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.91 by root, Fri Jan 13 01:09:37 2006 UTC vs.
Revision 1.128 by root, Wed Jan 25 00:57:57 2006 UTC

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
40Or by adding them to the resource for extensions loaded by default:
41
42 URxvt.perl-ext-common: default,automove-background,selection-autotransform
39 43
40=over 4 44=over 4
41 45
42=item selection (enabled by default) 46=item selection (enabled by default)
43 47
63the match. For example, the followign adds a regex that matches everything 67the match. For example, the followign adds a regex that matches everything
64between two vertical bars: 68between two vertical bars:
65 69
66 URxvt.selection.pattern-0: \\|([^|]+)\\| 70 URxvt.selection.pattern-0: \\|([^|]+)\\|
67 71
72Another example: Programs I use often output "absolute path: " at the
73beginning of a line when they process multiple files. The following
74pattern matches the filename (note, there is a single space at the very
75end):
76
77 URxvt.selection.pattern-0: ^(/[^:]+):\
78
68You can look at the source of the selection extension to see more 79You can look at the source of the selection extension to see more
69interesting uses, such as parsing a line from beginning to end. 80interesting uses, such as parsing a line from beginning to end.
70 81
71This extension also offers the following bindable keyboard command: 82This extension also offers following bindable keyboard commands:
72 83
73=over 4 84=over 4
74 85
75=item rot13 86=item rot13
76 87
87 98
88=item selection-popup (enabled by default) 99=item selection-popup (enabled by default)
89 100
90Binds a popup menu to Ctrl-Button3 that lets you convert the selection 101Binds a popup menu to Ctrl-Button3 that lets you convert the selection
91text into various other formats/action (such as uri unescaping, perl 102text into various other formats/action (such as uri unescaping, perl
92evalution, web-browser starting etc.), depending on content. 103evaluation, web-browser starting etc.), depending on content.
104
105Other extensions can extend this popup menu by pushing a code reference
106onto C<@{ $term->{selection_popup_hook} }>, that is called whenever the
107popup is displayed.
108
109It's sole argument is the popup menu, which can be modified. The selection
110is in C<$_>, which can be used to decide wether to add something or not.
111It should either return nothing or a string and a code reference. The
112string will be used as button text and the code reference will be called
113when the button gets activated and should transform C<$_>.
114
115The following will add an entry C<a to b> that transforms all C<a>s in
116the selection to C<b>s, but only if the selection currently contains any
117C<a>s:
118
119 push @{ $self->{term}{selection_popup_hook} }, sub {
120 /a/ ? ("a to be" => sub { s/a/b/g }
121 : ()
122 };
93 123
94=item searchable-scrollback<hotkey> (enabled by default) 124=item searchable-scrollback<hotkey> (enabled by default)
95 125
96Adds regex search functionality to the scrollback buffer, triggered 126Adds regex search functionality to the scrollback buffer, triggered
97by a hotkey (default: C<M-s>). While in search mode, normal terminal 127by a hotkey (default: C<M-s>). While in search mode, normal terminal
104bottom. C<Escape> leaves search mode and returns to the point where search 134bottom. C<Escape> leaves search mode and returns to the point where search
105was started, while C<Enter> or C<Return> stay at the current position and 135was started, while C<Enter> or C<Return> stay at the current position and
106additionally stores the first match in the current line into the primary 136additionally stores the first match in the current line into the primary
107selection. 137selection.
108 138
139=item readline (enabled by default)
140
141A support package that tries to make editing with readline easier. At the
142moment, it reacts to clicking with the left mouse button by trying to
143move the text cursor to this position. It does so by generating as many
144cursor-left or cursor-right keypresses as required (the this only works
145for programs that correctly support wide characters).
146
147To avoid too many false positives, this is only done when:
148
149=over 4
150
151=item - the tty is in ICANON state.
152
153=item - the text cursor is visible.
154
155=item - the primary screen is currently being displayed.
156
157=item - the mouse is on the same (multi-row-) line as the text cursor.
158
159=back
160
161The normal selection mechanism isn't disabled, so quick successive clicks
162might interfere with selection creation in harmless ways.
163
109=item selection-autotransform 164=item selection-autotransform
110 165
111This selection allows you to do automatic transforms on a selection 166This selection allows you to do automatic transforms on a selection
112whenever a selection is made. 167whenever a selection is made.
113 168
120 175
121For example, the following will transform selections of the form 176For example, the following will transform selections of the form
122C<filename:number>, often seen in compiler messages, into C<vi +$filename 177C<filename:number>, often seen in compiler messages, into C<vi +$filename
123$word>: 178$word>:
124 179
125 URxvt.selection-autotransform.0: s/^(\\S+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/ 180 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
126 181
127And this example matches the same,but replaces it with vi-commands you can 182And this example matches the same,but replaces it with vi-commands you can
128paste directly into your (vi :) editor: 183paste directly into your (vi :) editor:
129 184
130 URxvt.selection-autotransform.0: s/^(S+):(d+):?$/\\x1b:e \\Q$1\\E\\x0d:$2\\x0d/ 185 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/
131 186
132Of course, this can be modified to suit your needs and your editor :) 187Of course, this can be modified to suit your needs and your editor :)
133 188
134To expand the example above to typical perl error messages ("XXX at 189To expand the example above to typical perl error messages ("XXX at
135FILENAME line YYY."), you need a slightly more elaborate solution: 190FILENAME line YYY."), you need a slightly more elaborate solution:
136 191
137 URxvt.selection.pattern-0: ( at .*? line \\d+\\.) 192 URxvt.selection.pattern-0: ( at .*? line \\d+[,.])
138 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)\\.$/\x1b:e \\Q$1\E\\x0d:$2\\x0d/ 193 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/
139 194
140The first line tells the selection code to treat the unchanging part of 195The first line tells the selection code to treat the unchanging part of
141every error message as a selection pattern, and the second line transforms 196every error message as a selection pattern, and the second line transforms
142the message into vi commands to load the file. 197the message into vi commands to load the file.
198
199=item tabbed
200
201This transforms the terminal into a tabbar with additional terminals, that
202is, it implements what is commonly refered to as "tabbed terminal". The topmost line
203displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one
204button per tab.
205
206Clicking a button will activate that tab. Pressing B<Shift-Left> and
207B<Shift-Right> will switch to the tab left or right of the current one,
208while B<Shift-Down> creates a new tab.
143 209
144=item mark-urls 210=item mark-urls
145 211
146Uses per-line display filtering (C<on_line_update>) to underline urls and 212Uses per-line display filtering (C<on_line_update>) to underline urls and
147make them clickable. When middle-clicked, the program specified in the 213make them clickable. When middle-clicked, the program specified in the
148resource C<urlLauncher> (default C<x-www-browser>) will be started with 214resource C<urlLauncher> (default C<x-www-browser>) will be started with
149the URL as first argument. 215the URL as first argument.
150 216
217=item xim-onthespot
218
219This (experimental) perl extension implements OnTheSpot editing. It does
220not work perfectly, and some input methods don't seem to work well with
221OnTheSpot editing in general, but it seems to work at leats for SCIM and
222kinput2.
223
224You enable it by specifying this extension and a preedit style of
225C<OnTheSpot>, i.e.:
226
227 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot
228
229=item automove-background
230
231This is basically a one-line extension that dynamically changes the background pixmap offset
232to the window position, in effect creating the same effect as pseudo transparency with
233a custom pixmap. No scaling is supported in this mode. Exmaple:
234
235 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background
236
151=item block-graphics-to-ascii 237=item block-graphics-to-ascii
152 238
153A not very useful example of filtering all text output to the terminal, 239A not very useful example of filtering all text output to the terminal,
154by replacing all line-drawing characters (U+2500 .. U+259F) by a 240by replacing all line-drawing characters (U+2500 .. U+259F) by a
155similar-looking ascii character. 241similar-looking ascii character.
161=item example-refresh-hooks 247=item example-refresh-hooks
162 248
163Displays a very simple digital clock in the upper right corner of the 249Displays a very simple digital clock in the upper right corner of the
164window. Illustrates overwriting the refresh callbacks to create your own 250window. Illustrates overwriting the refresh callbacks to create your own
165overlays or changes. 251overlays or changes.
252
253=item selection-pastebin
254
255This is a little rarely useful extension that Uploads the selection as
256textfile to a remote site (or does other things). (The implementation is
257not currently secure for use in a multiuser environment as it writes to
258F</tmp> directly.).
259
260It listens to the C<selection-pastebin:remote-pastebin> keyboard command,
261i.e.
262
263 URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin
264
265Pressing this combination runs a command with C<%> replaced by the name of
266the textfile. This command can be set via a resource:
267
268 URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
269
270And the default is likely not useful to anybody but the few people around
271here :)
272
273The name of the textfile is the hex encoded md5 sum of the selection, so
274the same content should lead to the same filename.
275
276After a successful upload the selection will be replaced by the text given
277in the C<selection-pastebin-url> resource (again, the % is the placeholder
278for the filename):
279
280 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
166 281
167=back 282=back
168 283
169=head1 API DOCUMENTATION 284=head1 API DOCUMENTATION
170 285
243called whenever the relevant event happens. 358called whenever the relevant event happens.
244 359
245The first argument passed to them is an extension oject as described in 360The first argument passed to them is an extension oject as described in
246the in the C<Extension Objects> section. 361the in the C<Extension Objects> section.
247 362
248B<All> of these hooks must return a boolean value. If it is true, then the 363B<All> of these hooks must return a boolean value. If any of the called
249event counts as being I<consumed>, and the invocation of other hooks is 364hooks returns true, then the event counts as being I<consumed>, and the
250skipped, and the relevant action might not be carried out by the C++ code. 365relevant action might not be carried out by the C++ code.
251 366
252I<< When in doubt, return a false value (preferably C<()>). >> 367I<< When in doubt, return a false value (preferably C<()>). >>
253 368
254=over 4 369=over 4
255 370
256=item on_init $term 371=item on_init $term
257 372
258Called after a new terminal object has been initialized, but before 373Called after a new terminal object has been initialized, but before
259windows are created or the command gets run. Most methods are unsafe to 374windows are created or the command gets run. Most methods are unsafe to
260call or deliver senseless data, as terminal size and other characteristics 375call or deliver senseless data, as terminal size and other characteristics
261have not yet been determined. You can safely query and change resources, 376have not yet been determined. You can safely query and change resources
262though. 377and options, though. For many purposes the C<on_start> hook is a better
378place.
379
380=item on_start $term
381
382Called at the very end of initialisation of a new terminal, just before
383trying to map (display) the toplevel and returning to the mainloop.
384
385=item on_destroy $term
386
387Called whenever something tries to destroy terminal, when the terminal is
388still fully functional (not for long, though).
263 389
264=item on_reset $term 390=item on_reset $term
265 391
266Called after the screen is "reset" for any reason, such as resizing or 392Called after the screen is "reset" for any reason, such as resizing or
267control sequences. Here is where you can react on changes to size-related 393control sequences. Here is where you can react on changes to size-related
268variables. 394variables.
269 395
270=item on_start $term 396=item on_child_start $term, $pid
271 397
272Called at the very end of initialisation of a new terminal, just before 398Called just after the child process has been C<fork>ed.
273returning to the mainloop. 399
400=item on_child_exit $term, $status
401
402Called just after the child process has exited. C<$status> is the status
403from C<waitpid>.
274 404
275=item on_sel_make $term, $eventtime 405=item on_sel_make $term, $eventtime
276 406
277Called whenever a selection has been made by the user, but before the 407Called whenever a selection has been made by the user, but before the
278selection text is copied, so changes to the beginning, end or type of the 408selection text is copied, so changes to the beginning, end or type of the
371 501
372Called whenever the user presses a key combination that has a 502Called whenever the user presses a key combination that has a
373C<perl:string> action bound to it (see description of the B<keysym> 503C<perl:string> action bound to it (see description of the B<keysym>
374resource in the @@RXVT_NAME@@(1) manpage). 504resource in the @@RXVT_NAME@@(1) manpage).
375 505
506=item on_x_event $term, $event
507
508Called on every X event received on the vt window (and possibly other
509windows). Should only be used as a last resort. Most event structure
510members are not passed.
511
376=item on_focus_in $term 512=item on_focus_in $term
377 513
378Called whenever the window gets the keyboard focus, before rxvt-unicode 514Called whenever the window gets the keyboard focus, before rxvt-unicode
379does focus in processing. 515does focus in processing.
380 516
381=item on_focus_out $term 517=item on_focus_out $term
382 518
383Called wheneever the window loses keyboard focus, before rxvt-unicode does 519Called wheneever the window loses keyboard focus, before rxvt-unicode does
384focus out processing. 520focus out processing.
385 521
522=item on_configure_notify $term, $event
523
524=item on_property_notify $term, $event
525
386=item on_key_press $term, $event, $keysym, $octets 526=item on_key_press $term, $event, $keysym, $octets
387 527
388=item on_key_release $term, $event, $keysym 528=item on_key_release $term, $event, $keysym
389 529
390=item on_button_press $term, $event 530=item on_button_press $term, $event
399 539
400Called whenever the corresponding X event is received for the terminal If 540Called whenever the corresponding X event is received for the terminal If
401the hook returns true, then the even will be ignored by rxvt-unicode. 541the hook returns true, then the even will be ignored by rxvt-unicode.
402 542
403The event is a hash with most values as named by Xlib (see the XEvent 543The event is a hash with most values as named by Xlib (see the XEvent
404manpage), with the additional members C<row> and C<col>, which are the row 544manpage), with the additional members C<row> and C<col>, which are the
405and column under the mouse cursor. 545(real, not screen-based) row and column under the mouse cursor.
406 546
407C<on_key_press> additionally receives the string rxvt-unicode would 547C<on_key_press> additionally receives the string rxvt-unicode would
408output, if any, in locale-specific encoding. 548output, if any, in locale-specific encoding.
409 549
410subwindow. 550subwindow.
551
552=item on_client_message $term, $event
553
554=item on_wm_protocols $term, $event
555
556=item on_wm_delete_window $term, $event
557
558Called when various types of ClientMessage events are received (all with
559format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
411 560
412=back 561=back
413 562
414=cut 563=cut
415 564
421use Scalar::Util (); 570use Scalar::Util ();
422use List::Util (); 571use List::Util ();
423 572
424our $VERSION = 1; 573our $VERSION = 1;
425our $TERM; 574our $TERM;
575our @TERM_INIT;
576our @TERM_EXT;
426our @HOOKNAME; 577our @HOOKNAME;
427our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME; 578our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
428our %OPTION; 579our %OPTION;
429 580
430our $LIBDIR; 581our $LIBDIR;
431our $RESNAME; 582our $RESNAME;
432our $RESCLASS; 583our $RESCLASS;
433our $RXVTNAME; 584our $RXVTNAME;
434 585
586our $NOCHAR = chr 0xffff;
587
435=head2 Variables in the C<urxvt> Package 588=head2 Variables in the C<urxvt> Package
436 589
437=over 4 590=over 4
438 591
439=item $urxvt::LIBDIR 592=item $urxvt::LIBDIR
451 604
452=item $urxvt::TERM 605=item $urxvt::TERM
453 606
454The current terminal. This variable stores the current C<urxvt::term> 607The current terminal. This variable stores the current C<urxvt::term>
455object, whenever a callback/hook is executing. 608object, whenever a callback/hook is executing.
609
610=item @urxvt::TERM_INIT
611
612All coderefs in this array will be called as methods of the next newly
613created C<urxvt::term> object (during the C<on_init> phase). The array
614gets cleared before the codereferences that were in it are being executed,
615so coderefs can push themselves onto it again if they so desire.
616
617This complements to the perl-eval commandline option, but gets executed
618first.
619
620=item @urxvt::TERM_EXT
621
622Works similar to C<@TERM_INIT>, but contains perl package/class names, which
623get registered as normal extensions after calling the hooks in C<@TERM_INIT>
624but before other extensions. Gets cleared just like C<@TERM_INIT>.
456 625
457=back 626=back
458 627
459=head2 Functions in the C<urxvt> Package 628=head2 Functions in the C<urxvt> Package
460 629
475Using this function has the advantage that its output ends up in the 644Using this function has the advantage that its output ends up in the
476correct place, e.g. on stderr of the connecting urxvtc client. 645correct place, e.g. on stderr of the connecting urxvtc client.
477 646
478Messages have a size limit of 1023 bytes currently. 647Messages have a size limit of 1023 bytes currently.
479 648
480=item $is_safe = urxvt::safe
481
482Returns true when it is safe to do potentially unsafe things, such as
483evaluating perl code specified by the user. This is true when urxvt was
484started setuid or setgid.
485
486=item $time = urxvt::NOW 649=item $time = urxvt::NOW
487 650
488Returns the "current time" (as per the event loop). 651Returns the "current time" (as per the event loop).
489 652
490=item urxvt::CurrentTime 653=item urxvt::CurrentTime
491 654
492=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, 655=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
493Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, 656Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
494Button4Mask, Button5Mask, AnyModifier 657Button4Mask, Button5Mask, AnyModifier
658
659=item urxvt::NoEventMask, KeyPressMask, KeyReleaseMask,
660ButtonPressMask, ButtonReleaseMask, EnterWindowMask, LeaveWindowMask,
661PointerMotionMask, PointerMotionHintMask, Button1MotionMask, Button2MotionMask,
662Button3MotionMask, Button4MotionMask, Button5MotionMask, ButtonMotionMask,
663KeymapStateMask, ExposureMask, VisibilityChangeMask, StructureNotifyMask,
664ResizeRedirectMask, SubstructureNotifyMask, SubstructureRedirectMask,
665FocusChangeMask, PropertyChangeMask, ColormapChangeMask, OwnerGrabButtonMask
666
667=item urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify,
668EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose,
669GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify, DestroyNotify,
670UnmapNotify, MapNotify, MapRequest, ReparentNotify, ConfigureNotify,
671ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify,
672CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest,
673SelectionNotify, ColormapNotify, ClientMessage, MappingNotify
495 674
496Various constants for use in X calls and event processing. 675Various constants for use in X calls and event processing.
497 676
498=back 677=back
499 678
550=back 729=back
551 730
552=cut 731=cut
553 732
554BEGIN { 733BEGIN {
555 urxvt->bootstrap;
556
557 # overwrite perl's warn 734 # overwrite perl's warn
558 *CORE::GLOBAL::warn = sub { 735 *CORE::GLOBAL::warn = sub {
559 my $msg = join "", @_; 736 my $msg = join "", @_;
560 $msg .= "\n" 737 $msg .= "\n"
561 unless $msg =~ /\n$/; 738 unless $msg =~ /\n$/;
562 urxvt::warn ($msg); 739 urxvt::warn ($msg);
563 }; 740 };
564
565 # %ENV is the original startup environment
566 delete $ENV{IFS};
567 delete $ENV{CDPATH};
568 delete $ENV{BASH_ENV};
569 $ENV{PATH} = "/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/opt/bin:/opt/sbin";
570} 741}
571 742
572my @hook_count; 743no warnings 'utf8';
744
573my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 745my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
574 746
575sub verbose { 747sub verbose {
576 my ($level, $msg) = @_; 748 my ($level, $msg) = @_;
577 warn "$msg\n" if $level <= $verbosity; 749 warn "$msg\n" if $level <= $verbosity;
578} 750}
579 751
580my $extension_pkg = "extension0000";
581my %extension_pkg; 752my %extension_pkg;
582 753
583# load a single script into its own package, once only 754# load a single script into its own package, once only
584sub extension_package($) { 755sub extension_package($) {
585 my ($path) = @_; 756 my ($path) = @_;
586 757
587 $extension_pkg{$path} ||= do { 758 $extension_pkg{$path} ||= do {
588 my $pkg = "urxvt::" . ($extension_pkg++); 759 $path =~ /([^\/\\]+)$/;
760 my $pkg = $1;
761 $pkg =~ s/[^[:word:]]/_/g;
762 $pkg = "urxvt::ext::$pkg";
589 763
590 verbose 3, "loading extension '$path' into package '$pkg'"; 764 verbose 3, "loading extension '$path' into package '$pkg'";
591 765
592 open my $fh, "<:raw", $path 766 open my $fh, "<:raw", $path
593 or die "$path: $!"; 767 or die "$path: $!";
594 768
595 my $source = untaint 769 my $source =
596 "package $pkg; use strict; use utf8;\n" 770 "package $pkg; use strict; use utf8; no warnings 'utf8';\n"
597 . "use base urxvt::term::extension::;\n"
598 . "#line 1 \"$path\"\n{\n" 771 . "#line 1 \"$path\"\n{\n"
599 . (do { local $/; <$fh> }) 772 . (do { local $/; <$fh> })
600 . "\n};\n1"; 773 . "\n};\n1";
601 774
602 eval $source 775 eval $source
616 if ($htype == 0) { # INIT 789 if ($htype == 0) { # INIT
617 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 790 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
618 791
619 my %ext_arg; 792 my %ext_arg;
620 793
794 {
795 my @init = @TERM_INIT;
796 @TERM_INIT = ();
797 $_->($TERM) for @init;
798 my @pkg = @TERM_EXT;
799 @TERM_EXT = ();
800 $TERM->register_package ($_) for @pkg;
801 }
802
621 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) { 803 for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
622 if ($_ eq "default") { 804 if ($_ eq "default") {
623 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback); 805 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback readline);
624 } elsif (/^-(.*)$/) { 806 } elsif (/^-(.*)$/) {
625 delete $ext_arg{$1}; 807 delete $ext_arg{$1};
626 } elsif (/^([^<]+)<(.*)>$/) { 808 } elsif (/^([^<]+)<(.*)>$/) {
627 push @{ $ext_arg{$1} }, $2; 809 push @{ $ext_arg{$1} }, $2;
628 } else { 810 } else {
651 if $verbosity >= 10; 833 if $verbosity >= 10;
652 834
653 keys %$cb; 835 keys %$cb;
654 836
655 while (my ($pkg, $cb) = each %$cb) { 837 while (my ($pkg, $cb) = each %$cb) {
656 $retval = eval { $cb->($TERM->{_pkg}{$pkg}, @_) } 838 my $retval_ = eval { $cb->($TERM->{_pkg}{$pkg}, @_) };
657 and last; 839 $retval ||= $retval_;
658 840
659 if ($@) { 841 if ($@) {
660 $TERM->ungrab; # better to lose the grab than the session 842 $TERM->ungrab; # better to lose the grab than the session
661 warn $@; 843 warn $@;
662 } 844 }
665 verbose 11, "$HOOKNAME[$htype] returning <$retval>" 847 verbose 11, "$HOOKNAME[$htype] returning <$retval>"
666 if $verbosity >= 11; 848 if $verbosity >= 11;
667 } 849 }
668 850
669 if ($htype == 1) { # DESTROY 851 if ($htype == 1) { # DESTROY
670 if (my $hook = delete $TERM->{_hook}) {
671 for my $htype (0..$#$hook) {
672 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
673 or set_should_invoke $htype, 0;
674 }
675 }
676
677 # clear package objects 852 # clear package objects
678 %$_ = () for values %{ $TERM->{_pkg} }; 853 %$_ = () for values %{ $TERM->{_pkg} };
679 854
680 # clear package 855 # clear package
681 %$TERM = (); 856 %$TERM = ();
682 } 857 }
683 858
684 $retval 859 $retval
685}
686
687sub exec_async(@) {
688 my $pid = fork;
689
690 return
691 if !defined $pid or $pid;
692
693 %ENV = %{ $TERM->env };
694
695 exec @_;
696 _exit 255;
697} 860}
698 861
699# urxvt::term::extension 862# urxvt::term::extension
700 863
701package urxvt::term::extension; 864package urxvt::term::extension;
707 while (my ($name, $cb) = each %hook) { 870 while (my ($name, $cb) = each %hook) {
708 my $htype = $HOOKTYPE{uc $name}; 871 my $htype = $HOOKTYPE{uc $name};
709 defined $htype 872 defined $htype
710 or Carp::croak "unsupported hook type '$name'"; 873 or Carp::croak "unsupported hook type '$name'";
711 874
875 $self->set_should_invoke ($htype, +1)
712 unless (exists $self->{term}{_hook}[$htype]{$pkg}) { 876 unless exists $self->{term}{_hook}[$htype]{$pkg};
713 $hook_count[$htype]++
714 or urxvt::set_should_invoke $htype, 1;
715 }
716 877
717 $self->{term}{_hook}[$htype]{$pkg} = $cb; 878 $self->{term}{_hook}[$htype]{$pkg} = $cb;
718 } 879 }
719} 880}
720 881
725 for my $name (@hook) { 886 for my $name (@hook) {
726 my $htype = $HOOKTYPE{uc $name}; 887 my $htype = $HOOKTYPE{uc $name};
727 defined $htype 888 defined $htype
728 or Carp::croak "unsupported hook type '$name'"; 889 or Carp::croak "unsupported hook type '$name'";
729 890
891 $self->set_should_invoke ($htype, -1)
730 if (delete $self->{term}{_hook}[$htype]{$pkg}) { 892 if delete $self->{term}{_hook}[$htype]{$pkg};
731 --$hook_count[$htype]
732 or urxvt::set_should_invoke $htype, 0;
733 }
734 } 893 }
735} 894}
736 895
737our $AUTOLOAD; 896our $AUTOLOAD;
738 897
844# find on_xxx subs in the package and register them 1003# find on_xxx subs in the package and register them
845# as hooks 1004# as hooks
846sub register_package { 1005sub register_package {
847 my ($self, $pkg, $argv) = @_; 1006 my ($self, $pkg, $argv) = @_;
848 1007
1008 no strict 'refs';
1009
1010 urxvt::verbose 6, "register package $pkg to $self";
1011
1012 @{"$pkg\::ISA"} = urxvt::term::extension::;
1013
849 my $proxy = bless { 1014 my $proxy = bless {
850 _pkg => $pkg, 1015 _pkg => $pkg,
851 argv => $argv, 1016 argv => $argv,
852 }, $pkg; 1017 }, $pkg;
853 Scalar::Util::weaken ($proxy->{term} = $self); 1018 Scalar::Util::weaken ($proxy->{term} = $self);
884 1049
885Destroy the terminal object (close the window, free resources 1050Destroy the terminal object (close the window, free resources
886etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event 1051etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event
887watchers (timers, io watchers) are still active. 1052watchers (timers, io watchers) are still active.
888 1053
1054=item $term->exec_async ($cmd[, @args])
1055
1056Works like the combination of the C<fork>/C<exec> builtins, which executes
1057("starts") programs in the background. This function takes care of setting
1058the user environment before exec'ing the command (e.g. C<PATH>) and should
1059be preferred over explicit calls to C<exec> or C<system>.
1060
1061Returns the pid of the subprocess or C<undef> on error.
1062
1063=cut
1064
1065sub exec_async {
1066 my $self = shift;
1067
1068 my $pid = fork;
1069
1070 return $pid
1071 if !defined $pid or $pid;
1072
1073 %ENV = %{ $self->env };
1074
1075 exec @_;
1076 urxvt::_exit 255;
1077}
1078
889=item $isset = $term->option ($optval[, $set]) 1079=item $isset = $term->option ($optval[, $set])
890 1080
891Returns true if the option specified by C<$optval> is enabled, and 1081Returns true if the option specified by C<$optval> is enabled, and
892optionally change it. All option values are stored by name in the hash 1082optionally change it. All option values are stored by name in the hash
893C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash. 1083C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
895Here is a a likely non-exhaustive list of option names, please see the 1085Here is a a likely non-exhaustive list of option names, please see the
896source file F</src/optinc.h> to see the actual list: 1086source file F</src/optinc.h> to see the actual list:
897 1087
898 borderLess console cursorBlink cursorUnderline hold iconic insecure 1088 borderLess console cursorBlink cursorUnderline hold iconic insecure
899 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 1089 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
900 pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating 1090 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
901 scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer 1091 scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput
902 secondaryScreen secondaryScroll skipBuiltinGlyphs transparent 1092 scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs
903 tripleclickwords utmpInhibit visualBell 1093 transparent tripleclickwords utmpInhibit visualBell
904 1094
905=item $value = $term->resource ($name[, $newval]) 1095=item $value = $term->resource ($name[, $newval])
906 1096
907Returns the current resource value associated with a given name and 1097Returns the current resource value associated with a given name and
908optionally sets a new value. Setting values is most useful in the C<init> 1098optionally sets a new value. Setting values is most useful in the C<init>
925 1115
926 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1116 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
927 borderLess color cursorBlink cursorUnderline cutchars delete_key 1117 borderLess color cursorBlink cursorUnderline cutchars delete_key
928 display_name embed ext_bwidth fade font geometry hold iconName 1118 display_name embed ext_bwidth fade font geometry hold iconName
929 imFont imLocale inputMethod insecure int_bwidth intensityStyles 1119 imFont imLocale inputMethod insecure int_bwidth intensityStyles
930 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier 1120 italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier
931 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2 1121 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
932 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 1122 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
933 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 1123 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
934 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 1124 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
935 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 1125 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
936 shade term_name title transparent transparent_all tripleclickwords 1126 secondaryScreen secondaryScroll selectstyle shade term_name title
937 utmpInhibit visualBell 1127 transient_for transparent transparent_all tripleclickwords utmpInhibit
1128 visualBell
938 1129
939=cut 1130=cut
940 1131
941sub resource($$;$) { 1132sub resource($$;$) {
942 my ($self, $name) = (shift, shift); 1133 my ($self, $name) = (shift, shift);
1116 1307
1117Normally its not a good idea to use this function, as programs might be 1308Normally its not a good idea to use this function, as programs might be
1118confused by changes in cursor position or scrolling. Its useful inside a 1309confused by changes in cursor position or scrolling. Its useful inside a
1119C<on_add_lines> hook, though. 1310C<on_add_lines> hook, though.
1120 1311
1312=item $term->scr_change_screen ($screen)
1313
1314Switch to given screen - 0 primary, 1 secondary.
1315
1121=item $term->cmd_parse ($octets) 1316=item $term->cmd_parse ($octets)
1122 1317
1123Similar to C<scr_add_lines>, but the argument must be in the 1318Similar to C<scr_add_lines>, but the argument must be in the
1124locale-specific encoding of the terminal and can contain command sequences 1319locale-specific encoding of the terminal and can contain command sequences
1125(escape codes) that will be interpreted. 1320(escape codes) that will be interpreted.
1135Replaces the event mask of the pty watcher by the given event mask. Can 1330Replaces the event mask of the pty watcher by the given event mask. Can
1136be used to suppress input and output handling to the pty/tty. See the 1331be used to suppress input and output handling to the pty/tty. See the
1137description of C<< urxvt::timer->events >>. Make sure to always restore 1332description of C<< urxvt::timer->events >>. Make sure to always restore
1138the previous value. 1333the previous value.
1139 1334
1335=item $fd = $term->pty_fd
1336
1337Returns the master file descriptor for the pty in use, or C<-1> if no pty
1338is used.
1339
1140=item $windowid = $term->parent 1340=item $windowid = $term->parent
1141 1341
1142Return the window id of the toplevel window. 1342Return the window id of the toplevel window.
1143 1343
1144=item $windowid = $term->vt 1344=item $windowid = $term->vt
1145 1345
1146Return the window id of the terminal window. 1346Return the window id of the terminal window.
1147 1347
1348=item $term->vt_emask_add ($x_event_mask)
1349
1350Adds the specified events to the vt event mask. Useful e.g. when you want
1351to receive pointer events all the times:
1352
1353 $term->vt_emask_add (urxvt::PointerMotionMask);
1354
1148=item $window_width = $term->width 1355=item $window_width = $term->width
1149 1356
1150=item $window_height = $term->height 1357=item $window_height = $term->height
1151 1358
1152=item $font_width = $term->fwidth 1359=item $font_width = $term->fwidth
1165 1372
1166=item $max_scrollback = $term->saveLines 1373=item $max_scrollback = $term->saveLines
1167 1374
1168=item $nrow_plus_saveLines = $term->total_rows 1375=item $nrow_plus_saveLines = $term->total_rows
1169 1376
1170=item $lines_in_scrollback = $term->nsaved 1377=item $topmost_scrollback_row = $term->top_row
1171 1378
1172Return various integers describing terminal characteristics. 1379Return various integers describing terminal characteristics.
1173 1380
1174=item $x_display = $term->display_id 1381=item $x_display = $term->display_id
1175 1382
1201=item $modifiermask = $term->ModNumLockMask 1408=item $modifiermask = $term->ModNumLockMask
1202 1409
1203Return the modifier masks corresponding to the "ISO Level 3 Shift" (often 1410Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
1204AltGr), the meta key (often Alt) and the num lock key, if applicable. 1411AltGr), the meta key (often Alt) and the num lock key, if applicable.
1205 1412
1413=item $screen = $term->current_screen
1414
1415Returns the currently displayed screen (0 primary, 1 secondary).
1416
1417=item $cursor_is_hidden = $term->hidden_cursor
1418
1419Returns wether the cursor is currently hidden or not.
1420
1206=item $view_start = $term->view_start ([$newvalue]) 1421=item $view_start = $term->view_start ([$newvalue])
1207 1422
1208Returns the negative row number of the topmost line. Minimum value is 1423Returns the row number of the topmost displayed line. Maximum value is
1209C<0>, which displays the normal terminal contents. Larger values scroll 1424C<0>, which displays the normal terminal contents. Lower values scroll
1210this many lines into the scrollback buffer. 1425this many lines into the scrollback buffer.
1211 1426
1212=item $term->want_refresh 1427=item $term->want_refresh
1213 1428
1214Requests a screen refresh. At the next opportunity, rxvt-unicode will 1429Requests a screen refresh. At the next opportunity, rxvt-unicode will
1229line, starting at column C<$start_col> (default C<0>), which is useful 1444line, starting at column C<$start_col> (default C<0>), which is useful
1230to replace only parts of a line. The font index in the rendition will 1445to replace only parts of a line. The font index in the rendition will
1231automatically be updated. 1446automatically be updated.
1232 1447
1233C<$text> is in a special encoding: tabs and wide characters that use more 1448C<$text> is in a special encoding: tabs and wide characters that use more
1234than one cell when displayed are padded with urxvt::NOCHAR characters 1449than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535)
1235(C<chr 65535>). Characters with combining characters and other characters 1450characters. Characters with combining characters and other characters that
1236that do not fit into the normal tetx encoding will be replaced with 1451do not fit into the normal tetx encoding will be replaced with characters
1237characters in the private use area. 1452in the private use area.
1238 1453
1239You have to obey this encoding when changing text. The advantage is 1454You have to obey this encoding when changing text. The advantage is
1240that C<substr> and similar functions work on screen cells and not on 1455that C<substr> and similar functions work on screen cells and not on
1241characters. 1456characters.
1242 1457
1417 1632
1418Calls XUngrab for the most recent grab. Is called automatically on 1633Calls XUngrab for the most recent grab. Is called automatically on
1419evaluation errors, as it is better to lose the grab in the error case as 1634evaluation errors, as it is better to lose the grab in the error case as
1420the session. 1635the session.
1421 1636
1637=item $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
1638
1639=item $atom_name = $term->XGetAtomName ($atom)
1640
1641=item @atoms = $term->XListProperties ($window)
1642
1643=item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
1644
1645=item $term->XChangeWindowProperty ($window, $property, $type, $format, $octets)
1646
1647=item $term->XDeleteProperty ($window, $property)
1648
1649=item $window = $term->DefaultRootWindow
1650
1651=item $term->XReparentWindow ($window, $parent, [$x, $y])
1652
1653=item $term->XMapWindow ($window)
1654
1655=item $term->XUnmapWindow ($window)
1656
1657=item $term->XMoveResizeWindow ($window, $x, $y, $width, $height)
1658
1659=item ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x, $y)
1660
1661=item $term->XChangeInput ($window, $add_events[, $del_events])
1662
1663Various X or X-related functions. The C<$term> object only serves as
1664the source of the display, otherwise those functions map more-or-less
1665directory onto the X functions of the same name.
1666
1422=back 1667=back
1423 1668
1424=cut 1669=cut
1425 1670
1426package urxvt::popup; 1671package urxvt::popup;
1527 my $env = $self->{term}->env; 1772 my $env = $self->{term}->env;
1528 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE. 1773 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
1529 delete $env->{LC_ALL}; 1774 delete $env->{LC_ALL};
1530 $env->{LC_CTYPE} = $self->{term}->locale; 1775 $env->{LC_CTYPE} = $self->{term}->locale;
1531 1776
1532 urxvt::term->new ($env, $self->{term}->resource ("name"), 1777 urxvt::term->new ($env, "popup",
1533 "--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0, 1778 "--perl-lib" => "", "--perl-ext-common" => "",
1779 "-pty-fd" => -1, "-sl" => 0,
1780 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect",
1534 "--transient-for" => $self->{term}->parent, 1781 "--transient-for" => $self->{term}->parent,
1535 "-display" => $self->{term}->display_id, 1782 "-display" => $self->{term}->display_id,
1536 "-pe" => "urxvt-popup") 1783 "-pe" => "urxvt-popup")
1537 or die "unable to create popup window\n"; 1784 or die "unable to create popup window\n";
1538} 1785}
1543 delete $self->{term}{_destroy}{$self}; 1790 delete $self->{term}{_destroy}{$self};
1544 $self->{term}->ungrab; 1791 $self->{term}->ungrab;
1545} 1792}
1546 1793
1547=back 1794=back
1795
1796=cut
1797
1798package urxvt::watcher;
1799
1800@urxvt::timer::ISA = __PACKAGE__;
1801@urxvt::iow::ISA = __PACKAGE__;
1802@urxvt::pw::ISA = __PACKAGE__;
1803@urxvt::iw::ISA = __PACKAGE__;
1548 1804
1549=head2 The C<urxvt::timer> Class 1805=head2 The C<urxvt::timer> Class
1550 1806
1551This class implements timer watchers/events. Time is represented as a 1807This class implements timer watchers/events. Time is represented as a
1552fractional number of seconds since the epoch. Example: 1808fractional number of seconds since the epoch. Example:
1590Start the timer. 1846Start the timer.
1591 1847
1592=item $timer = $timer->start ($tstamp) 1848=item $timer = $timer->start ($tstamp)
1593 1849
1594Set the event trigger time to C<$tstamp> and start the timer. 1850Set the event trigger time to C<$tstamp> and start the timer.
1851
1852=item $timer = $timer->after ($delay)
1853
1854Like C<start>, but sets the expiry timer to c<urxvt::NOW + $delay>.
1595 1855
1596=item $timer = $timer->stop 1856=item $timer = $timer->stop
1597 1857
1598Stop the timer. 1858Stop the timer.
1599 1859
1646 1906
1647Stop watching for events on the given filehandle. 1907Stop watching for events on the given filehandle.
1648 1908
1649=back 1909=back
1650 1910
1911=head2 The C<urxvt::iw> Class
1912
1913This class implements idle watchers, that get called automatically when
1914the process is idle. They should return as fast as possible, after doing
1915some useful work.
1916
1917=over 4
1918
1919=item $iw = new urxvt::iw
1920
1921Create a new idle watcher object in stopped state.
1922
1923=item $iw = $iw->cb (sub { my ($iw) = @_; ... })
1924
1925Set the callback to be called when the watcher triggers.
1926
1927=item $timer = $timer->start
1928
1929Start the watcher.
1930
1931=item $timer = $timer->stop
1932
1933Stop the watcher.
1934
1935=back
1936
1937=head2 The C<urxvt::pw> Class
1938
1939This class implements process watchers. They create an event whenever a
1940process exits, after which they stop automatically.
1941
1942 my $pid = fork;
1943 ...
1944 $term->{pw} = urxvt::pw
1945 ->new
1946 ->start ($pid)
1947 ->cb (sub {
1948 my ($pw, $exit_status) = @_;
1949 ...
1950 });
1951
1952=over 4
1953
1954=item $pw = new urxvt::pw
1955
1956Create a new process watcher in stopped state.
1957
1958=item $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
1959
1960Set the callback to be called when the timer triggers.
1961
1962=item $pw = $timer->start ($pid)
1963
1964Tells the wqtcher to start watching for process C<$pid>.
1965
1966=item $pw = $pw->stop
1967
1968Stop the watcher.
1969
1970=back
1971
1651=head1 ENVIRONMENT 1972=head1 ENVIRONMENT
1652 1973
1653=head2 URXVT_PERL_VERBOSITY 1974=head2 URXVT_PERL_VERBOSITY
1654 1975
1655This variable controls the verbosity level of the perl extension. Higher 1976This variable controls the verbosity level of the perl extension. Higher

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines