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.46 by root, Sat Jan 7 20:29:28 2006 UTC vs.
Revision 1.111 by root, Thu Jan 19 19:52:54 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.
64 166
65=item mark-urls 167=item mark-urls
66 168
67Uses per-line display filtering (C<on_line_update>) to underline urls. 169Uses per-line display filtering (C<on_line_update>) to underline urls and
170make them clickable. When middle-clicked, the program specified in the
171resource C<urlLauncher> (default C<x-www-browser>) will be started with
172the URL as first argument.
173
174=item automove-background
175
176This is basically a one-line extension that dynamically changes the background pixmap offset
177to the window position, in effect creating the same effect as pseudo transparency with
178a custom pixmap. No scaling is supported in this mode. Exmaple:
179
180 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background
68 181
69=item block-graphics-to-ascii 182=item block-graphics-to-ascii
70 183
71A not very useful example of filtering all text output to the terminal, 184A not very useful example of filtering all text output to the terminal,
72by replacing all line-drawing characters (U+2500 .. U+259F) by a 185by replacing all line-drawing characters (U+2500 .. U+259F) by a
73similar-looking ascii character. 186similar-looking ascii character.
74 187
188=item digital-clock
189
190Displays a digital clock using the built-in overlay.
191
75=item example-refresh-hooks 192=item example-refresh-hooks
76 193
77Displays a very simple digital clock in the upper right corner of the 194Displays a very simple digital clock in the upper right corner of the
78window. Illustrates overwriting the refresh callbacks to create your own 195window. Illustrates overwriting the refresh callbacks to create your own
79overlays or changes. 196overlays or changes.
80 197
198=item selection-pastebin
199
200This is a little rarely useful extension that Uploads the selection as
201textfile to a remote site (or does other things). (The implementation is
202not currently secure for use in a multiuser environment as it writes to
203F</tmp> directly.).
204
205It listens to the C<selection-pastebin:remote-pastebin> keyboard command,
206i.e.
207
208 URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin
209
210Pressing this combination runs a command with C<%> replaced by the name of
211the textfile. This command can be set via a resource:
212
213 URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
214
215And the default is likely not useful to anybody but the few people around
216here :)
217
218The name of the textfile is the hex encoded md5 sum of the selection, so
219the same content should lead to the same filename.
220
221After a successful upload the selection will be replaced by the text given
222in the C<selection-pastebin-url> resource (again, the % is the placeholder
223for the filename):
224
225 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
226
81=back 227=back
228
229=head1 API DOCUMENTATION
82 230
83=head2 General API Considerations 231=head2 General API Considerations
84 232
85All objects (such as terminals, time watchers etc.) are typical 233All objects (such as terminals, time watchers etc.) are typical
86reference-to-hash objects. The hash can be used to store anything you 234reference-to-hash objects. The hash can be used to store anything you
99=over 4 247=over 4
100 248
101=item $text 249=item $text
102 250
103Rxvt-unicodes special way of encoding text, where one "unicode" character 251Rxvt-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. 252always represents one screen cell. See L<ROW_t> for a discussion of this format.
105 253
106=item $string 254=item $string
107 255
108A perl text string, with an emphasis on I<text>. It can store all unicode 256A 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 257characters and is to be distinguished with text encoded in a specific
114Either binary data or - more common - a text string encoded in a 262Either binary data or - more common - a text string encoded in a
115locale-specific way. 263locale-specific way.
116 264
117=back 265=back
118 266
267=head2 Extension Objects
268
269Very perl extension is a perl class. A separate perl object is created
270for each terminal and each extension and passed as the first parameter to
271hooks. So extensions can use their C<$self> object without having to think
272about other extensions, with the exception of methods and members that
273begin with an underscore character C<_>: these are reserved for internal
274use.
275
276Although it isn't a C<urxvt::term> object, you can call all methods of the
277C<urxvt::term> class on this object.
278
279It has the following methods and data members:
280
281=over 4
282
283=item $urxvt_term = $self->{term}
284
285Returns the C<urxvt::term> object associated with this instance of the
286extension. This member I<must not> be changed in any way.
287
288=item $self->enable ($hook_name => $cb, [$hook_name => $cb..])
289
290Dynamically enable the given hooks (named without the C<on_> prefix) for
291this extension, replacing any previous hook. This is useful when you want
292to overwrite time-critical hooks only temporarily.
293
294=item $self->disable ($hook_name[, $hook_name..])
295
296Dynamically disable the given hooks.
297
298=back
299
119=head2 Hooks 300=head2 Hooks
120 301
121The following subroutines can be declared in extension files, and will be 302The following subroutines can be declared in extension files, and will be
122called whenever the relevant event happens. 303called whenever the relevant event happens.
123 304
124The first argument passed to them is an object private to each terminal 305The 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 306the 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 307
131All of them must return a boolean value. If it is true, then the event 308B<All> of these hooks must return a boolean value. If it is true, then the
132counts as being I<consumed>, and the invocation of other hooks is skipped, 309event counts as being I<consumed>, and the invocation of other hooks is
133and the relevant action might not be carried out by the C++ code. 310skipped, and the relevant action might not be carried out by the C++ code.
134 311
135When in doubt, return a false value (preferably C<()>). 312I<< When in doubt, return a false value (preferably C<()>). >>
136 313
137=over 4 314=over 4
138 315
139=item on_init $term 316=item on_init $term
140 317
153=item on_start $term 330=item on_start $term
154 331
155Called at the very end of initialisation of a new terminal, just before 332Called at the very end of initialisation of a new terminal, just before
156returning to the mainloop. 333returning to the mainloop.
157 334
335=item on_child_start $term, $pid
336
337Called just after the child process has been C<fork>ed.
338
339=item on_child_exit $term, $status
340
341Called just after the child process has exited. C<$status> is the status
342from C<waitpid>.
343
158=item on_sel_make $term, $eventtime 344=item on_sel_make $term, $eventtime
159 345
160Called whenever a selection has been made by the user, but before the 346Called 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 347selection text is copied, so changes to the beginning, end or type of the
162selection will be honored. 348selection will be honored.
175=item on_sel_extend $term 361=item on_sel_extend $term
176 362
177Called whenever the user tries to extend the selection (e.g. with a double 363Called whenever the user tries to extend the selection (e.g. with a double
178click) and is either supposed to return false (normal operation), or 364click) and is either supposed to return false (normal operation), or
179should extend the selection itelf and return true to suppress the built-in 365should extend the selection itelf and return true to suppress the built-in
180processing. 366processing. This can happen multiple times, as long as the callback
367returns true, it will be called on every further click by the user and is
368supposed to enlarge the selection more and more, if possible.
181 369
182See the F<selection> example extension. 370See the F<selection> example extension.
183 371
184=item on_view_change $term, $offset 372=item on_view_change $term, $offset
185 373
194than the scroll back buffer or the terminal. 382than the scroll back buffer or the terminal.
195 383
196It is called before lines are scrolled out (so rows 0 .. min ($lines - 1, 384It 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 385$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
198number of lines that will be in the scrollback buffer. 386number 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 387
204=item on_osc_seq $term, $string 388=item on_osc_seq $term, $string
205 389
206Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 390Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
207operating system command) is processed. Cursor position and other state 391operating system command) is processed. Cursor position and other state
220can filter/change and output the text yourself by returning a true value 404can filter/change and output the text yourself by returning a true value
221and calling C<< $term->scr_add_lines >> yourself. Please note that this 405and 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 406might be very slow, however, as your hook is called for B<all> text being
223output. 407output.
224 408
409=item on_tt_write $term, $octets
410
411Called whenever some data is written to the tty/pty and can be used to
412suppress or filter tty input.
413
225=item on_line_update $term, $row 414=item on_line_update $term, $row
226 415
227Called whenever a line was updated or changed. Can be used to filter 416Called whenever a line was updated or changed. Can be used to filter
228screen output (e.g. underline urls or other useless stuff). Only lines 417screen output (e.g. underline urls or other useless stuff). Only lines
229that are being shown will be filtered, and, due to performance reasons, 418that are being shown will be filtered, and, due to performance reasons,
251 440
252Called whenever the user presses a key combination that has a 441Called whenever the user presses a key combination that has a
253C<perl:string> action bound to it (see description of the B<keysym> 442C<perl:string> action bound to it (see description of the B<keysym>
254resource in the @@RXVT_NAME@@(1) manpage). 443resource in the @@RXVT_NAME@@(1) manpage).
255 444
445=item on_x_event $term, $event
446
447Called on every X event received on the vt window (and possibly other
448windows). Should only be used as a last resort. Most event structure
449members are not passed.
450
256=item on_focus_in $term 451=item on_focus_in $term
257 452
258Called whenever the window gets the keyboard focus, before rxvt-unicode 453Called whenever the window gets the keyboard focus, before rxvt-unicode
259does focus in processing. 454does focus in processing.
260 455
261=item on_focus_out $term 456=item on_focus_out $term
262 457
263Called wheneever the window loses keyboard focus, before rxvt-unicode does 458Called wheneever the window loses keyboard focus, before rxvt-unicode does
264focus out processing. 459focus out processing.
265 460
461=item on_configure_notify $term, $event
462
266=item on_key_press $term, $event, $octets 463=item on_key_press $term, $event, $keysym, $octets
267 464
268=item on_key_release $term, $event 465=item on_key_release $term, $event, $keysym
269 466
270=item on_button_press $term, $event 467=item on_button_press $term, $event
271 468
272=item on_button_release $term, $event 469=item on_button_release $term, $event
273 470
289 486
290subwindow. 487subwindow.
291 488
292=back 489=back
293 490
491=cut
492
493package urxvt;
494
495use utf8;
496use strict;
497use Carp ();
498use Scalar::Util ();
499use List::Util ();
500
501our $VERSION = 1;
502our $TERM;
503our @HOOKNAME;
504our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
505our %OPTION;
506
507our $LIBDIR;
508our $RESNAME;
509our $RESCLASS;
510our $RXVTNAME;
511
294=head2 Variables in the C<urxvt> Package 512=head2 Variables in the C<urxvt> Package
295 513
296=over 4 514=over 4
515
516=item $urxvt::LIBDIR
517
518The rxvt-unicode library directory, where, among other things, the perl
519modules and scripts are stored.
520
521=item $urxvt::RESCLASS, $urxvt::RESCLASS
522
523The resource class and name rxvt-unicode uses to look up X resources.
524
525=item $urxvt::RXVTNAME
526
527The basename of the installed binaries, usually C<urxvt>.
297 528
298=item $urxvt::TERM 529=item $urxvt::TERM
299 530
300The current terminal. This variable stores the current C<urxvt::term> 531The current terminal. This variable stores the current C<urxvt::term>
301object, whenever a callback/hook is executing. 532object, whenever a callback/hook is executing.
303=back 534=back
304 535
305=head2 Functions in the C<urxvt> Package 536=head2 Functions in the C<urxvt> Package
306 537
307=over 4 538=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 539
317=item urxvt::fatal $errormessage 540=item urxvt::fatal $errormessage
318 541
319Fatally aborts execution with the given error message. Avoid at all 542Fatally aborts execution with the given error message. Avoid at all
320costs! The only time this is acceptable is when the terminal process 543costs! The only time this is acceptable is when the terminal process
327that calls this function. 550that calls this function.
328 551
329Using this function has the advantage that its output ends up in the 552Using this function has the advantage that its output ends up in the
330correct place, e.g. on stderr of the connecting urxvtc client. 553correct place, e.g. on stderr of the connecting urxvtc client.
331 554
555Messages have a size limit of 1023 bytes currently.
556
332=item $time = urxvt::NOW 557=item $time = urxvt::NOW
333 558
334Returns the "current time" (as per the event loop). 559Returns the "current time" (as per the event loop).
560
561=item urxvt::CurrentTime
562
563=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
564Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
565Button4Mask, Button5Mask, AnyModifier
566
567=item urxvt::NoEventMask, KeyPressMask, KeyReleaseMask,
568ButtonPressMask, ButtonReleaseMask, EnterWindowMask, LeaveWindowMask,
569PointerMotionMask, PointerMotionHintMask, Button1MotionMask, Button2MotionMask,
570Button3MotionMask, Button4MotionMask, Button5MotionMask, ButtonMotionMask,
571KeymapStateMask, ExposureMask, VisibilityChangeMask, StructureNotifyMask,
572ResizeRedirectMask, SubstructureNotifyMask, SubstructureRedirectMask,
573FocusChangeMask, PropertyChangeMask, ColormapChangeMask, OwnerGrabButtonMask
574
575=item urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify,
576EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose,
577GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify, DestroyNotify,
578UnmapNotify, MapNotify, MapRequest, ReparentNotify, ConfigureNotify,
579ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify,
580CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest,
581SelectionNotify, ColormapNotify, ClientMessage, MappingNotify
582
583Various constants for use in X calls and event processing.
335 584
336=back 585=back
337 586
338=head2 RENDITION 587=head2 RENDITION
339 588
366 615
367=item $background = urxvt::GET_BASEBG $rend 616=item $background = urxvt::GET_BASEBG $rend
368 617
369Return the foreground/background colour index, respectively. 618Return the foreground/background colour index, respectively.
370 619
371=item $rend = urxvt::SET_FGCOLOR ($rend, $new_colour) 620=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
372 621
373=item $rend = urxvt::SET_BGCOLOR ($rend, $new_colour) 622=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
374 623
375Replace the foreground/background colour in the rendition mask with the 624Replace the foreground/background colour in the rendition mask with the
376specified one. 625specified one.
377 626
378=item $value = urxvt::GET_CUSTOM ($rend) 627=item $value = urxvt::GET_CUSTOM $rend
379 628
380Return the "custom" value: Every rendition has 5 bits for use by 629Return the "custom" value: Every rendition has 5 bits for use by
381extensions. They can be set and changed as you like and are initially 630extensions. They can be set and changed as you like and are initially
382zero. 631zero.
383 632
384=item $rend = urxvt::SET_CUSTOM ($rend, $new_value) 633=item $rend = urxvt::SET_CUSTOM $rend, $new_value
385 634
386Change the custom value. 635Change the custom value.
387 636
388=back 637=back
389 638
390=cut 639=cut
391 640
392package urxvt;
393
394use strict;
395use Scalar::Util ();
396
397our $TERM;
398our @HOOKNAME;
399our $LIBDIR;
400
401BEGIN { 641BEGIN {
402 urxvt->bootstrap;
403
404 # overwrite perl's warn 642 # overwrite perl's warn
405 *CORE::GLOBAL::warn = sub { 643 *CORE::GLOBAL::warn = sub {
406 my $msg = join "", @_; 644 my $msg = join "", @_;
407 $msg .= "\n" 645 $msg .= "\n"
408 unless $msg =~ /\n$/; 646 unless $msg =~ /\n$/;
409 urxvt::warn ($msg); 647 urxvt::warn ($msg);
410 }; 648 };
411} 649}
412 650
413my @hook_count;
414my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 651my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
415 652
416sub verbose { 653sub verbose {
417 my ($level, $msg) = @_; 654 my ($level, $msg) = @_;
418 warn "$msg\n" if $level <= $verbosity; 655 warn "$msg\n" if $level <= $verbosity;
419} 656}
420 657
421# find on_xxx subs in the package and register them
422# as hooks
423sub register_package($) {
424 my ($pkg) = @_;
425
426 for my $htype (0.. $#HOOKNAME) {
427 my $name = $HOOKNAME[$htype];
428
429 my $ref = $pkg->can ("on_" . lc $name)
430 or next;
431
432 $TERM->{_hook}[$htype]{$pkg} = $ref;
433 $hook_count[$htype]++
434 or set_should_invoke $htype, 1;
435 }
436}
437
438my $extension_pkg = "extension0000";
439my %extension_pkg; 658my %extension_pkg;
440 659
441# load a single script into its own package, once only 660# load a single script into its own package, once only
442sub extension_package($) { 661sub extension_package($) {
443 my ($path) = @_; 662 my ($path) = @_;
444 663
664 no strict 'refs';
665
445 $extension_pkg{$path} ||= do { 666 $extension_pkg{$path} ||= do {
446 my $pkg = "urxvt::" . ($extension_pkg++); 667 $path =~ /([^\/\\]+)$/;
668 my $pkg = $1;
669 $pkg =~ s/[^[:word:]]/_/g;
670 $pkg = "urxvt::ext::$pkg";
447 671
448 verbose 3, "loading extension '$path' into package '$pkg'"; 672 verbose 3, "loading extension '$path' into package '$pkg'";
449 673
450 open my $fh, "<:raw", $path 674 open my $fh, "<:raw", $path
451 or die "$path: $!"; 675 or die "$path: $!";
452 676
677 @{"$pkg\::ISA"} = urxvt::term::extension::;
678
679 my $source =
453 my $source = "package $pkg; use strict; use utf8;\n" 680 "package $pkg; use strict; use utf8;\n"
454 . "use base urxvt::term::proxy::;\n"
455 . "#line 1 \"$path\"\n{\n" 681 . "#line 1 \"$path\"\n{\n"
456 . (do { local $/; <$fh> }) 682 . (do { local $/; <$fh> })
457 . "\n};\n1"; 683 . "\n};\n1";
458 684
685 eval $source
459 eval $source or die "$path: $@"; 686 or die "$path: $@";
460 687
461 $pkg 688 $pkg
462 } 689 }
463} 690}
464 691
469 local $TERM = shift; 696 local $TERM = shift;
470 my $htype = shift; 697 my $htype = shift;
471 698
472 if ($htype == 0) { # INIT 699 if ($htype == 0) { # INIT
473 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 700 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
701
702 my %ext_arg;
474 703
475 for my $ext (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) { 704 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
705 if ($_ eq "default") {
706 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback);
707 } elsif (/^-(.*)$/) {
708 delete $ext_arg{$1};
709 } elsif (/^([^<]+)<(.*)>$/) {
710 push @{ $ext_arg{$1} }, $2;
711 } else {
712 $ext_arg{$_} ||= [];
713 }
714 }
715
716 while (my ($ext, $argv) = each %ext_arg) {
476 my @files = grep -f $_, map "$_/$ext", @dirs; 717 my @files = grep -f $_, map "$_/$ext", @dirs;
477 718
478 if (@files) { 719 if (@files) {
479 register_package extension_package $files[0]; 720 $TERM->register_package (extension_package $files[0], $argv);
480 } else { 721 } else {
481 warn "perl extension '$ext' not found in perl library search path\n"; 722 warn "perl extension '$ext' not found in perl library search path\n";
482 } 723 }
483 } 724 }
725
726 eval "#line 1 \"--perl-eval resource/argument\"\n" . $TERM->resource ("perl_eval");
727 warn $@ if $@;
484 } 728 }
485 729
486 $retval = undef; 730 $retval = undef;
487 731
488 if (my $cb = $TERM->{_hook}[$htype]) { 732 if (my $cb = $TERM->{_hook}[$htype]) {
490 if $verbosity >= 10; 734 if $verbosity >= 10;
491 735
492 keys %$cb; 736 keys %$cb;
493 737
494 while (my ($pkg, $cb) = each %$cb) { 738 while (my ($pkg, $cb) = each %$cb) {
495 eval { 739 $retval = eval { $cb->($TERM->{_pkg}{$pkg}, @_) }
496 $retval = $cb->(
497 $TERM->{_pkg}{$pkg} ||= do {
498 my $proxy = bless { }, $pkg;
499 Scalar::Util::weaken ($proxy->{term} = $TERM);
500 $proxy
501 },
502 @_,
503 ) and last; 740 and last;
504 };
505 warn $@ if $@;#d#
506 }
507 }
508 741
509 if ($htype == 1) { # DESTROY 742 if ($@) {
510 # remove hooks if unused 743 $TERM->ungrab; # better to lose the grab than the session
511 if (my $hook = $TERM->{_hook}) { 744 warn $@;
512 for my $htype (0..$#$hook) {
513 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
514 or set_should_invoke $htype, 0;
515 } 745 }
516 } 746 }
517 747
748 verbose 11, "$HOOKNAME[$htype] returning <$retval>"
749 if $verbosity >= 11;
750 }
751
752 if ($htype == 1) { # DESTROY
518 # clear package objects 753 # clear package objects
519 %$_ = () for values %{ $TERM->{_pkg} }; 754 %$_ = () for values %{ $TERM->{_pkg} };
520 755
521 # clear package 756 # clear package
522 %$TERM = (); 757 %$TERM = ();
523 } 758 }
524 759
525 $retval 760 $retval
526} 761}
527 762
528sub urxvt::term::proxy::AUTOLOAD { 763# urxvt::term::extension
529 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/ 764
765package urxvt::term::extension;
766
767sub enable {
768 my ($self, %hook) = @_;
769 my $pkg = $self->{_pkg};
770
771 while (my ($name, $cb) = each %hook) {
772 my $htype = $HOOKTYPE{uc $name};
773 defined $htype
774 or Carp::croak "unsupported hook type '$name'";
775
776 $self->set_should_invoke ($htype, +1)
777 unless exists $self->{term}{_hook}[$htype]{$pkg};
778
779 $self->{term}{_hook}[$htype]{$pkg} = $cb;
780 }
781}
782
783sub disable {
784 my ($self, @hook) = @_;
785 my $pkg = $self->{_pkg};
786
787 for my $name (@hook) {
788 my $htype = $HOOKTYPE{uc $name};
789 defined $htype
790 or Carp::croak "unsupported hook type '$name'";
791
792 $self->set_should_invoke ($htype, -1)
793 if delete $self->{term}{_hook}[$htype]{$pkg};
794 }
795}
796
797our $AUTOLOAD;
798
799sub AUTOLOAD {
800 $AUTOLOAD =~ /:([^:]+)$/
530 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable"; 801 or die "FATAL: \$AUTOLOAD '$AUTOLOAD' unparsable";
531 802
532 eval qq{ 803 eval qq{
533 sub $urxvt::term::proxy::AUTOLOAD { 804 sub $AUTOLOAD {
534 my \$proxy = shift; 805 my \$proxy = shift;
535 \$proxy->{term}->$1 (\@_) 806 \$proxy->{term}->$1 (\@_)
536 } 807 }
537 1 808 1
538 } or die "FATAL: unable to compile method forwarder: $@"; 809 } or die "FATAL: unable to compile method forwarder: $@";
539 810
540 goto &$urxvt::term::proxy::AUTOLOAD; 811 goto &$AUTOLOAD;
541} 812}
813
814sub DESTROY {
815 # nop
816}
817
818# urxvt::destroy_hook
542 819
543sub urxvt::destroy_hook::DESTROY { 820sub urxvt::destroy_hook::DESTROY {
544 ${$_[0]}->(); 821 ${$_[0]}->();
545} 822}
546 823
547sub urxvt::destroy_hook(&) { 824sub urxvt::destroy_hook(&) {
548 bless \shift, urxvt::destroy_hook:: 825 bless \shift, urxvt::destroy_hook::
549} 826}
550 827
828package urxvt::anyevent;
829
830=head2 The C<urxvt::anyevent> Class
831
832The sole purpose of this class is to deliver an interface to the
833C<AnyEvent> module - any module using it will work inside urxvt without
834further programming. The only exception is that you cannot wait on
835condition variables, but non-blocking condvar use is ok. What this means
836is that you cannot use blocking APIs, but the non-blocking variant should
837work.
838
839=cut
840
841our $VERSION = 1;
842
843$INC{"urxvt/anyevent.pm"} = 1; # mark us as there
844push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
845
846sub timer {
847 my ($class, %arg) = @_;
848
849 my $cb = $arg{cb};
850
851 urxvt::timer
852 ->new
853 ->start (urxvt::NOW + $arg{after})
854 ->cb (sub {
855 $_[0]->stop; # need to cancel manually
856 $cb->();
857 })
858}
859
860sub io {
861 my ($class, %arg) = @_;
862
863 my $cb = $arg{cb};
864
865 bless [$arg{fh}, urxvt::iow
866 ->new
867 ->fd (fileno $arg{fh})
868 ->events (($arg{poll} =~ /r/ ? 1 : 0)
869 | ($arg{poll} =~ /w/ ? 2 : 0))
870 ->start
871 ->cb (sub {
872 $cb->(($_[1] & 1 ? 'r' : '')
873 . ($_[1] & 2 ? 'w' : ''));
874 })],
875 urxvt::anyevent::
876}
877
878sub DESTROY {
879 $_[0][1]->stop;
880}
881
882sub condvar {
883 bless \my $flag, urxvt::anyevent::condvar::
884}
885
886sub urxvt::anyevent::condvar::broadcast {
887 ${$_[0]}++;
888}
889
890sub urxvt::anyevent::condvar::wait {
891 unless (${$_[0]}) {
892 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API";
893 }
894}
895
896package urxvt::term;
897
551=head2 The C<urxvt::term> Class 898=head2 The C<urxvt::term> Class
552 899
553=over 4 900=over 4
554 901
902=cut
903
904# find on_xxx subs in the package and register them
905# as hooks
906sub register_package {
907 my ($self, $pkg, $argv) = @_;
908
909 my $proxy = bless {
910 _pkg => $pkg,
911 argv => $argv,
912 }, $pkg;
913 Scalar::Util::weaken ($proxy->{term} = $self);
914
915 $self->{_pkg}{$pkg} = $proxy;
916
917 for my $name (@HOOKNAME) {
918 if (my $ref = $pkg->can ("on_" . lc $name)) {
919 $proxy->enable ($name => $ref);
920 }
921 }
922}
923
924=item $term = new urxvt::term $envhashref, $rxvtname, [arg...]
925
926Creates a new terminal, very similar as if you had started it with system
927C<$rxvtname, arg...>. C<$envhashref> must be a reference to a C<%ENV>-like
928hash which defines the environment of the new terminal.
929
930Croaks (and probably outputs an error message) if the new instance
931couldn't be created. Returns C<undef> if the new instance didn't
932initialise perl, and the terminal object otherwise. The C<init> and
933C<start> hooks will be called during this call.
934
935=cut
936
937sub new {
938 my ($class, $env, @args) = @_;
939
940 _new ([ map "$_=$env->{$_}", keys %$env ], @args);
941}
942
555=item $term->destroy 943=item $term->destroy
556 944
557Destroy the terminal object (close the window, free resources etc.). 945Destroy the terminal object (close the window, free resources
946etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event
947watchers (timers, io watchers) are still active.
948
949=item $term->exec_async ($cmd[, @args])
950
951Works like the combination of the C<fork>/C<exec> builtins, which executes
952("starts") programs in the background. This function takes care of setting
953the user environment before exec'ing the command (e.g. C<PATH>) and should
954be preferred over explicit calls to C<exec> or C<system>.
955
956Returns the pid of the subprocess or C<undef> on error.
957
958=cut
959
960sub exec_async {
961 my $self = shift;
962
963 my $pid = fork;
964
965 return $pid
966 if !defined $pid or $pid;
967
968 %ENV = %{ $self->env };
969
970 exec @_;
971 urxvt::_exit 255;
972}
973
974=item $isset = $term->option ($optval[, $set])
975
976Returns true if the option specified by C<$optval> is enabled, and
977optionally change it. All option values are stored by name in the hash
978C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
979
980Here is a a likely non-exhaustive list of option names, please see the
981source file F</src/optinc.h> to see the actual list:
982
983 borderLess console cursorBlink cursorUnderline hold iconic insecure
984 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
985 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
986 scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput
987 scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs
988 transparent tripleclickwords utmpInhibit visualBell
558 989
559=item $value = $term->resource ($name[, $newval]) 990=item $value = $term->resource ($name[, $newval])
560 991
561Returns the current resource value associated with a given name and 992Returns the current resource value associated with a given name and
562optionally sets a new value. Setting values is most useful in the C<init> 993optionally sets a new value. Setting values is most useful in the C<init>
572 1003
573Please note that resource strings will currently only be freed when the 1004Please note that resource strings will currently only be freed when the
574terminal is destroyed, so changing options frequently will eat memory. 1005terminal is destroyed, so changing options frequently will eat memory.
575 1006
576Here is a a likely non-exhaustive list of resource names, not all of which 1007Here is a a likely non-exhaustive list of resource names, not all of which
577are supported in every build, please see the source to see the actual 1008are supported in every build, please see the source file F</src/rsinc.h>
578list: 1009to see the actual list:
579 1010
580 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1011 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
581 borderLess color cursorBlink cursorUnderline cutchars delete_key 1012 borderLess color cursorBlink cursorUnderline cutchars delete_key
582 display_name embed ext_bwidth fade font geometry hold iconName 1013 display_name embed ext_bwidth fade font geometry hold iconName
583 imFont imLocale inputMethod insecure int_bwidth intensityStyles 1014 imFont imLocale inputMethod insecure int_bwidth intensityStyles
584 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier 1015 italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier
585 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2 1016 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
586 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 1017 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
587 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 1018 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
588 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 1019 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
589 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 1020 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
590 shade term_name title transparent transparent_all tripleclickwords 1021 secondaryScreen secondaryScroll selectstyle shade term_name title
591 utmpInhibit visualBell 1022 transient_for transparent transparent_all tripleclickwords utmpInhibit
1023 visualBell
592 1024
593=cut 1025=cut
594 1026
595sub urxvt::term::resource($$;$) { 1027sub resource($$;$) {
596 my ($self, $name) = (shift, shift); 1028 my ($self, $name) = (shift, shift);
597 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 1029 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
598 &urxvt::term::_resource 1030 &urxvt::term::_resource
599} 1031}
600 1032
1033=item $value = $term->x_resource ($pattern)
1034
1035Returns the X-Resource for the given pattern, excluding the program or
1036class name, i.e. C<< $term->x_resource ("boldFont") >> should return the
1037same value as used by this instance of rxvt-unicode. Returns C<undef> if no
1038resource with that pattern exists.
1039
1040This method should only be called during the C<on_start> hook, as there is
1041only one resource database per display, and later invocations might return
1042the wrong resources.
1043
1044=item $success = $term->parse_keysym ($keysym_spec, $command_string)
1045
1046Adds a keymap translation exactly as specified via a resource. See the
1047C<keysym> resource in the @@RXVT_NAME@@(1) manpage.
1048
601=item $rend = $term->rstyle ([$new_rstyle]) 1049=item $rend = $term->rstyle ([$new_rstyle])
602 1050
603Return and optionally change the current rendition. Text that is output by 1051Return and optionally change the current rendition. Text that is output by
604the terminal application will use this style. 1052the terminal application will use this style.
605 1053
615=item ($row, $col) = $term->selection_end ([$row, $col]) 1063=item ($row, $col) = $term->selection_end ([$row, $col])
616 1064
617Return the current values of the selection mark, begin or end positions, 1065Return the current values of the selection mark, begin or end positions,
618and optionally set them to new values. 1066and optionally set them to new values.
619 1067
1068=item $term->selection_make ($eventtime[, $rectangular])
1069
1070Tries to make a selection as set by C<selection_beg> and
1071C<selection_end>. If C<$rectangular> is true (default: false), a
1072rectangular selection will be made. This is the prefered function to make
1073a selection.
1074
620=item $success = $term->selection_grab ($eventtime) 1075=item $success = $term->selection_grab ($eventtime)
621 1076
622Try to request the primary selection from the server (for example, as set 1077Try to request the primary selection text from the server (for example, as
623by the next method). 1078set by the next method). No visual feedback will be given. This function
1079is mostly useful from within C<on_sel_grab> hooks.
624 1080
625=item $oldtext = $term->selection ([$newtext]) 1081=item $oldtext = $term->selection ([$newtext])
626 1082
627Return the current selection text and optionally replace it by C<$newtext>. 1083Return the current selection text and optionally replace it by C<$newtext>.
628 1084
629#=item $term->overlay ($x, $y, $text) 1085=item $term->overlay_simple ($x, $y, $text)
630# 1086
631#Create a simple multi-line overlay box. See the next method for details. 1087Create a simple multi-line overlay box. See the next method for details.
632# 1088
633#=cut 1089=cut
634# 1090
635#sub urxvt::term::scr_overlay { 1091sub overlay_simple {
636# my ($self, $x, $y, $text) = @_; 1092 my ($self, $x, $y, $text) = @_;
637# 1093
638# my @lines = split /\n/, $text; 1094 my @lines = split /\n/, $text;
639# 1095
640# my $w = 0; 1096 my $w = List::Util::max map $self->strwidth ($_), @lines;
641# for (map $self->strwidth ($_), @lines) { 1097
642# $w = $_ if $w < $_;
643# }
644#
645# $self->scr_overlay_new ($x, $y, $w, scalar @lines); 1098 my $overlay = $self->overlay ($x, $y, $w, scalar @lines);
646# $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 1099 $overlay->set (0, $_, $lines[$_]) for 0.. $#lines;
647#} 1100
1101 $overlay
1102}
648 1103
649=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 1104=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
650 1105
651Create a new (empty) overlay at the given position with the given 1106Create a new (empty) overlay at the given position with the given
652width/height. C<$rstyle> defines the initial rendition style 1107width/height. C<$rstyle> defines the initial rendition style
687C<$event> I<must> be the event causing the menu to pop up (a button event, 1142C<$event> I<must> be the event causing the menu to pop up (a button event,
688currently). 1143currently).
689 1144
690=cut 1145=cut
691 1146
692sub urxvt::term::popup { 1147sub popup {
693 my ($self, $event) = @_; 1148 my ($self, $event) = @_;
694 1149
695 $self->grab ($event->{time}, 1) 1150 $self->grab ($event->{time}, 1)
696 or return; 1151 or return;
697 1152
719 1174
720=item $string = $term->locale_decode ($octets) 1175=item $string = $term->locale_decode ($octets)
721 1176
722Convert the given locale-encoded octets into a perl string. 1177Convert the given locale-encoded octets into a perl string.
723 1178
1179=item $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
1180
1181XORs the rendition values in the given span with the provided value
1182(default: C<RS_RVid>), which I<MUST NOT> contain font styles. Useful in
1183refresh hooks to provide effects similar to the selection.
1184
1185=item $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, $rstyle2]])
1186
1187Similar to C<scr_xor_span>, but xors a rectangle instead. Trailing
1188whitespace will additionally be xored with the C<$rstyle2>, which defaults
1189to C<RS_RVid | RS_Uline>, which removes reverse video again and underlines
1190it instead. Both styles I<MUST NOT> contain font styles.
1191
1192=item $term->scr_bell
1193
1194Ring the bell!
1195
724=item $term->scr_add_lines ($string) 1196=item $term->scr_add_lines ($string)
725 1197
726Write the given text string to the screen, as if output by the application 1198Write the given text string to the screen, as if output by the application
727running inside the terminal. It may not contain command sequences (escape 1199running inside the terminal. It may not contain command sequences (escape
728codes), but is free to use line feeds, carriage returns and tabs. The 1200codes), but is free to use line feeds, carriage returns and tabs. The
742 1214
743Write the octets given in C<$data> to the tty (i.e. as program input). To 1215Write the octets given in C<$data> to the tty (i.e. as program input). To
744pass characters instead of octets, you should convert your strings first 1216pass characters instead of octets, you should convert your strings first
745to the locale-specific encoding using C<< $term->locale_encode >>. 1217to the locale-specific encoding using C<< $term->locale_encode >>.
746 1218
1219=item $old_events = $term->pty_ev_events ([$new_events])
1220
1221Replaces the event mask of the pty watcher by the given event mask. Can
1222be used to suppress input and output handling to the pty/tty. See the
1223description of C<< urxvt::timer->events >>. Make sure to always restore
1224the previous value.
1225
747=item $windowid = $term->parent 1226=item $windowid = $term->parent
748 1227
749Return the window id of the toplevel window. 1228Return the window id of the toplevel window.
750 1229
751=item $windowid = $term->vt 1230=item $windowid = $term->vt
752 1231
753Return the window id of the terminal window. 1232Return the window id of the terminal window.
754 1233
1234=item $term->vt_emask_add ($x_event_mask)
1235
1236Adds the specified events to the vt event mask. Useful e.g. when you want
1237to receive pointer events all the times:
1238
1239 $term->vt_emask_add (urxvt::PointerMotionMask);
1240
755=item $window_width = $term->width 1241=item $window_width = $term->width
756 1242
757=item $window_height = $term->height 1243=item $window_height = $term->height
758 1244
759=item $font_width = $term->fwidth 1245=item $font_width = $term->fwidth
772 1258
773=item $max_scrollback = $term->saveLines 1259=item $max_scrollback = $term->saveLines
774 1260
775=item $nrow_plus_saveLines = $term->total_rows 1261=item $nrow_plus_saveLines = $term->total_rows
776 1262
777=item $lines_in_scrollback = $term->nsaved 1263=item $topmost_scrollback_row = $term->top_row
778 1264
779Return various integers describing terminal characteristics. 1265Return various integers describing terminal characteristics.
780 1266
1267=item $x_display = $term->display_id
1268
1269Return the DISPLAY used by rxvt-unicode.
1270
1271=item $lc_ctype = $term->locale
1272
1273Returns the LC_CTYPE category string used by this rxvt-unicode.
1274
1275=item $env = $term->env
1276
1277Returns a copy of the environment in effect for the terminal as a hashref
1278similar to C<\%ENV>.
1279
1280=cut
1281
1282sub env {
1283 if (my $env = $_[0]->_env) {
1284 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env }
1285 } else {
1286 +{ %ENV }
1287 }
1288}
1289
1290=item $modifiermask = $term->ModLevel3Mask
1291
1292=item $modifiermask = $term->ModMetaMask
1293
1294=item $modifiermask = $term->ModNumLockMask
1295
1296Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
1297AltGr), the meta key (often Alt) and the num lock key, if applicable.
1298
781=item $view_start = $term->view_start ([$newvalue]) 1299=item $view_start = $term->view_start ([$newvalue])
782 1300
783Returns the negative row number of the topmost line. Minimum value is 1301Returns the row number of the topmost displayed line. Maximum value is
784C<0>, which displays the normal terminal contents. Larger values scroll 1302C<0>, which displays the normal terminal contents. Lower values scroll
785this many lines into the scrollback buffer. 1303this many lines into the scrollback buffer.
786 1304
787=item $term->want_refresh 1305=item $term->want_refresh
788 1306
789Requests a screen refresh. At the next opportunity, rxvt-unicode will 1307Requests a screen refresh. At the next opportunity, rxvt-unicode will
868Return the row number of the first/last row of the line, respectively. 1386Return the row number of the first/last row of the line, respectively.
869 1387
870=item $offset = $line->offset_of ($row, $col) 1388=item $offset = $line->offset_of ($row, $col)
871 1389
872Returns the character offset of the given row|col pair within the logical 1390Returns the character offset of the given row|col pair within the logical
873line. 1391line. Works for rows outside the line, too, and returns corresponding
1392offsets outside the string.
874 1393
875=item ($row, $col) = $line->coord_of ($offset) 1394=item ($row, $col) = $line->coord_of ($offset)
876 1395
877Translates a string offset into terminal coordinates again. 1396Translates a string offset into terminal coordinates again.
878 1397
879=back 1398=back
880 1399
881=cut 1400=cut
882 1401
883sub urxvt::term::line { 1402sub line {
884 my ($self, $row) = @_; 1403 my ($self, $row) = @_;
885 1404
886 my $maxrow = $self->nrow - 1; 1405 my $maxrow = $self->nrow - 1;
887 1406
888 my ($beg, $end) = ($row, $row); 1407 my ($beg, $end) = ($row, $row);
952 $offset / $self->{ncol} + $self->{beg}, 1471 $offset / $self->{ncol} + $self->{beg},
953 $offset % $self->{ncol} 1472 $offset % $self->{ncol}
954 ) 1473 )
955} 1474}
956 1475
957=item ($row, $col) = $line->coord_of ($offset)
958=item $text = $term->special_encode $string 1476=item $text = $term->special_encode $string
959 1477
960Converts a perl string into the special encoding used by rxvt-unicode, 1478Converts a perl string into the special encoding used by rxvt-unicode,
961where one character corresponds to one screen cell. See 1479where one character corresponds to one screen cell. See
962C<< $term->ROW_t >> for details. 1480C<< $term->ROW_t >> for details.
964=item $string = $term->special_decode $text 1482=item $string = $term->special_decode $text
965 1483
966Converts rxvt-unicodes text reprsentation into a perl string. See 1484Converts rxvt-unicodes text reprsentation into a perl string. See
967C<< $term->ROW_t >> for details. 1485C<< $term->ROW_t >> for details.
968 1486
1487=item $success = $term->grab_button ($button, $modifiermask)
1488
1489Registers a synchronous button grab. See the XGrabButton manpage.
1490
1491=item $success = $term->grab ($eventtime[, $sync])
1492
1493Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1494synchronous (C<$sync> is true). Also remembers the grab timestampe.
1495
1496=item $term->allow_events_async
1497
1498Calls XAllowEvents with AsyncBoth for the most recent grab.
1499
1500=item $term->allow_events_sync
1501
1502Calls XAllowEvents with SyncBoth for the most recent grab.
1503
1504=item $term->allow_events_replay
1505
1506Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most
1507recent grab.
1508
1509=item $term->ungrab
1510
1511Calls XUngrab for the most recent grab. Is called automatically on
1512evaluation errors, as it is better to lose the grab in the error case as
1513the session.
1514
969=back 1515=back
970 1516
1517=cut
1518
1519package urxvt::popup;
1520
971=head2 The C<urxvt::popup> Class 1521=head2 The C<urxvt::popup> Class
972 1522
973=over 4 1523=over 4
974 1524
975=cut 1525=cut
976
977package urxvt::popup;
978 1526
979sub add_item { 1527sub add_item {
980 my ($self, $item) = @_; 1528 my ($self, $item) = @_;
981 1529
1530 $item->{rend}{normal} = "\x1b[0;30;47m" unless exists $item->{rend}{normal};
1531 $item->{rend}{hover} = "\x1b[0;30;46m" unless exists $item->{rend}{hover};
1532 $item->{rend}{active} = "\x1b[m" unless exists $item->{rend}{active};
1533
1534 $item->{render} ||= sub { $_[0]{text} };
1535
982 push @{ $self->{item} }, $item; 1536 push @{ $self->{item} }, $item;
983} 1537}
1538
1539=item $popup->add_title ($title)
1540
1541Adds a non-clickable title to the popup.
1542
1543=cut
1544
1545sub add_title {
1546 my ($self, $title) = @_;
1547
1548 $self->add_item ({
1549 rend => { normal => "\x1b[38;5;11;44m", hover => "\x1b[38;5;11;44m", active => "\x1b[38;5;11;44m" },
1550 text => $title,
1551 activate => sub { },
1552 });
1553}
1554
1555=item $popup->add_separator ([$sepchr])
1556
1557Creates a separator, optionally using the character given as C<$sepchr>.
1558
1559=cut
1560
1561sub add_separator {
1562 my ($self, $sep) = @_;
1563
1564 $sep ||= "=";
1565
1566 $self->add_item ({
1567 rend => { normal => "\x1b[0;30;47m", hover => "\x1b[0;30;47m", active => "\x1b[0;30;47m" },
1568 text => "",
1569 render => sub { $sep x $self->{term}->ncol },
1570 activate => sub { },
1571 });
1572}
1573
1574=item $popup->add_button ($text, $cb)
1575
1576Adds a clickable button to the popup. C<$cb> is called whenever it is
1577selected.
1578
1579=cut
984 1580
985sub add_button { 1581sub add_button {
986 my ($self, $text, $cb) = @_; 1582 my ($self, $text, $cb) = @_;
987 1583
988 $self->add_item ({ type => "button", text => "[ $text ]", activate => $cb }); 1584 $self->add_item ({ type => "button", text => $text, activate => $cb});
989} 1585}
1586
1587=item $popup->add_toggle ($text, $cb, $initial_value)
1588
1589Adds a toggle/checkbox item to the popup. Teh callback gets called
1590whenever it gets toggled, with a boolean indicating its value as its first
1591argument.
1592
1593=cut
1594
1595sub add_toggle {
1596 my ($self, $text, $cb, $value) = @_;
1597
1598 my $item; $item = {
1599 type => "button",
1600 text => " $text",
1601 value => $value,
1602 render => sub { ($_[0]{value} ? "* " : " ") . $text },
1603 activate => sub { $cb->($_[1]{value} = !$_[1]{value}); },
1604 };
1605
1606 $self->add_item ($item);
1607}
1608
1609=item $popup->show
1610
1611Displays the popup (which is initially hidden).
1612
1613=cut
990 1614
991sub show { 1615sub show {
992 my ($self) = @_; 1616 my ($self) = @_;
993 1617
994 local $urxvt::popup::self = $self; 1618 local $urxvt::popup::self = $self;
995 1619
996 urxvt->new ("--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0, 1620 my $env = $self->{term}->env;
1621 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
1622 delete $env->{LC_ALL};
1623 $env->{LC_CTYPE} = $self->{term}->locale;
1624
1625 urxvt::term->new ($env, "popup",
1626 "--perl-lib" => "", "--perl-ext-common" => "",
1627 "-pty-fd" => -1, "-sl" => 0,
1628 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect",
997 "--transient-for" => $self->{term}->parent, 1629 "--transient-for" => $self->{term}->parent,
1630 "-display" => $self->{term}->display_id,
998 "-pe" => "urxvt-popup") 1631 "-pe" => "urxvt-popup")
999 or die "unable to create popup window\n"; 1632 or die "unable to create popup window\n";
1000} 1633}
1001 1634
1002sub DESTROY { 1635sub DESTROY {
1003 my ($self) = @_; 1636 my ($self) = @_;
1004 1637
1638 delete $self->{term}{_destroy}{$self};
1005 $self->{term}->ungrab; 1639 $self->{term}->ungrab;
1006} 1640}
1641
1642=back
1007 1643
1008=head2 The C<urxvt::timer> Class 1644=head2 The C<urxvt::timer> Class
1009 1645
1010This class implements timer watchers/events. Time is represented as a 1646This class implements timer watchers/events. Time is represented as a
1011fractional number of seconds since the epoch. Example: 1647fractional number of seconds since the epoch. Example:
1050 1686
1051=item $timer = $timer->start ($tstamp) 1687=item $timer = $timer->start ($tstamp)
1052 1688
1053Set the event trigger time to C<$tstamp> and start the timer. 1689Set the event trigger time to C<$tstamp> and start the timer.
1054 1690
1691=item $timer = $timer->after ($delay)
1692
1693Like C<start>, but sets the expiry timer to c<urxvt::NOW + $delay>.
1694
1055=item $timer = $timer->stop 1695=item $timer = $timer->stop
1056 1696
1057Stop the timer. 1697Stop the timer.
1058 1698
1059=back 1699=back
1064 1704
1065 $term->{socket} = ... 1705 $term->{socket} = ...
1066 $term->{iow} = urxvt::iow 1706 $term->{iow} = urxvt::iow
1067 ->new 1707 ->new
1068 ->fd (fileno $term->{socket}) 1708 ->fd (fileno $term->{socket})
1069 ->events (1) # wait for read data 1709 ->events (urxvt::EVENT_READ)
1070 ->start 1710 ->start
1071 ->cb (sub { 1711 ->cb (sub {
1072 my ($iow, $revents) = @_; 1712 my ($iow, $revents) = @_;
1073 # $revents must be 1 here, no need to check 1713 # $revents must be 1 here, no need to check
1074 sysread $term->{socket}, my $buf, 8192 1714 sysread $term->{socket}, my $buf, 8192
1091 1731
1092Set the filedescriptor (not handle) to watch. 1732Set the filedescriptor (not handle) to watch.
1093 1733
1094=item $iow = $iow->events ($eventmask) 1734=item $iow = $iow->events ($eventmask)
1095 1735
1096Set the event mask to watch. Bit #0 (value C<1>) enables watching for read 1736Set the event mask to watch. The only allowed values are
1097data, Bit #1 (value C<2>) enables watching for write data. 1737C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed
1738together, or C<urxvt::EVENT_NONE>.
1098 1739
1099=item $iow = $iow->start 1740=item $iow = $iow->start
1100 1741
1101Start watching for requested events on the given handle. 1742Start watching for requested events on the given handle.
1102 1743
1113This variable controls the verbosity level of the perl extension. Higher 1754This variable controls the verbosity level of the perl extension. Higher
1114numbers indicate more verbose output. 1755numbers indicate more verbose output.
1115 1756
1116=over 4 1757=over 4
1117 1758
1118=item =0 - only fatal messages 1759=item == 0 - fatal messages
1119 1760
1120=item =3 - script loading and management 1761=item >= 3 - script loading and management
1121 1762
1122=item =10 - all events received 1763=item >=10 - all called hooks
1764
1765=item >=11 - hook reutrn values
1123 1766
1124=back 1767=back
1125 1768
1126=head1 AUTHOR 1769=head1 AUTHOR
1127 1770

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines