ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/rxvt-unicode/src/urxvt.pm
(Generate patch)

Comparing rxvt-unicode/src/urxvt.pm (file contents):
Revision 1.50 by root, Sun Jan 8 00:11:38 2006 UTC vs.
Revision 1.116 by root, Fri Jan 20 16:18:07 2006 UTC

26thus must be encoded as UTF-8. 26thus must be encoded as UTF-8.
27 27
28Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where 28Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where
29scripts will be shared (but not enabled) for all terminals. 29scripts will be shared (but not enabled) for all terminals.
30 30
31=head2 Prepackaged Extensions 31=head1 PREPACKAGED EXTENSIONS
32 32
33This section describes the extensiosn delivered with this version. You can 33This section describes the extensions delivered with this release. You can
34find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>. 34find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>.
35 35
36You can activate them like this: 36You can activate them like this:
37 37
38 @@RXVT_NAME@@ -pe <extensionname> 38 @@RXVT_NAME@@ -pe <extensionname>
39 39
40Or by adding them to the resource for extensions loaded by default:
41
42 URxvt.perl-ext-common: default,automove-background,selection-autotransform
43
40=over 4 44=over 4
41 45
42=item selection 46=item selection (enabled by default)
43 47
44Intelligent selection. This extension tries to be more intelligent when 48(More) intelligent selection. This extension tries to be more intelligent
45the user extends selections (double-click). Right now, it tries to select 49when the user extends selections (double-click and further clicks). Right
46urls and complete shell-quoted arguments, which is very convenient, too, 50now, it tries to select words, urls and complete shell-quoted
47if your F<ls> supports C<--quoting-style=shell>. 51arguments, which is very convenient, too, if your F<ls> supports
52C<--quoting-style=shell>.
48 53
49It also offers the following bindable event: 54A double-click usually selects the word under the cursor, further clicks
55will enlarge the selection.
56
57The selection works by trying to match a number of regexes and displaying
58them in increasing order of length. You can add your own regexes by
59specifying resources of the form:
60
61 URxvt.selection.pattern-0: perl-regex
62 URxvt.selection.pattern-1: perl-regex
63 ...
64
65The index number (0, 1...) must not have any holes, and each regex must
66contain at least one pair of capturing parentheses, which will be used for
67the match. For example, the followign adds a regex that matches everything
68between two vertical bars:
69
70 URxvt.selection.pattern-0: \\|([^|]+)\\|
71
72You can look at the source of the selection extension to see more
73interesting uses, such as parsing a line from beginning to end.
74
75This extension also offers following bindable keyboard commands:
50 76
51=over 4 77=over 4
52 78
53=item rot13 79=item rot13
54 80
56 82
57 URxvt.keysym.C-M-r: perl:selection:rot13 83 URxvt.keysym.C-M-r: perl:selection:rot13
58 84
59=back 85=back
60 86
61=item digital-clock 87=item option-popup (enabled by default)
62 88
63Displays a digital clock using the built-in overlay. 89Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at
90runtime.
91
92=item selection-popup (enabled by default)
93
94Binds a popup menu to Ctrl-Button3 that lets you convert the selection
95text into various other formats/action (such as uri unescaping, perl
96evalution, web-browser starting etc.), depending on content.
97
98Other extensions can extend this popup menu by pushing a code reference
99onto C<@{ $term->{selection_popup_hook} }>, that is called whenever the
100popup is displayed.
101
102It's sole argument is the popup menu, which can be modified. The selection
103is in C<$_>, which can be used to decide wether to add something or not.
104It should either return nothing or a string and a code reference. The
105string will be used as button text and the code reference will be called
106when the button gets activated and should transform C<$_>.
107
108The following will add an entry C<a to b> that transforms all C<a>s in
109the selection to C<b>s, but only if the selection currently contains any
110C<a>s:
111
112 push @{ $self->{term}{selection_popup_hook} }, sub {
113 /a/ ? ("a to be" => sub { s/a/b/g }
114 : ()
115 };
116
117=item searchable-scrollback<hotkey> (enabled by default)
118
119Adds regex search functionality to the scrollback buffer, triggered
120by a hotkey (default: C<M-s>). While in search mode, normal terminal
121input/output is suspended and a regex is displayed at the bottom of the
122screen.
123
124Inputting characters appends them to the regex and continues incremental
125search. C<BackSpace> removes a character from the regex, C<Up> and C<Down>
126search upwards/downwards in the scrollback buffer, C<End> jumps to the
127bottom. C<Escape> leaves search mode and returns to the point where search
128was started, while C<Enter> or C<Return> stay at the current position and
129additionally stores the first match in the current line into the primary
130selection.
131
132=item selection-autotransform
133
134This selection allows you to do automatic transforms on a selection
135whenever a selection is made.
136
137It works by specifying perl snippets (most useful is a single C<s///>
138operator) that modify C<$_> as resources:
139
140 URxvt.selection-autotransform.0: transform
141 URxvt.selection-autotransform.1: transform
142 ...
143
144For example, the following will transform selections of the form
145C<filename:number>, often seen in compiler messages, into C<vi +$filename
146$word>:
147
148 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
149
150And this example matches the same,but replaces it with vi-commands you can
151paste directly into your (vi :) editor:
152
153 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/
154
155Of course, this can be modified to suit your needs and your editor :)
156
157To expand the example above to typical perl error messages ("XXX at
158FILENAME line YYY."), you need a slightly more elaborate solution:
159
160 URxvt.selection.pattern-0: ( at .*? line \\d+[,.])
161 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/
162
163The first line tells the selection code to treat the unchanging part of
164every error message as a selection pattern, and the second line transforms
165the message into vi commands to load the file.
166
167=item tabbed
168
169This transforms the terminal into a tabbar with additional terminals, that
170is, it implements what is commonly refered to as "tabbed terminal". The topmost line
171displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one
172button per tab.
173
174Clicking a button will activate that tab. Pressing B<Shift-Left> and
175B<Shift-Right> will switch to the tab left or right of the current one,
176while B<Shift-Down> creates a new tab.
64 177
65=item mark-urls 178=item mark-urls
66 179
67Uses per-line display filtering (C<on_line_update>) to underline urls. 180Uses per-line display filtering (C<on_line_update>) to underline urls and
181make them clickable. When middle-clicked, the program specified in the
182resource C<urlLauncher> (default C<x-www-browser>) will be started with
183the URL as first argument.
184
185=item automove-background
186
187This is basically a one-line extension that dynamically changes the background pixmap offset
188to the window position, in effect creating the same effect as pseudo transparency with
189a custom pixmap. No scaling is supported in this mode. Exmaple:
190
191 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background
68 192
69=item block-graphics-to-ascii 193=item block-graphics-to-ascii
70 194
71A not very useful example of filtering all text output to the terminal, 195A not very useful example of filtering all text output to the terminal,
72by replacing all line-drawing characters (U+2500 .. U+259F) by a 196by replacing all line-drawing characters (U+2500 .. U+259F) by a
73similar-looking ascii character. 197similar-looking ascii character.
74 198
199=item digital-clock
200
201Displays a digital clock using the built-in overlay.
202
75=item example-refresh-hooks 203=item example-refresh-hooks
76 204
77Displays a very simple digital clock in the upper right corner of the 205Displays a very simple digital clock in the upper right corner of the
78window. Illustrates overwriting the refresh callbacks to create your own 206window. Illustrates overwriting the refresh callbacks to create your own
79overlays or changes. 207overlays or changes.
80 208
209=item selection-pastebin
210
211This is a little rarely useful extension that Uploads the selection as
212textfile to a remote site (or does other things). (The implementation is
213not currently secure for use in a multiuser environment as it writes to
214F</tmp> directly.).
215
216It listens to the C<selection-pastebin:remote-pastebin> keyboard command,
217i.e.
218
219 URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin
220
221Pressing this combination runs a command with C<%> replaced by the name of
222the textfile. This command can be set via a resource:
223
224 URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
225
226And the default is likely not useful to anybody but the few people around
227here :)
228
229The name of the textfile is the hex encoded md5 sum of the selection, so
230the same content should lead to the same filename.
231
232After a successful upload the selection will be replaced by the text given
233in the C<selection-pastebin-url> resource (again, the % is the placeholder
234for the filename):
235
236 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
237
81=back 238=back
239
240=head1 API DOCUMENTATION
82 241
83=head2 General API Considerations 242=head2 General API Considerations
84 243
85All objects (such as terminals, time watchers etc.) are typical 244All objects (such as terminals, time watchers etc.) are typical
86reference-to-hash objects. The hash can be used to store anything you 245reference-to-hash objects. The hash can be used to store anything you
99=over 4 258=over 4
100 259
101=item $text 260=item $text
102 261
103Rxvt-unicodes special way of encoding text, where one "unicode" character 262Rxvt-unicodes special way of encoding text, where one "unicode" character
104always represents one screen cell. See L<row_t> for a discussion of this format. 263always represents one screen cell. See L<ROW_t> for a discussion of this format.
105 264
106=item $string 265=item $string
107 266
108A perl text string, with an emphasis on I<text>. It can store all unicode 267A perl text string, with an emphasis on I<text>. It can store all unicode
109characters and is to be distinguished with text encoded in a specific 268characters and is to be distinguished with text encoded in a specific
114Either binary data or - more common - a text string encoded in a 273Either binary data or - more common - a text string encoded in a
115locale-specific way. 274locale-specific way.
116 275
117=back 276=back
118 277
278=head2 Extension Objects
279
280Very perl extension is a perl class. A separate perl object is created
281for each terminal and each extension and passed as the first parameter to
282hooks. So extensions can use their C<$self> object without having to think
283about other extensions, with the exception of methods and members that
284begin with an underscore character C<_>: these are reserved for internal
285use.
286
287Although it isn't a C<urxvt::term> object, you can call all methods of the
288C<urxvt::term> class on this object.
289
290It has the following methods and data members:
291
292=over 4
293
294=item $urxvt_term = $self->{term}
295
296Returns the C<urxvt::term> object associated with this instance of the
297extension. This member I<must not> be changed in any way.
298
299=item $self->enable ($hook_name => $cb, [$hook_name => $cb..])
300
301Dynamically enable the given hooks (named without the C<on_> prefix) for
302this extension, replacing any previous hook. This is useful when you want
303to overwrite time-critical hooks only temporarily.
304
305=item $self->disable ($hook_name[, $hook_name..])
306
307Dynamically disable the given hooks.
308
309=back
310
119=head2 Hooks 311=head2 Hooks
120 312
121The following subroutines can be declared in extension files, and will be 313The following subroutines can be declared in extension files, and will be
122called whenever the relevant event happens. 314called whenever the relevant event happens.
123 315
124The first argument passed to them is an object private to each terminal 316The first argument passed to them is an extension oject as described in
125and extension package. You can call all C<urxvt::term> methods on it, but 317the in the C<Extension Objects> section.
126its not a real C<urxvt::term> object. Instead, the real C<urxvt::term>
127object that is shared between all packages is stored in the C<term>
128member. It is, however, blessed intot he package of the extension script,
129so for all practical purposes you can treat an extension script as a class.
130 318
131All of them must return a boolean value. If it is true, then the event 319B<All> of these hooks must return a boolean value. If any of the called
132counts as being I<consumed>, and the invocation of other hooks is skipped, 320hooks returns true, then the event counts as being I<consumed>, and the
133and the relevant action might not be carried out by the C++ code. 321relevant action might not be carried out by the C++ code.
134 322
135When in doubt, return a false value (preferably C<()>). 323I<< When in doubt, return a false value (preferably C<()>). >>
136 324
137=over 4 325=over 4
138 326
139=item on_init $term 327=item on_init $term
140 328
141Called after a new terminal object has been initialized, but before 329Called after a new terminal object has been initialized, but before
142windows are created or the command gets run. Most methods are unsafe to 330windows are created or the command gets run. Most methods are unsafe to
143call or deliver senseless data, as terminal size and other characteristics 331call or deliver senseless data, as terminal size and other characteristics
144have not yet been determined. You can safely query and change resources, 332have not yet been determined. You can safely query and change resources
145though. 333and options, though. For many purposes the C<on_start> hook is a better
334place.
335
336=item on_start $term
337
338Called at the very end of initialisation of a new terminal, just before
339trying to map (display) the toplevel and returning to the mainloop.
340
341=item on_destroy $term
342
343Called whenever something tries to destroy terminal, before doing anything
344yet. If this hook returns true, then destruction is skipped, but this is
345rarely a good idea.
146 346
147=item on_reset $term 347=item on_reset $term
148 348
149Called after the screen is "reset" for any reason, such as resizing or 349Called after the screen is "reset" for any reason, such as resizing or
150control sequences. Here is where you can react on changes to size-related 350control sequences. Here is where you can react on changes to size-related
151variables. 351variables.
152 352
153=item on_start $term 353=item on_child_start $term, $pid
154 354
155Called at the very end of initialisation of a new terminal, just before 355Called just after the child process has been C<fork>ed.
156returning to the mainloop. 356
357=item on_child_exit $term, $status
358
359Called just after the child process has exited. C<$status> is the status
360from C<waitpid>.
157 361
158=item on_sel_make $term, $eventtime 362=item on_sel_make $term, $eventtime
159 363
160Called whenever a selection has been made by the user, but before the 364Called whenever a selection has been made by the user, but before the
161selection text is copied, so changes to the beginning, end or type of the 365selection text is copied, so changes to the beginning, end or type of the
175=item on_sel_extend $term 379=item on_sel_extend $term
176 380
177Called whenever the user tries to extend the selection (e.g. with a double 381Called whenever the user tries to extend the selection (e.g. with a double
178click) and is either supposed to return false (normal operation), or 382click) and is either supposed to return false (normal operation), or
179should extend the selection itelf and return true to suppress the built-in 383should extend the selection itelf and return true to suppress the built-in
180processing. 384processing. This can happen multiple times, as long as the callback
385returns true, it will be called on every further click by the user and is
386supposed to enlarge the selection more and more, if possible.
181 387
182See the F<selection> example extension. 388See the F<selection> example extension.
183 389
184=item on_view_change $term, $offset 390=item on_view_change $term, $offset
185 391
194than the scroll back buffer or the terminal. 400than the scroll back buffer or the terminal.
195 401
196It is called before lines are scrolled out (so rows 0 .. min ($lines - 1, 402It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
197$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total 403$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
198number of lines that will be in the scrollback buffer. 404number of lines that will be in the scrollback buffer.
199
200=item on_tty_activity $term *NYI*
201
202Called whenever the program(s) running in the urxvt window send output.
203 405
204=item on_osc_seq $term, $string 406=item on_osc_seq $term, $string
205 407
206Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 408Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
207operating system command) is processed. Cursor position and other state 409operating system command) is processed. Cursor position and other state
220can filter/change and output the text yourself by returning a true value 422can filter/change and output the text yourself by returning a true value
221and calling C<< $term->scr_add_lines >> yourself. Please note that this 423and calling C<< $term->scr_add_lines >> yourself. Please note that this
222might be very slow, however, as your hook is called for B<all> text being 424might be very slow, however, as your hook is called for B<all> text being
223output. 425output.
224 426
427=item on_tt_write $term, $octets
428
429Called whenever some data is written to the tty/pty and can be used to
430suppress or filter tty input.
431
225=item on_line_update $term, $row 432=item on_line_update $term, $row
226 433
227Called whenever a line was updated or changed. Can be used to filter 434Called whenever a line was updated or changed. Can be used to filter
228screen output (e.g. underline urls or other useless stuff). Only lines 435screen output (e.g. underline urls or other useless stuff). Only lines
229that are being shown will be filtered, and, due to performance reasons, 436that are being shown will be filtered, and, due to performance reasons,
251 458
252Called whenever the user presses a key combination that has a 459Called whenever the user presses a key combination that has a
253C<perl:string> action bound to it (see description of the B<keysym> 460C<perl:string> action bound to it (see description of the B<keysym>
254resource in the @@RXVT_NAME@@(1) manpage). 461resource in the @@RXVT_NAME@@(1) manpage).
255 462
463=item on_x_event $term, $event
464
465Called on every X event received on the vt window (and possibly other
466windows). Should only be used as a last resort. Most event structure
467members are not passed.
468
256=item on_focus_in $term 469=item on_focus_in $term
257 470
258Called whenever the window gets the keyboard focus, before rxvt-unicode 471Called whenever the window gets the keyboard focus, before rxvt-unicode
259does focus in processing. 472does focus in processing.
260 473
261=item on_focus_out $term 474=item on_focus_out $term
262 475
263Called wheneever the window loses keyboard focus, before rxvt-unicode does 476Called wheneever the window loses keyboard focus, before rxvt-unicode does
264focus out processing. 477focus out processing.
265 478
479=item on_configure_notify $term, $event
480
266=item on_key_press $term, $event, $octets 481=item on_key_press $term, $event, $keysym, $octets
267 482
268=item on_key_release $term, $event 483=item on_key_release $term, $event, $keysym
269 484
270=item on_button_press $term, $event 485=item on_button_press $term, $event
271 486
272=item on_button_release $term, $event 487=item on_button_release $term, $event
273 488
287C<on_key_press> additionally receives the string rxvt-unicode would 502C<on_key_press> additionally receives the string rxvt-unicode would
288output, if any, in locale-specific encoding. 503output, if any, in locale-specific encoding.
289 504
290subwindow. 505subwindow.
291 506
507=item on_client_message $term, $event
508
509=item on_wm_protocols $term, $event
510
511=item on_wm_delete_window $term, $event
512
513Called when various types of ClientMessage events are received (all with
514format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
515
292=back 516=back
293 517
518=cut
519
520package urxvt;
521
522use utf8;
523use strict;
524use Carp ();
525use Scalar::Util ();
526use List::Util ();
527
528our $VERSION = 1;
529our $TERM;
530our @TERM_INIT;
531our @TERM_EXT;
532our @HOOKNAME;
533our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
534our %OPTION;
535
536our $LIBDIR;
537our $RESNAME;
538our $RESCLASS;
539our $RXVTNAME;
540
294=head2 Variables in the C<urxvt> Package 541=head2 Variables in the C<urxvt> Package
295 542
296=over 4 543=over 4
544
545=item $urxvt::LIBDIR
546
547The rxvt-unicode library directory, where, among other things, the perl
548modules and scripts are stored.
549
550=item $urxvt::RESCLASS, $urxvt::RESCLASS
551
552The resource class and name rxvt-unicode uses to look up X resources.
553
554=item $urxvt::RXVTNAME
555
556The basename of the installed binaries, usually C<urxvt>.
297 557
298=item $urxvt::TERM 558=item $urxvt::TERM
299 559
300The current terminal. This variable stores the current C<urxvt::term> 560The current terminal. This variable stores the current C<urxvt::term>
301object, whenever a callback/hook is executing. 561object, whenever a callback/hook is executing.
302 562
563=item @urxvt::TERM_INIT
564
565All coderefs in this array will be called as methods of the next newly
566created C<urxvt::term> object (during the C<on_init> phase). The array
567gets cleared before the codereferences that were in it are being executed,
568so coderefs can push themselves onto it again if they so desire.
569
570This complements to the perl-eval commandline option, but gets executed
571first.
572
573=item @urxvt::TERM_EXT
574
575Works similar to C<@TERM_INIT>, but contains perl package/class names, which
576get registered as normal extensions after calling the hooks in C<@TERM_INIT>
577but before other extensions. Gets cleared just like C<@TERM_INIT>.
578
303=back 579=back
304 580
305=head2 Functions in the C<urxvt> Package 581=head2 Functions in the C<urxvt> Package
306 582
307=over 4 583=over 4
308
309=item $term = new urxvt [arg...]
310
311Creates a new terminal, very similar as if you had started it with
312C<system $binfile, arg...>. Croaks (and probably outputs an error message)
313if the new instance couldn't be created. Returns C<undef> if the new
314instance didn't initialise perl, and the terminal object otherwise. The
315C<init> and C<start> hooks will be called during the call.
316 584
317=item urxvt::fatal $errormessage 585=item urxvt::fatal $errormessage
318 586
319Fatally aborts execution with the given error message. Avoid at all 587Fatally aborts execution with the given error message. Avoid at all
320costs! The only time this is acceptable is when the terminal process 588costs! The only time this is acceptable is when the terminal process
327that calls this function. 595that calls this function.
328 596
329Using this function has the advantage that its output ends up in the 597Using this function has the advantage that its output ends up in the
330correct place, e.g. on stderr of the connecting urxvtc client. 598correct place, e.g. on stderr of the connecting urxvtc client.
331 599
600Messages have a size limit of 1023 bytes currently.
601
332=item $time = urxvt::NOW 602=item $time = urxvt::NOW
333 603
334Returns the "current time" (as per the event loop). 604Returns the "current time" (as per the event loop).
335 605
336=item urxvt::CurrentTime 606=item urxvt::CurrentTime
337 607
338=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, 608=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
339Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, 609Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
340Button4Mask, Button5Mask, AnyModifier 610Button4Mask, Button5Mask, AnyModifier
341 611
612=item urxvt::NoEventMask, KeyPressMask, KeyReleaseMask,
613ButtonPressMask, ButtonReleaseMask, EnterWindowMask, LeaveWindowMask,
614PointerMotionMask, PointerMotionHintMask, Button1MotionMask, Button2MotionMask,
615Button3MotionMask, Button4MotionMask, Button5MotionMask, ButtonMotionMask,
616KeymapStateMask, ExposureMask, VisibilityChangeMask, StructureNotifyMask,
617ResizeRedirectMask, SubstructureNotifyMask, SubstructureRedirectMask,
618FocusChangeMask, PropertyChangeMask, ColormapChangeMask, OwnerGrabButtonMask
619
620=item urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify,
621EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose,
622GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify, DestroyNotify,
623UnmapNotify, MapNotify, MapRequest, ReparentNotify, ConfigureNotify,
624ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify,
625CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest,
626SelectionNotify, ColormapNotify, ClientMessage, MappingNotify
627
342Various constants for use in X events. 628Various constants for use in X calls and event processing.
343 629
344=back 630=back
345 631
346=head2 RENDITION 632=head2 RENDITION
347 633
374 660
375=item $background = urxvt::GET_BASEBG $rend 661=item $background = urxvt::GET_BASEBG $rend
376 662
377Return the foreground/background colour index, respectively. 663Return the foreground/background colour index, respectively.
378 664
379=item $rend = urxvt::SET_FGCOLOR ($rend, $new_colour) 665=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
380 666
381=item $rend = urxvt::SET_BGCOLOR ($rend, $new_colour) 667=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
382 668
383Replace the foreground/background colour in the rendition mask with the 669Replace the foreground/background colour in the rendition mask with the
384specified one. 670specified one.
385 671
386=item $value = urxvt::GET_CUSTOM ($rend) 672=item $value = urxvt::GET_CUSTOM $rend
387 673
388Return the "custom" value: Every rendition has 5 bits for use by 674Return the "custom" value: Every rendition has 5 bits for use by
389extensions. They can be set and changed as you like and are initially 675extensions. They can be set and changed as you like and are initially
390zero. 676zero.
391 677
392=item $rend = urxvt::SET_CUSTOM ($rend, $new_value) 678=item $rend = urxvt::SET_CUSTOM $rend, $new_value
393 679
394Change the custom value. 680Change the custom value.
395 681
396=back 682=back
397 683
398=cut 684=cut
399 685
400package urxvt;
401
402use utf8;
403use strict;
404use Scalar::Util ();
405use List::Util ();
406
407our $TERM;
408our @HOOKNAME;
409our %OPTION;
410our $LIBDIR;
411
412BEGIN { 686BEGIN {
413 urxvt->bootstrap;
414
415 # overwrite perl's warn 687 # overwrite perl's warn
416 *CORE::GLOBAL::warn = sub { 688 *CORE::GLOBAL::warn = sub {
417 my $msg = join "", @_; 689 my $msg = join "", @_;
418 $msg .= "\n" 690 $msg .= "\n"
419 unless $msg =~ /\n$/; 691 unless $msg =~ /\n$/;
420 urxvt::warn ($msg); 692 urxvt::warn ($msg);
421 }; 693 };
422} 694}
423 695
424my @hook_count;
425my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 696my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
426 697
427sub verbose { 698sub verbose {
428 my ($level, $msg) = @_; 699 my ($level, $msg) = @_;
429 warn "$msg\n" if $level <= $verbosity; 700 warn "$msg\n" if $level <= $verbosity;
430} 701}
431 702
432# find on_xxx subs in the package and register them
433# as hooks
434sub register_package($) {
435 my ($pkg) = @_;
436
437 for my $htype (0.. $#HOOKNAME) {
438 my $name = $HOOKNAME[$htype];
439
440 my $ref = $pkg->can ("on_" . lc $name)
441 or next;
442
443 $TERM->{_hook}[$htype]{$pkg} = $ref;
444 $hook_count[$htype]++
445 or set_should_invoke $htype, 1;
446 }
447}
448
449my $extension_pkg = "extension0000";
450my %extension_pkg; 703my %extension_pkg;
451 704
452# load a single script into its own package, once only 705# load a single script into its own package, once only
453sub extension_package($) { 706sub extension_package($) {
454 my ($path) = @_; 707 my ($path) = @_;
455 708
456 $extension_pkg{$path} ||= do { 709 $extension_pkg{$path} ||= do {
457 my $pkg = "urxvt::" . ($extension_pkg++); 710 $path =~ /([^\/\\]+)$/;
711 my $pkg = $1;
712 $pkg =~ s/[^[:word:]]/_/g;
713 $pkg = "urxvt::ext::$pkg";
458 714
459 verbose 3, "loading extension '$path' into package '$pkg'"; 715 verbose 3, "loading extension '$path' into package '$pkg'";
460 716
461 open my $fh, "<:raw", $path 717 open my $fh, "<:raw", $path
462 or die "$path: $!"; 718 or die "$path: $!";
463 719
720 my $source =
464 my $source = "package $pkg; use strict; use utf8;\n" 721 "package $pkg; use strict; use utf8;\n"
465 . "use base urxvt::term::proxy::;\n"
466 . "#line 1 \"$path\"\n{\n" 722 . "#line 1 \"$path\"\n{\n"
467 . (do { local $/; <$fh> }) 723 . (do { local $/; <$fh> })
468 . "\n};\n1"; 724 . "\n};\n1";
469 725
726 eval $source
470 eval $source or die "$path: $@"; 727 or die "$path: $@";
471 728
472 $pkg 729 $pkg
473 } 730 }
474} 731}
475 732
481 my $htype = shift; 738 my $htype = shift;
482 739
483 if ($htype == 0) { # INIT 740 if ($htype == 0) { # INIT
484 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 741 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
485 742
486 my %want_ext; 743 my %ext_arg;
487 744
745 {
746 my @init = @TERM_INIT;
747 @TERM_INIT = ();
748 $_->($TERM) for @init;
749 my @pkg = @TERM_EXT;
750 @TERM_EXT = ();
751 $TERM->register_package ($_) for @pkg;
752 }
753
488 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) { 754 for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
489 if ($_ eq "default") { 755 if ($_ eq "default") {
490 $want_ext{$_}++ for qw(selection); 756 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback);
491 } elsif (/-(.*)/) { 757 } elsif (/^-(.*)$/) {
492 delete $want_ext{$1}; 758 delete $ext_arg{$1};
759 } elsif (/^([^<]+)<(.*)>$/) {
760 push @{ $ext_arg{$1} }, $2;
493 } else { 761 } else {
494 $want_ext{$_}++; 762 $ext_arg{$_} ||= [];
495 } 763 }
496 } 764 }
497 765
498 for my $ext (keys %want_ext) { 766 while (my ($ext, $argv) = each %ext_arg) {
499 my @files = grep -f $_, map "$_/$ext", @dirs; 767 my @files = grep -f $_, map "$_/$ext", @dirs;
500 768
501 if (@files) { 769 if (@files) {
502 register_package extension_package $files[0]; 770 $TERM->register_package (extension_package $files[0], $argv);
503 } else { 771 } else {
504 warn "perl extension '$ext' not found in perl library search path\n"; 772 warn "perl extension '$ext' not found in perl library search path\n";
505 } 773 }
506 } 774 }
775
776 eval "#line 1 \"--perl-eval resource/argument\"\n" . $TERM->resource ("perl_eval");
777 warn $@ if $@;
507 } 778 }
508 779
509 $retval = undef; 780 $retval = undef;
510 781
511 if (my $cb = $TERM->{_hook}[$htype]) { 782 if (my $cb = $TERM->{_hook}[$htype]) {
513 if $verbosity >= 10; 784 if $verbosity >= 10;
514 785
515 keys %$cb; 786 keys %$cb;
516 787
517 while (my ($pkg, $cb) = each %$cb) { 788 while (my ($pkg, $cb) = each %$cb) {
518 eval { 789 my $retval_ = eval { $cb->($TERM->{_pkg}{$pkg}, @_) };
519 $retval = $cb->( 790 $retval ||= $retval_;
520 $TERM->{_pkg}{$pkg} ||= do {
521 my $proxy = bless { }, $pkg;
522 Scalar::Util::weaken ($proxy->{term} = $TERM);
523 $proxy
524 },
525 @_,
526 ) and last;
527 };
528 warn $@ if $@;#d#
529 }
530 }
531 791
532 if ($htype == 1) { # DESTROY 792 if ($@) {
533 # remove hooks if unused 793 $TERM->ungrab; # better to lose the grab than the session
534 if (my $hook = $TERM->{_hook}) { 794 warn $@;
535 for my $htype (0..$#$hook) {
536 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
537 or set_should_invoke $htype, 0;
538 } 795 }
539 } 796 }
540 797
798 verbose 11, "$HOOKNAME[$htype] returning <$retval>"
799 if $verbosity >= 11;
800 }
801
802 if ($htype == 1) { # DESTROY
541 # clear package objects 803 # clear package objects
542 %$_ = () for values %{ $TERM->{_pkg} }; 804 %$_ = () for values %{ $TERM->{_pkg} };
543 805
544 # clear package 806 # clear package
545 %$TERM = (); 807 %$TERM = ();
546 } 808 }
547 809
548 $retval 810 $retval
549} 811}
550 812
551sub urxvt::term::proxy::AUTOLOAD { 813# urxvt::term::extension
552 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/ 814
815package urxvt::term::extension;
816
817sub enable {
818 my ($self, %hook) = @_;
819 my $pkg = $self->{_pkg};
820
821 while (my ($name, $cb) = each %hook) {
822 my $htype = $HOOKTYPE{uc $name};
823 defined $htype
824 or Carp::croak "unsupported hook type '$name'";
825
826 $self->set_should_invoke ($htype, +1)
827 unless exists $self->{term}{_hook}[$htype]{$pkg};
828
829 $self->{term}{_hook}[$htype]{$pkg} = $cb;
830 }
831}
832
833sub disable {
834 my ($self, @hook) = @_;
835 my $pkg = $self->{_pkg};
836
837 for my $name (@hook) {
838 my $htype = $HOOKTYPE{uc $name};
839 defined $htype
840 or Carp::croak "unsupported hook type '$name'";
841
842 $self->set_should_invoke ($htype, -1)
843 if delete $self->{term}{_hook}[$htype]{$pkg};
844 }
845}
846
847our $AUTOLOAD;
848
849sub AUTOLOAD {
850 $AUTOLOAD =~ /:([^:]+)$/
553 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable"; 851 or die "FATAL: \$AUTOLOAD '$AUTOLOAD' unparsable";
554 852
555 eval qq{ 853 eval qq{
556 sub $urxvt::term::proxy::AUTOLOAD { 854 sub $AUTOLOAD {
557 my \$proxy = shift; 855 my \$proxy = shift;
558 \$proxy->{term}->$1 (\@_) 856 \$proxy->{term}->$1 (\@_)
559 } 857 }
560 1 858 1
561 } or die "FATAL: unable to compile method forwarder: $@"; 859 } or die "FATAL: unable to compile method forwarder: $@";
562 860
563 goto &$urxvt::term::proxy::AUTOLOAD; 861 goto &$AUTOLOAD;
564} 862}
863
864sub DESTROY {
865 # nop
866}
867
868# urxvt::destroy_hook
565 869
566sub urxvt::destroy_hook::DESTROY { 870sub urxvt::destroy_hook::DESTROY {
567 ${$_[0]}->(); 871 ${$_[0]}->();
568} 872}
569 873
570sub urxvt::destroy_hook(&) { 874sub urxvt::destroy_hook(&) {
571 bless \shift, urxvt::destroy_hook:: 875 bless \shift, urxvt::destroy_hook::
572} 876}
573 877
878package urxvt::anyevent;
879
880=head2 The C<urxvt::anyevent> Class
881
882The sole purpose of this class is to deliver an interface to the
883C<AnyEvent> module - any module using it will work inside urxvt without
884further programming. The only exception is that you cannot wait on
885condition variables, but non-blocking condvar use is ok. What this means
886is that you cannot use blocking APIs, but the non-blocking variant should
887work.
888
889=cut
890
891our $VERSION = 1;
892
893$INC{"urxvt/anyevent.pm"} = 1; # mark us as there
894push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
895
896sub timer {
897 my ($class, %arg) = @_;
898
899 my $cb = $arg{cb};
900
901 urxvt::timer
902 ->new
903 ->start (urxvt::NOW + $arg{after})
904 ->cb (sub {
905 $_[0]->stop; # need to cancel manually
906 $cb->();
907 })
908}
909
910sub io {
911 my ($class, %arg) = @_;
912
913 my $cb = $arg{cb};
914
915 bless [$arg{fh}, urxvt::iow
916 ->new
917 ->fd (fileno $arg{fh})
918 ->events (($arg{poll} =~ /r/ ? 1 : 0)
919 | ($arg{poll} =~ /w/ ? 2 : 0))
920 ->start
921 ->cb (sub {
922 $cb->(($_[1] & 1 ? 'r' : '')
923 . ($_[1] & 2 ? 'w' : ''));
924 })],
925 urxvt::anyevent::
926}
927
928sub DESTROY {
929 $_[0][1]->stop;
930}
931
932sub condvar {
933 bless \my $flag, urxvt::anyevent::condvar::
934}
935
936sub urxvt::anyevent::condvar::broadcast {
937 ${$_[0]}++;
938}
939
940sub urxvt::anyevent::condvar::wait {
941 unless (${$_[0]}) {
942 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API";
943 }
944}
945
946package urxvt::term;
947
574=head2 The C<urxvt::term> Class 948=head2 The C<urxvt::term> Class
575 949
576=over 4 950=over 4
577 951
952=cut
953
954# find on_xxx subs in the package and register them
955# as hooks
956sub register_package {
957 my ($self, $pkg, $argv) = @_;
958
959 no strict 'refs';
960
961 urxvt::verbose 6, "register package $pkg to $self";
962
963 @{"$pkg\::ISA"} = urxvt::term::extension::;
964
965 my $proxy = bless {
966 _pkg => $pkg,
967 argv => $argv,
968 }, $pkg;
969 Scalar::Util::weaken ($proxy->{term} = $self);
970
971 $self->{_pkg}{$pkg} = $proxy;
972
973 for my $name (@HOOKNAME) {
974 if (my $ref = $pkg->can ("on_" . lc $name)) {
975 $proxy->enable ($name => $ref);
976 }
977 }
978}
979
980=item $term = new urxvt::term $envhashref, $rxvtname, [arg...]
981
982Creates a new terminal, very similar as if you had started it with system
983C<$rxvtname, arg...>. C<$envhashref> must be a reference to a C<%ENV>-like
984hash which defines the environment of the new terminal.
985
986Croaks (and probably outputs an error message) if the new instance
987couldn't be created. Returns C<undef> if the new instance didn't
988initialise perl, and the terminal object otherwise. The C<init> and
989C<start> hooks will be called during this call.
990
991=cut
992
993sub new {
994 my ($class, $env, @args) = @_;
995
996 _new ([ map "$_=$env->{$_}", keys %$env ], @args);
997}
998
578=item $term->destroy 999=item $term->destroy
579 1000
580Destroy the terminal object (close the window, free resources etc.). 1001Destroy the terminal object (close the window, free resources
1002etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event
1003watchers (timers, io watchers) are still active.
1004
1005=item $term->exec_async ($cmd[, @args])
1006
1007Works like the combination of the C<fork>/C<exec> builtins, which executes
1008("starts") programs in the background. This function takes care of setting
1009the user environment before exec'ing the command (e.g. C<PATH>) and should
1010be preferred over explicit calls to C<exec> or C<system>.
1011
1012Returns the pid of the subprocess or C<undef> on error.
1013
1014=cut
1015
1016sub exec_async {
1017 my $self = shift;
1018
1019 my $pid = fork;
1020
1021 return $pid
1022 if !defined $pid or $pid;
1023
1024 %ENV = %{ $self->env };
1025
1026 exec @_;
1027 urxvt::_exit 255;
1028}
581 1029
582=item $isset = $term->option ($optval[, $set]) 1030=item $isset = $term->option ($optval[, $set])
583 1031
584Returns true if the option specified by C<$optval> is enabled, and 1032Returns true if the option specified by C<$optval> is enabled, and
585optionally change it. All option values are stored by name in the hash 1033optionally change it. All option values are stored by name in the hash
588Here is a a likely non-exhaustive list of option names, please see the 1036Here is a a likely non-exhaustive list of option names, please see the
589source file F</src/optinc.h> to see the actual list: 1037source file F</src/optinc.h> to see the actual list:
590 1038
591 borderLess console cursorBlink cursorUnderline hold iconic insecure 1039 borderLess console cursorBlink cursorUnderline hold iconic insecure
592 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 1040 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
593 pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating 1041 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
594 scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer 1042 scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput
595 secondaryScreen secondaryScroll skipBuiltinGlyphs transparent 1043 scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs
596 tripleclickwords utmpInhibit visualBell 1044 transparent tripleclickwords utmpInhibit visualBell
597 1045
598=item $value = $term->resource ($name[, $newval]) 1046=item $value = $term->resource ($name[, $newval])
599 1047
600Returns the current resource value associated with a given name and 1048Returns the current resource value associated with a given name and
601optionally sets a new value. Setting values is most useful in the C<init> 1049optionally sets a new value. Setting values is most useful in the C<init>
618 1066
619 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1067 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
620 borderLess color cursorBlink cursorUnderline cutchars delete_key 1068 borderLess color cursorBlink cursorUnderline cutchars delete_key
621 display_name embed ext_bwidth fade font geometry hold iconName 1069 display_name embed ext_bwidth fade font geometry hold iconName
622 imFont imLocale inputMethod insecure int_bwidth intensityStyles 1070 imFont imLocale inputMethod insecure int_bwidth intensityStyles
623 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier 1071 italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier
624 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2 1072 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
625 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 1073 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
626 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 1074 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
627 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 1075 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
628 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 1076 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
629 shade term_name title transparent transparent_all tripleclickwords 1077 secondaryScreen secondaryScroll selectstyle shade term_name title
630 utmpInhibit visualBell 1078 transient_for transparent transparent_all tripleclickwords utmpInhibit
1079 visualBell
631 1080
632=cut 1081=cut
633 1082
634sub urxvt::term::resource($$;$) { 1083sub resource($$;$) {
635 my ($self, $name) = (shift, shift); 1084 my ($self, $name) = (shift, shift);
636 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 1085 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
637 &urxvt::term::_resource 1086 &urxvt::term::_resource
638} 1087}
639 1088
1089=item $value = $term->x_resource ($pattern)
1090
1091Returns the X-Resource for the given pattern, excluding the program or
1092class name, i.e. C<< $term->x_resource ("boldFont") >> should return the
1093same value as used by this instance of rxvt-unicode. Returns C<undef> if no
1094resource with that pattern exists.
1095
1096This method should only be called during the C<on_start> hook, as there is
1097only one resource database per display, and later invocations might return
1098the wrong resources.
1099
1100=item $success = $term->parse_keysym ($keysym_spec, $command_string)
1101
1102Adds a keymap translation exactly as specified via a resource. See the
1103C<keysym> resource in the @@RXVT_NAME@@(1) manpage.
1104
640=item $rend = $term->rstyle ([$new_rstyle]) 1105=item $rend = $term->rstyle ([$new_rstyle])
641 1106
642Return and optionally change the current rendition. Text that is output by 1107Return and optionally change the current rendition. Text that is output by
643the terminal application will use this style. 1108the terminal application will use this style.
644 1109
654=item ($row, $col) = $term->selection_end ([$row, $col]) 1119=item ($row, $col) = $term->selection_end ([$row, $col])
655 1120
656Return the current values of the selection mark, begin or end positions, 1121Return the current values of the selection mark, begin or end positions,
657and optionally set them to new values. 1122and optionally set them to new values.
658 1123
1124=item $term->selection_make ($eventtime[, $rectangular])
1125
1126Tries to make a selection as set by C<selection_beg> and
1127C<selection_end>. If C<$rectangular> is true (default: false), a
1128rectangular selection will be made. This is the prefered function to make
1129a selection.
1130
659=item $success = $term->selection_grab ($eventtime) 1131=item $success = $term->selection_grab ($eventtime)
660 1132
661Try to request the primary selection from the server (for example, as set 1133Try to request the primary selection text from the server (for example, as
662by the next method). 1134set by the next method). No visual feedback will be given. This function
1135is mostly useful from within C<on_sel_grab> hooks.
663 1136
664=item $oldtext = $term->selection ([$newtext]) 1137=item $oldtext = $term->selection ([$newtext])
665 1138
666Return the current selection text and optionally replace it by C<$newtext>. 1139Return the current selection text and optionally replace it by C<$newtext>.
667 1140
668#=item $term->overlay ($x, $y, $text) 1141=item $term->overlay_simple ($x, $y, $text)
669# 1142
670#Create a simple multi-line overlay box. See the next method for details. 1143Create a simple multi-line overlay box. See the next method for details.
671# 1144
672#=cut 1145=cut
673# 1146
674#sub urxvt::term::scr_overlay { 1147sub overlay_simple {
675# my ($self, $x, $y, $text) = @_; 1148 my ($self, $x, $y, $text) = @_;
676# 1149
677# my @lines = split /\n/, $text; 1150 my @lines = split /\n/, $text;
678# 1151
679# my $w = 0; 1152 my $w = List::Util::max map $self->strwidth ($_), @lines;
680# for (map $self->strwidth ($_), @lines) { 1153
681# $w = $_ if $w < $_;
682# }
683#
684# $self->scr_overlay_new ($x, $y, $w, scalar @lines); 1154 my $overlay = $self->overlay ($x, $y, $w, scalar @lines);
685# $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 1155 $overlay->set (0, $_, $lines[$_]) for 0.. $#lines;
686#} 1156
1157 $overlay
1158}
687 1159
688=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 1160=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
689 1161
690Create a new (empty) overlay at the given position with the given 1162Create a new (empty) overlay at the given position with the given
691width/height. C<$rstyle> defines the initial rendition style 1163width/height. C<$rstyle> defines the initial rendition style
726C<$event> I<must> be the event causing the menu to pop up (a button event, 1198C<$event> I<must> be the event causing the menu to pop up (a button event,
727currently). 1199currently).
728 1200
729=cut 1201=cut
730 1202
731sub urxvt::term::popup { 1203sub popup {
732 my ($self, $event) = @_; 1204 my ($self, $event) = @_;
733 1205
734 $self->grab ($event->{time}, 1) 1206 $self->grab ($event->{time}, 1)
735 or return; 1207 or return;
736 1208
758 1230
759=item $string = $term->locale_decode ($octets) 1231=item $string = $term->locale_decode ($octets)
760 1232
761Convert the given locale-encoded octets into a perl string. 1233Convert the given locale-encoded octets into a perl string.
762 1234
1235=item $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
1236
1237XORs the rendition values in the given span with the provided value
1238(default: C<RS_RVid>), which I<MUST NOT> contain font styles. Useful in
1239refresh hooks to provide effects similar to the selection.
1240
1241=item $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, $rstyle2]])
1242
1243Similar to C<scr_xor_span>, but xors a rectangle instead. Trailing
1244whitespace will additionally be xored with the C<$rstyle2>, which defaults
1245to C<RS_RVid | RS_Uline>, which removes reverse video again and underlines
1246it instead. Both styles I<MUST NOT> contain font styles.
1247
1248=item $term->scr_bell
1249
1250Ring the bell!
1251
763=item $term->scr_add_lines ($string) 1252=item $term->scr_add_lines ($string)
764 1253
765Write the given text string to the screen, as if output by the application 1254Write the given text string to the screen, as if output by the application
766running inside the terminal. It may not contain command sequences (escape 1255running inside the terminal. It may not contain command sequences (escape
767codes), but is free to use line feeds, carriage returns and tabs. The 1256codes), but is free to use line feeds, carriage returns and tabs. The
781 1270
782Write the octets given in C<$data> to the tty (i.e. as program input). To 1271Write the octets given in C<$data> to the tty (i.e. as program input). To
783pass characters instead of octets, you should convert your strings first 1272pass characters instead of octets, you should convert your strings first
784to the locale-specific encoding using C<< $term->locale_encode >>. 1273to the locale-specific encoding using C<< $term->locale_encode >>.
785 1274
1275=item $old_events = $term->pty_ev_events ([$new_events])
1276
1277Replaces the event mask of the pty watcher by the given event mask. Can
1278be used to suppress input and output handling to the pty/tty. See the
1279description of C<< urxvt::timer->events >>. Make sure to always restore
1280the previous value.
1281
786=item $windowid = $term->parent 1282=item $windowid = $term->parent
787 1283
788Return the window id of the toplevel window. 1284Return the window id of the toplevel window.
789 1285
790=item $windowid = $term->vt 1286=item $windowid = $term->vt
791 1287
792Return the window id of the terminal window. 1288Return the window id of the terminal window.
793 1289
1290=item $term->vt_emask_add ($x_event_mask)
1291
1292Adds the specified events to the vt event mask. Useful e.g. when you want
1293to receive pointer events all the times:
1294
1295 $term->vt_emask_add (urxvt::PointerMotionMask);
1296
794=item $window_width = $term->width 1297=item $window_width = $term->width
795 1298
796=item $window_height = $term->height 1299=item $window_height = $term->height
797 1300
798=item $font_width = $term->fwidth 1301=item $font_width = $term->fwidth
811 1314
812=item $max_scrollback = $term->saveLines 1315=item $max_scrollback = $term->saveLines
813 1316
814=item $nrow_plus_saveLines = $term->total_rows 1317=item $nrow_plus_saveLines = $term->total_rows
815 1318
816=item $lines_in_scrollback = $term->nsaved 1319=item $topmost_scrollback_row = $term->top_row
817 1320
818Return various integers describing terminal characteristics. 1321Return various integers describing terminal characteristics.
1322
1323=item $x_display = $term->display_id
1324
1325Return the DISPLAY used by rxvt-unicode.
1326
1327=item $lc_ctype = $term->locale
1328
1329Returns the LC_CTYPE category string used by this rxvt-unicode.
1330
1331=item $env = $term->env
1332
1333Returns a copy of the environment in effect for the terminal as a hashref
1334similar to C<\%ENV>.
1335
1336=cut
1337
1338sub env {
1339 if (my $env = $_[0]->_env) {
1340 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env }
1341 } else {
1342 +{ %ENV }
1343 }
1344}
819 1345
820=item $modifiermask = $term->ModLevel3Mask 1346=item $modifiermask = $term->ModLevel3Mask
821 1347
822=item $modifiermask = $term->ModMetaMask 1348=item $modifiermask = $term->ModMetaMask
823 1349
826Return the modifier masks corresponding to the "ISO Level 3 Shift" (often 1352Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
827AltGr), the meta key (often Alt) and the num lock key, if applicable. 1353AltGr), the meta key (often Alt) and the num lock key, if applicable.
828 1354
829=item $view_start = $term->view_start ([$newvalue]) 1355=item $view_start = $term->view_start ([$newvalue])
830 1356
831Returns the negative row number of the topmost line. Minimum value is 1357Returns the row number of the topmost displayed line. Maximum value is
832C<0>, which displays the normal terminal contents. Larger values scroll 1358C<0>, which displays the normal terminal contents. Lower values scroll
833this many lines into the scrollback buffer. 1359this many lines into the scrollback buffer.
834 1360
835=item $term->want_refresh 1361=item $term->want_refresh
836 1362
837Requests a screen refresh. At the next opportunity, rxvt-unicode will 1363Requests a screen refresh. At the next opportunity, rxvt-unicode will
916Return the row number of the first/last row of the line, respectively. 1442Return the row number of the first/last row of the line, respectively.
917 1443
918=item $offset = $line->offset_of ($row, $col) 1444=item $offset = $line->offset_of ($row, $col)
919 1445
920Returns the character offset of the given row|col pair within the logical 1446Returns the character offset of the given row|col pair within the logical
921line. 1447line. Works for rows outside the line, too, and returns corresponding
1448offsets outside the string.
922 1449
923=item ($row, $col) = $line->coord_of ($offset) 1450=item ($row, $col) = $line->coord_of ($offset)
924 1451
925Translates a string offset into terminal coordinates again. 1452Translates a string offset into terminal coordinates again.
926 1453
927=back 1454=back
928 1455
929=cut 1456=cut
930 1457
931sub urxvt::term::line { 1458sub line {
932 my ($self, $row) = @_; 1459 my ($self, $row) = @_;
933 1460
934 my $maxrow = $self->nrow - 1; 1461 my $maxrow = $self->nrow - 1;
935 1462
936 my ($beg, $end) = ($row, $row); 1463 my ($beg, $end) = ($row, $row);
1000 $offset / $self->{ncol} + $self->{beg}, 1527 $offset / $self->{ncol} + $self->{beg},
1001 $offset % $self->{ncol} 1528 $offset % $self->{ncol}
1002 ) 1529 )
1003} 1530}
1004 1531
1005=item ($row, $col) = $line->coord_of ($offset)
1006=item $text = $term->special_encode $string 1532=item $text = $term->special_encode $string
1007 1533
1008Converts a perl string into the special encoding used by rxvt-unicode, 1534Converts a perl string into the special encoding used by rxvt-unicode,
1009where one character corresponds to one screen cell. See 1535where one character corresponds to one screen cell. See
1010C<< $term->ROW_t >> for details. 1536C<< $term->ROW_t >> for details.
1012=item $string = $term->special_decode $text 1538=item $string = $term->special_decode $text
1013 1539
1014Converts rxvt-unicodes text reprsentation into a perl string. See 1540Converts rxvt-unicodes text reprsentation into a perl string. See
1015C<< $term->ROW_t >> for details. 1541C<< $term->ROW_t >> for details.
1016 1542
1543=item $success = $term->grab_button ($button, $modifiermask)
1544
1545Registers a synchronous button grab. See the XGrabButton manpage.
1546
1547=item $success = $term->grab ($eventtime[, $sync])
1548
1549Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1550synchronous (C<$sync> is true). Also remembers the grab timestampe.
1551
1552=item $term->allow_events_async
1553
1554Calls XAllowEvents with AsyncBoth for the most recent grab.
1555
1556=item $term->allow_events_sync
1557
1558Calls XAllowEvents with SyncBoth for the most recent grab.
1559
1560=item $term->allow_events_replay
1561
1562Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most
1563recent grab.
1564
1565=item $term->ungrab
1566
1567Calls XUngrab for the most recent grab. Is called automatically on
1568evaluation errors, as it is better to lose the grab in the error case as
1569the session.
1570
1017=back 1571=back
1018 1572
1573=cut
1574
1575package urxvt::popup;
1576
1019=head2 The C<urxvt::popup> Class 1577=head2 The C<urxvt::popup> Class
1020 1578
1021=over 4 1579=over 4
1022 1580
1023=cut 1581=cut
1024
1025package urxvt::popup;
1026 1582
1027sub add_item { 1583sub add_item {
1028 my ($self, $item) = @_; 1584 my ($self, $item) = @_;
1029 1585
1586 $item->{rend}{normal} = "\x1b[0;30;47m" unless exists $item->{rend}{normal};
1587 $item->{rend}{hover} = "\x1b[0;30;46m" unless exists $item->{rend}{hover};
1588 $item->{rend}{active} = "\x1b[m" unless exists $item->{rend}{active};
1589
1590 $item->{render} ||= sub { $_[0]{text} };
1591
1030 push @{ $self->{item} }, $item; 1592 push @{ $self->{item} }, $item;
1031} 1593}
1594
1595=item $popup->add_title ($title)
1596
1597Adds a non-clickable title to the popup.
1598
1599=cut
1600
1601sub add_title {
1602 my ($self, $title) = @_;
1603
1604 $self->add_item ({
1605 rend => { normal => "\x1b[38;5;11;44m", hover => "\x1b[38;5;11;44m", active => "\x1b[38;5;11;44m" },
1606 text => $title,
1607 activate => sub { },
1608 });
1609}
1610
1611=item $popup->add_separator ([$sepchr])
1612
1613Creates a separator, optionally using the character given as C<$sepchr>.
1614
1615=cut
1616
1617sub add_separator {
1618 my ($self, $sep) = @_;
1619
1620 $sep ||= "=";
1621
1622 $self->add_item ({
1623 rend => { normal => "\x1b[0;30;47m", hover => "\x1b[0;30;47m", active => "\x1b[0;30;47m" },
1624 text => "",
1625 render => sub { $sep x $self->{term}->ncol },
1626 activate => sub { },
1627 });
1628}
1629
1630=item $popup->add_button ($text, $cb)
1631
1632Adds a clickable button to the popup. C<$cb> is called whenever it is
1633selected.
1634
1635=cut
1032 1636
1033sub add_button { 1637sub add_button {
1034 my ($self, $text, $cb) = @_; 1638 my ($self, $text, $cb) = @_;
1035 1639
1036 $self->add_item ({ type => "button", text => "[ $text ]", activate => $cb, 1640 $self->add_item ({ type => "button", text => $text, activate => $cb});
1037 render => sub { $_[0]{text} },
1038 });
1039} 1641}
1642
1643=item $popup->add_toggle ($text, $cb, $initial_value)
1644
1645Adds a toggle/checkbox item to the popup. Teh callback gets called
1646whenever it gets toggled, with a boolean indicating its value as its first
1647argument.
1648
1649=cut
1040 1650
1041sub add_toggle { 1651sub add_toggle {
1042 my ($self, $text, $cb, $value) = @_; 1652 my ($self, $text, $cb, $value) = @_;
1043 1653
1044 my $item; $item = { 1654 my $item; $item = {
1045 type => "button", 1655 type => "button",
1046 text => " $text", 1656 text => " $text",
1047 value => $value, 1657 value => $value,
1048 render => sub { ($item->{value} ? "" : " ") . $text }, 1658 render => sub { ($_[0]{value} ? "* " : " ") . $text },
1049 activate => sub { $cb->($item->{value} = !$item->{value}); }, 1659 activate => sub { $cb->($_[1]{value} = !$_[1]{value}); },
1050 }; 1660 };
1051 1661
1052 $self->add_item ($item); 1662 $self->add_item ($item);
1053} 1663}
1664
1665=item $popup->show
1666
1667Displays the popup (which is initially hidden).
1668
1669=cut
1054 1670
1055sub show { 1671sub show {
1056 my ($self) = @_; 1672 my ($self) = @_;
1057 1673
1058 local $urxvt::popup::self = $self; 1674 local $urxvt::popup::self = $self;
1059 1675
1060 urxvt->new ("--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0, 1676 my $env = $self->{term}->env;
1677 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
1678 delete $env->{LC_ALL};
1679 $env->{LC_CTYPE} = $self->{term}->locale;
1680
1681 urxvt::term->new ($env, "popup",
1682 "--perl-lib" => "", "--perl-ext-common" => "",
1683 "-pty-fd" => -1, "-sl" => 0,
1684 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect",
1061 "--transient-for" => $self->{term}->parent, 1685 "--transient-for" => $self->{term}->parent,
1686 "-display" => $self->{term}->display_id,
1062 "-pe" => "urxvt-popup") 1687 "-pe" => "urxvt-popup")
1063 or die "unable to create popup window\n"; 1688 or die "unable to create popup window\n";
1064} 1689}
1065 1690
1066sub DESTROY { 1691sub DESTROY {
1067 my ($self) = @_; 1692 my ($self) = @_;
1068 1693
1694 delete $self->{term}{_destroy}{$self};
1069 $self->{term}->ungrab; 1695 $self->{term}->ungrab;
1070} 1696}
1697
1698=back
1699
1700=cut
1701
1702package urxvt::watcher;
1703
1704@urxvt::timer::ISA = __PACKAGE__;
1705@urxvt::iow::ISA = __PACKAGE__;
1706@urxvt::pw::ISA = __PACKAGE__;
1707@urxvt::iw::ISA = __PACKAGE__;
1071 1708
1072=head2 The C<urxvt::timer> Class 1709=head2 The C<urxvt::timer> Class
1073 1710
1074This class implements timer watchers/events. Time is represented as a 1711This class implements timer watchers/events. Time is represented as a
1075fractional number of seconds since the epoch. Example: 1712fractional number of seconds since the epoch. Example:
1114 1751
1115=item $timer = $timer->start ($tstamp) 1752=item $timer = $timer->start ($tstamp)
1116 1753
1117Set the event trigger time to C<$tstamp> and start the timer. 1754Set the event trigger time to C<$tstamp> and start the timer.
1118 1755
1756=item $timer = $timer->after ($delay)
1757
1758Like C<start>, but sets the expiry timer to c<urxvt::NOW + $delay>.
1759
1119=item $timer = $timer->stop 1760=item $timer = $timer->stop
1120 1761
1121Stop the timer. 1762Stop the timer.
1122 1763
1123=back 1764=back
1128 1769
1129 $term->{socket} = ... 1770 $term->{socket} = ...
1130 $term->{iow} = urxvt::iow 1771 $term->{iow} = urxvt::iow
1131 ->new 1772 ->new
1132 ->fd (fileno $term->{socket}) 1773 ->fd (fileno $term->{socket})
1133 ->events (1) # wait for read data 1774 ->events (urxvt::EVENT_READ)
1134 ->start 1775 ->start
1135 ->cb (sub { 1776 ->cb (sub {
1136 my ($iow, $revents) = @_; 1777 my ($iow, $revents) = @_;
1137 # $revents must be 1 here, no need to check 1778 # $revents must be 1 here, no need to check
1138 sysread $term->{socket}, my $buf, 8192 1779 sysread $term->{socket}, my $buf, 8192
1155 1796
1156Set the filedescriptor (not handle) to watch. 1797Set the filedescriptor (not handle) to watch.
1157 1798
1158=item $iow = $iow->events ($eventmask) 1799=item $iow = $iow->events ($eventmask)
1159 1800
1160Set the event mask to watch. Bit #0 (value C<1>) enables watching for read 1801Set the event mask to watch. The only allowed values are
1161data, Bit #1 (value C<2>) enables watching for write data. 1802C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed
1803together, or C<urxvt::EVENT_NONE>.
1162 1804
1163=item $iow = $iow->start 1805=item $iow = $iow->start
1164 1806
1165Start watching for requested events on the given handle. 1807Start watching for requested events on the given handle.
1166 1808
1167=item $iow = $iow->stop 1809=item $iow = $iow->stop
1168 1810
1169Stop watching for events on the given filehandle. 1811Stop watching for events on the given filehandle.
1812
1813=back
1814
1815=head2 The C<urxvt::iw> Class
1816
1817This class implements idle watchers, that get called automatically when
1818the process is idle. They should return as fast as possible, after doing
1819some useful work.
1820
1821=over 4
1822
1823=item $iw = new urxvt::iw
1824
1825Create a new idle watcher object in stopped state.
1826
1827=item $iw = $iw->cb (sub { my ($iw) = @_; ... })
1828
1829Set the callback to be called when the watcher triggers.
1830
1831=item $timer = $timer->start
1832
1833Start the watcher.
1834
1835=item $timer = $timer->stop
1836
1837Stop the watcher.
1838
1839=back
1840
1841=head2 The C<urxvt::pw> Class
1842
1843This class implements process watchers. They create an event whenever a
1844process exits, after which they stop automatically.
1845
1846 my $pid = fork;
1847 ...
1848 $term->{pw} = urxvt::pw
1849 ->new
1850 ->start ($pid)
1851 ->cb (sub {
1852 my ($pw, $exit_status) = @_;
1853 ...
1854 });
1855
1856=over 4
1857
1858=item $pw = new urxvt::pw
1859
1860Create a new process watcher in stopped state.
1861
1862=item $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
1863
1864Set the callback to be called when the timer triggers.
1865
1866=item $pw = $timer->start ($pid)
1867
1868Tells the wqtcher to start watching for process C<$pid>.
1869
1870=item $pw = $pw->stop
1871
1872Stop the watcher.
1170 1873
1171=back 1874=back
1172 1875
1173=head1 ENVIRONMENT 1876=head1 ENVIRONMENT
1174 1877
1177This variable controls the verbosity level of the perl extension. Higher 1880This variable controls the verbosity level of the perl extension. Higher
1178numbers indicate more verbose output. 1881numbers indicate more verbose output.
1179 1882
1180=over 4 1883=over 4
1181 1884
1182=item =0 - only fatal messages 1885=item == 0 - fatal messages
1183 1886
1184=item =3 - script loading and management 1887=item >= 3 - script loading and management
1185 1888
1186=item =10 - all events received 1889=item >=10 - all called hooks
1890
1891=item >=11 - hook reutrn values
1187 1892
1188=back 1893=back
1189 1894
1190=head1 AUTHOR 1895=head1 AUTHOR
1191 1896

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines