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.89 by root, Thu Jan 12 12:10:06 2006 UTC vs.
Revision 1.129 by root, Wed Jan 25 15:11:31 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/
186
187Of course, this can be modified to suit your needs and your editor :)
188
189To expand the example above to typical perl error messages ("XXX at
190FILENAME line YYY."), you need a slightly more elaborate solution:
191
192 URxvt.selection.pattern-0: ( at .*? line \\d+[,.])
193 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/
194
195The first line tells the selection code to treat the unchanging part of
196every error message as a selection pattern, and the second line transforms
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.
131 209
132=item mark-urls 210=item mark-urls
133 211
134Uses 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
135make them clickable. When middle-clicked, the program specified in the 213make them clickable. When middle-clicked, the program specified in the
136resource C<urlLauncher> (default C<x-www-browser>) will be started with 214resource C<urlLauncher> (default C<x-www-browser>) will be started with
137the URL as first argument. 215the URL as first argument.
138 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
139=item block-graphics-to-ascii 237=item block-graphics-to-ascii
140 238
141A 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,
142by replacing all line-drawing characters (U+2500 .. U+259F) by a 240by replacing all line-drawing characters (U+2500 .. U+259F) by a
143similar-looking ascii character. 241similar-looking ascii character.
144 242
145=item digital-clock 243=item digital-clock
146 244
147Displays a digital clock using the built-in overlay. 245Displays a digital clock using the built-in overlay.
246
247=item remote-selection
248
249Somewhat of a misnomer, this extension adds two menu entries to the
250selection popup that allows one ti run external commands to store the
251selection somewhere and fetch it again.
252
253We use it to implement a "distributed selection mechanism", which just
254means that one command uploads the file to a remote server, and another
255reads it.
256
257The commands can be set using the C<URxvt.remote-selection.store> and
258C<URxvt.remote-selection.fetch> resources. The first should read the
259selection to store from STDIN (always in UTF-8), the second should provide
260the selection data on STDOUT (also in UTF-8).
261
262The defaults (which are likely useless to you) use rsh and cat:
263
264 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
265 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
266
267=item selection-pastebin
268
269This is a little rarely useful extension that Uploads the selection as
270textfile to a remote site (or does other things). (The implementation is
271not currently secure for use in a multiuser environment as it writes to
272F</tmp> directly.).
273
274It listens to the C<selection-pastebin:remote-pastebin> keyboard command,
275i.e.
276
277 URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin
278
279Pressing this combination runs a command with C<%> replaced by the name of
280the textfile. This command can be set via a resource:
281
282 URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
283
284And the default is likely not useful to anybody but the few people around
285here :)
286
287The name of the textfile is the hex encoded md5 sum of the selection, so
288the same content should lead to the same filename.
289
290After a successful upload the selection will be replaced by the text given
291in the C<selection-pastebin-url> resource (again, the % is the placeholder
292for the filename):
293
294 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
148 295
149=item example-refresh-hooks 296=item example-refresh-hooks
150 297
151Displays a very simple digital clock in the upper right corner of the 298Displays a very simple digital clock in the upper right corner of the
152window. Illustrates overwriting the refresh callbacks to create your own 299window. Illustrates overwriting the refresh callbacks to create your own
231called whenever the relevant event happens. 378called whenever the relevant event happens.
232 379
233The first argument passed to them is an extension oject as described in 380The first argument passed to them is an extension oject as described in
234the in the C<Extension Objects> section. 381the in the C<Extension Objects> section.
235 382
236B<All> of these hooks must return a boolean value. If it is true, then the 383B<All> of these hooks must return a boolean value. If any of the called
237event counts as being I<consumed>, and the invocation of other hooks is 384hooks returns true, then the event counts as being I<consumed>, and the
238skipped, and the relevant action might not be carried out by the C++ code. 385relevant action might not be carried out by the C++ code.
239 386
240I<< When in doubt, return a false value (preferably C<()>). >> 387I<< When in doubt, return a false value (preferably C<()>). >>
241 388
242=over 4 389=over 4
243 390
244=item on_init $term 391=item on_init $term
245 392
246Called after a new terminal object has been initialized, but before 393Called after a new terminal object has been initialized, but before
247windows are created or the command gets run. Most methods are unsafe to 394windows are created or the command gets run. Most methods are unsafe to
248call or deliver senseless data, as terminal size and other characteristics 395call or deliver senseless data, as terminal size and other characteristics
249have not yet been determined. You can safely query and change resources, 396have not yet been determined. You can safely query and change resources
250though. 397and options, though. For many purposes the C<on_start> hook is a better
398place.
399
400=item on_start $term
401
402Called at the very end of initialisation of a new terminal, just before
403trying to map (display) the toplevel and returning to the mainloop.
404
405=item on_destroy $term
406
407Called whenever something tries to destroy terminal, when the terminal is
408still fully functional (not for long, though).
251 409
252=item on_reset $term 410=item on_reset $term
253 411
254Called after the screen is "reset" for any reason, such as resizing or 412Called after the screen is "reset" for any reason, such as resizing or
255control sequences. Here is where you can react on changes to size-related 413control sequences. Here is where you can react on changes to size-related
256variables. 414variables.
257 415
258=item on_start $term 416=item on_child_start $term, $pid
259 417
260Called at the very end of initialisation of a new terminal, just before 418Called just after the child process has been C<fork>ed.
261returning to the mainloop. 419
420=item on_child_exit $term, $status
421
422Called just after the child process has exited. C<$status> is the status
423from C<waitpid>.
262 424
263=item on_sel_make $term, $eventtime 425=item on_sel_make $term, $eventtime
264 426
265Called whenever a selection has been made by the user, but before the 427Called whenever a selection has been made by the user, but before the
266selection text is copied, so changes to the beginning, end or type of the 428selection text is copied, so changes to the beginning, end or type of the
359 521
360Called whenever the user presses a key combination that has a 522Called whenever the user presses a key combination that has a
361C<perl:string> action bound to it (see description of the B<keysym> 523C<perl:string> action bound to it (see description of the B<keysym>
362resource in the @@RXVT_NAME@@(1) manpage). 524resource in the @@RXVT_NAME@@(1) manpage).
363 525
526=item on_x_event $term, $event
527
528Called on every X event received on the vt window (and possibly other
529windows). Should only be used as a last resort. Most event structure
530members are not passed.
531
364=item on_focus_in $term 532=item on_focus_in $term
365 533
366Called whenever the window gets the keyboard focus, before rxvt-unicode 534Called whenever the window gets the keyboard focus, before rxvt-unicode
367does focus in processing. 535does focus in processing.
368 536
369=item on_focus_out $term 537=item on_focus_out $term
370 538
371Called wheneever the window loses keyboard focus, before rxvt-unicode does 539Called wheneever the window loses keyboard focus, before rxvt-unicode does
372focus out processing. 540focus out processing.
373 541
542=item on_configure_notify $term, $event
543
544=item on_property_notify $term, $event
545
374=item on_key_press $term, $event, $keysym, $octets 546=item on_key_press $term, $event, $keysym, $octets
375 547
376=item on_key_release $term, $event, $keysym 548=item on_key_release $term, $event, $keysym
377 549
378=item on_button_press $term, $event 550=item on_button_press $term, $event
387 559
388Called whenever the corresponding X event is received for the terminal If 560Called whenever the corresponding X event is received for the terminal If
389the hook returns true, then the even will be ignored by rxvt-unicode. 561the hook returns true, then the even will be ignored by rxvt-unicode.
390 562
391The event is a hash with most values as named by Xlib (see the XEvent 563The event is a hash with most values as named by Xlib (see the XEvent
392manpage), with the additional members C<row> and C<col>, which are the row 564manpage), with the additional members C<row> and C<col>, which are the
393and column under the mouse cursor. 565(real, not screen-based) row and column under the mouse cursor.
394 566
395C<on_key_press> additionally receives the string rxvt-unicode would 567C<on_key_press> additionally receives the string rxvt-unicode would
396output, if any, in locale-specific encoding. 568output, if any, in locale-specific encoding.
397 569
398subwindow. 570subwindow.
571
572=item on_client_message $term, $event
573
574=item on_wm_protocols $term, $event
575
576=item on_wm_delete_window $term, $event
577
578Called when various types of ClientMessage events are received (all with
579format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
399 580
400=back 581=back
401 582
402=cut 583=cut
403 584
409use Scalar::Util (); 590use Scalar::Util ();
410use List::Util (); 591use List::Util ();
411 592
412our $VERSION = 1; 593our $VERSION = 1;
413our $TERM; 594our $TERM;
595our @TERM_INIT;
596our @TERM_EXT;
414our @HOOKNAME; 597our @HOOKNAME;
415our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME; 598our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
416our %OPTION; 599our %OPTION;
417 600
418our $LIBDIR; 601our $LIBDIR;
419our $RESNAME; 602our $RESNAME;
420our $RESCLASS; 603our $RESCLASS;
421our $RXVTNAME; 604our $RXVTNAME;
422 605
606our $NOCHAR = chr 0xffff;
607
423=head2 Variables in the C<urxvt> Package 608=head2 Variables in the C<urxvt> Package
424 609
425=over 4 610=over 4
426 611
427=item $urxvt::LIBDIR 612=item $urxvt::LIBDIR
439 624
440=item $urxvt::TERM 625=item $urxvt::TERM
441 626
442The current terminal. This variable stores the current C<urxvt::term> 627The current terminal. This variable stores the current C<urxvt::term>
443object, whenever a callback/hook is executing. 628object, whenever a callback/hook is executing.
629
630=item @urxvt::TERM_INIT
631
632All coderefs in this array will be called as methods of the next newly
633created C<urxvt::term> object (during the C<on_init> phase). The array
634gets cleared before the codereferences that were in it are being executed,
635so coderefs can push themselves onto it again if they so desire.
636
637This complements to the perl-eval commandline option, but gets executed
638first.
639
640=item @urxvt::TERM_EXT
641
642Works similar to C<@TERM_INIT>, but contains perl package/class names, which
643get registered as normal extensions after calling the hooks in C<@TERM_INIT>
644but before other extensions. Gets cleared just like C<@TERM_INIT>.
444 645
445=back 646=back
446 647
447=head2 Functions in the C<urxvt> Package 648=head2 Functions in the C<urxvt> Package
448 649
463Using this function has the advantage that its output ends up in the 664Using this function has the advantage that its output ends up in the
464correct place, e.g. on stderr of the connecting urxvtc client. 665correct place, e.g. on stderr of the connecting urxvtc client.
465 666
466Messages have a size limit of 1023 bytes currently. 667Messages have a size limit of 1023 bytes currently.
467 668
468=item $is_safe = urxvt::safe
469
470Returns true when it is safe to do potentially unsafe things, such as
471evaluating perl code specified by the user. This is true when urxvt was
472started setuid or setgid.
473
474=item $time = urxvt::NOW 669=item $time = urxvt::NOW
475 670
476Returns the "current time" (as per the event loop). 671Returns the "current time" (as per the event loop).
477 672
478=item urxvt::CurrentTime 673=item urxvt::CurrentTime
479 674
480=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, 675=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
481Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, 676Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
482Button4Mask, Button5Mask, AnyModifier 677Button4Mask, Button5Mask, AnyModifier
678
679=item urxvt::NoEventMask, KeyPressMask, KeyReleaseMask,
680ButtonPressMask, ButtonReleaseMask, EnterWindowMask, LeaveWindowMask,
681PointerMotionMask, PointerMotionHintMask, Button1MotionMask, Button2MotionMask,
682Button3MotionMask, Button4MotionMask, Button5MotionMask, ButtonMotionMask,
683KeymapStateMask, ExposureMask, VisibilityChangeMask, StructureNotifyMask,
684ResizeRedirectMask, SubstructureNotifyMask, SubstructureRedirectMask,
685FocusChangeMask, PropertyChangeMask, ColormapChangeMask, OwnerGrabButtonMask
686
687=item urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify,
688EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose,
689GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify, DestroyNotify,
690UnmapNotify, MapNotify, MapRequest, ReparentNotify, ConfigureNotify,
691ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify,
692CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest,
693SelectionNotify, ColormapNotify, ClientMessage, MappingNotify
483 694
484Various constants for use in X calls and event processing. 695Various constants for use in X calls and event processing.
485 696
486=back 697=back
487 698
538=back 749=back
539 750
540=cut 751=cut
541 752
542BEGIN { 753BEGIN {
543 urxvt->bootstrap;
544
545 # overwrite perl's warn 754 # overwrite perl's warn
546 *CORE::GLOBAL::warn = sub { 755 *CORE::GLOBAL::warn = sub {
547 my $msg = join "", @_; 756 my $msg = join "", @_;
548 $msg .= "\n" 757 $msg .= "\n"
549 unless $msg =~ /\n$/; 758 unless $msg =~ /\n$/;
550 urxvt::warn ($msg); 759 urxvt::warn ($msg);
551 }; 760 };
552
553 # %ENV is the original startup environment
554 delete $ENV{IFS};
555 delete $ENV{CDPATH};
556 delete $ENV{BASH_ENV};
557 $ENV{PATH} = "/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/opt/bin:/opt/sbin";
558} 761}
559 762
560my @hook_count; 763no warnings 'utf8';
764
561my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 765my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
562 766
563sub verbose { 767sub verbose {
564 my ($level, $msg) = @_; 768 my ($level, $msg) = @_;
565 warn "$msg\n" if $level <= $verbosity; 769 warn "$msg\n" if $level <= $verbosity;
566} 770}
567 771
568my $extension_pkg = "extension0000";
569my %extension_pkg; 772my %extension_pkg;
570 773
571# load a single script into its own package, once only 774# load a single script into its own package, once only
572sub extension_package($) { 775sub extension_package($) {
573 my ($path) = @_; 776 my ($path) = @_;
574 777
575 $extension_pkg{$path} ||= do { 778 $extension_pkg{$path} ||= do {
576 my $pkg = "urxvt::" . ($extension_pkg++); 779 $path =~ /([^\/\\]+)$/;
780 my $pkg = $1;
781 $pkg =~ s/[^[:word:]]/_/g;
782 $pkg = "urxvt::ext::$pkg";
577 783
578 verbose 3, "loading extension '$path' into package '$pkg'"; 784 verbose 3, "loading extension '$path' into package '$pkg'";
579 785
580 open my $fh, "<:raw", $path 786 open my $fh, "<:raw", $path
581 or die "$path: $!"; 787 or die "$path: $!";
582 788
583 my $source = untaint 789 my $source =
584 "package $pkg; use strict; use utf8;\n" 790 "package $pkg; use strict; use utf8; no warnings 'utf8';\n"
585 . "use base urxvt::term::extension::;\n"
586 . "#line 1 \"$path\"\n{\n" 791 . "#line 1 \"$path\"\n{\n"
587 . (do { local $/; <$fh> }) 792 . (do { local $/; <$fh> })
588 . "\n};\n1"; 793 . "\n};\n1";
589 794
590 eval $source 795 eval $source
604 if ($htype == 0) { # INIT 809 if ($htype == 0) { # INIT
605 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 810 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
606 811
607 my %ext_arg; 812 my %ext_arg;
608 813
814 {
815 my @init = @TERM_INIT;
816 @TERM_INIT = ();
817 $_->($TERM) for @init;
818 my @pkg = @TERM_EXT;
819 @TERM_EXT = ();
820 $TERM->register_package ($_) for @pkg;
821 }
822
609 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) { 823 for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
610 if ($_ eq "default") { 824 if ($_ eq "default") {
611 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback); 825 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback readline);
612 } elsif (/^-(.*)$/) { 826 } elsif (/^-(.*)$/) {
613 delete $ext_arg{$1}; 827 delete $ext_arg{$1};
614 } elsif (/^([^<]+)<(.*)>$/) { 828 } elsif (/^([^<]+)<(.*)>$/) {
615 push @{ $ext_arg{$1} }, $2; 829 push @{ $ext_arg{$1} }, $2;
616 } else { 830 } else {
639 if $verbosity >= 10; 853 if $verbosity >= 10;
640 854
641 keys %$cb; 855 keys %$cb;
642 856
643 while (my ($pkg, $cb) = each %$cb) { 857 while (my ($pkg, $cb) = each %$cb) {
644 $retval = eval { $cb->($TERM->{_pkg}{$pkg}, @_) } 858 my $retval_ = eval { $cb->($TERM->{_pkg}{$pkg}, @_) };
645 and last; 859 $retval ||= $retval_;
646 860
647 if ($@) { 861 if ($@) {
648 $TERM->ungrab; # better to lose the grab than the session 862 $TERM->ungrab; # better to lose the grab than the session
649 warn $@; 863 warn $@;
650 } 864 }
653 verbose 11, "$HOOKNAME[$htype] returning <$retval>" 867 verbose 11, "$HOOKNAME[$htype] returning <$retval>"
654 if $verbosity >= 11; 868 if $verbosity >= 11;
655 } 869 }
656 870
657 if ($htype == 1) { # DESTROY 871 if ($htype == 1) { # DESTROY
658 if (my $hook = delete $TERM->{_hook}) {
659 for my $htype (0..$#$hook) {
660 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
661 or set_should_invoke $htype, 0;
662 }
663 }
664
665 # clear package objects 872 # clear package objects
666 %$_ = () for values %{ $TERM->{_pkg} }; 873 %$_ = () for values %{ $TERM->{_pkg} };
667 874
668 # clear package 875 # clear package
669 %$TERM = (); 876 %$TERM = ();
670 } 877 }
671 878
672 $retval 879 $retval
673}
674
675sub exec_async(@) {
676 my $pid = fork;
677
678 return
679 if !defined $pid or $pid;
680
681 %ENV = %{ $TERM->env };
682
683 exec @_;
684 _exit 255;
685} 880}
686 881
687# urxvt::term::extension 882# urxvt::term::extension
688 883
689package urxvt::term::extension; 884package urxvt::term::extension;
695 while (my ($name, $cb) = each %hook) { 890 while (my ($name, $cb) = each %hook) {
696 my $htype = $HOOKTYPE{uc $name}; 891 my $htype = $HOOKTYPE{uc $name};
697 defined $htype 892 defined $htype
698 or Carp::croak "unsupported hook type '$name'"; 893 or Carp::croak "unsupported hook type '$name'";
699 894
895 $self->set_should_invoke ($htype, +1)
700 unless (exists $self->{term}{_hook}[$htype]{$pkg}) { 896 unless exists $self->{term}{_hook}[$htype]{$pkg};
701 $hook_count[$htype]++
702 or urxvt::set_should_invoke $htype, 1;
703 }
704 897
705 $self->{term}{_hook}[$htype]{$pkg} = $cb; 898 $self->{term}{_hook}[$htype]{$pkg} = $cb;
706 } 899 }
707} 900}
708 901
713 for my $name (@hook) { 906 for my $name (@hook) {
714 my $htype = $HOOKTYPE{uc $name}; 907 my $htype = $HOOKTYPE{uc $name};
715 defined $htype 908 defined $htype
716 or Carp::croak "unsupported hook type '$name'"; 909 or Carp::croak "unsupported hook type '$name'";
717 910
911 $self->set_should_invoke ($htype, -1)
718 if (delete $self->{term}{_hook}[$htype]{$pkg}) { 912 if delete $self->{term}{_hook}[$htype]{$pkg};
719 --$hook_count[$htype]
720 or urxvt::set_should_invoke $htype, 0;
721 }
722 } 913 }
723} 914}
724 915
725our $AUTOLOAD; 916our $AUTOLOAD;
726 917
832# find on_xxx subs in the package and register them 1023# find on_xxx subs in the package and register them
833# as hooks 1024# as hooks
834sub register_package { 1025sub register_package {
835 my ($self, $pkg, $argv) = @_; 1026 my ($self, $pkg, $argv) = @_;
836 1027
1028 no strict 'refs';
1029
1030 urxvt::verbose 6, "register package $pkg to $self";
1031
1032 @{"$pkg\::ISA"} = urxvt::term::extension::;
1033
837 my $proxy = bless { 1034 my $proxy = bless {
838 _pkg => $pkg, 1035 _pkg => $pkg,
839 argv => $argv, 1036 argv => $argv,
840 }, $pkg; 1037 }, $pkg;
841 Scalar::Util::weaken ($proxy->{term} = $self); 1038 Scalar::Util::weaken ($proxy->{term} = $self);
872 1069
873Destroy the terminal object (close the window, free resources 1070Destroy the terminal object (close the window, free resources
874etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event 1071etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event
875watchers (timers, io watchers) are still active. 1072watchers (timers, io watchers) are still active.
876 1073
1074=item $term->exec_async ($cmd[, @args])
1075
1076Works like the combination of the C<fork>/C<exec> builtins, which executes
1077("starts") programs in the background. This function takes care of setting
1078the user environment before exec'ing the command (e.g. C<PATH>) and should
1079be preferred over explicit calls to C<exec> or C<system>.
1080
1081Returns the pid of the subprocess or C<undef> on error.
1082
1083=cut
1084
1085sub exec_async {
1086 my $self = shift;
1087
1088 my $pid = fork;
1089
1090 return $pid
1091 if !defined $pid or $pid;
1092
1093 %ENV = %{ $self->env };
1094
1095 exec @_;
1096 urxvt::_exit 255;
1097}
1098
877=item $isset = $term->option ($optval[, $set]) 1099=item $isset = $term->option ($optval[, $set])
878 1100
879Returns true if the option specified by C<$optval> is enabled, and 1101Returns true if the option specified by C<$optval> is enabled, and
880optionally change it. All option values are stored by name in the hash 1102optionally change it. All option values are stored by name in the hash
881C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash. 1103C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
883Here is a a likely non-exhaustive list of option names, please see the 1105Here is a a likely non-exhaustive list of option names, please see the
884source file F</src/optinc.h> to see the actual list: 1106source file F</src/optinc.h> to see the actual list:
885 1107
886 borderLess console cursorBlink cursorUnderline hold iconic insecure 1108 borderLess console cursorBlink cursorUnderline hold iconic insecure
887 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 1109 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
888 pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating 1110 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
889 scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer 1111 scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput
890 secondaryScreen secondaryScroll skipBuiltinGlyphs transparent 1112 scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs
891 tripleclickwords utmpInhibit visualBell 1113 transparent tripleclickwords utmpInhibit visualBell
892 1114
893=item $value = $term->resource ($name[, $newval]) 1115=item $value = $term->resource ($name[, $newval])
894 1116
895Returns the current resource value associated with a given name and 1117Returns the current resource value associated with a given name and
896optionally sets a new value. Setting values is most useful in the C<init> 1118optionally sets a new value. Setting values is most useful in the C<init>
913 1135
914 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1136 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
915 borderLess color cursorBlink cursorUnderline cutchars delete_key 1137 borderLess color cursorBlink cursorUnderline cutchars delete_key
916 display_name embed ext_bwidth fade font geometry hold iconName 1138 display_name embed ext_bwidth fade font geometry hold iconName
917 imFont imLocale inputMethod insecure int_bwidth intensityStyles 1139 imFont imLocale inputMethod insecure int_bwidth intensityStyles
918 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier 1140 italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier
919 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2 1141 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
920 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 1142 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
921 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 1143 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
922 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 1144 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
923 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 1145 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
924 shade term_name title transparent transparent_all tripleclickwords 1146 secondaryScreen secondaryScroll selectstyle shade term_name title
925 utmpInhibit visualBell 1147 transient_for transparent transparent_all tripleclickwords utmpInhibit
1148 visualBell
926 1149
927=cut 1150=cut
928 1151
929sub resource($$;$) { 1152sub resource($$;$) {
930 my ($self, $name) = (shift, shift); 1153 my ($self, $name) = (shift, shift);
1104 1327
1105Normally its not a good idea to use this function, as programs might be 1328Normally its not a good idea to use this function, as programs might be
1106confused by changes in cursor position or scrolling. Its useful inside a 1329confused by changes in cursor position or scrolling. Its useful inside a
1107C<on_add_lines> hook, though. 1330C<on_add_lines> hook, though.
1108 1331
1332=item $term->scr_change_screen ($screen)
1333
1334Switch to given screen - 0 primary, 1 secondary.
1335
1109=item $term->cmd_parse ($octets) 1336=item $term->cmd_parse ($octets)
1110 1337
1111Similar to C<scr_add_lines>, but the argument must be in the 1338Similar to C<scr_add_lines>, but the argument must be in the
1112locale-specific encoding of the terminal and can contain command sequences 1339locale-specific encoding of the terminal and can contain command sequences
1113(escape codes) that will be interpreted. 1340(escape codes) that will be interpreted.
1123Replaces the event mask of the pty watcher by the given event mask. Can 1350Replaces the event mask of the pty watcher by the given event mask. Can
1124be used to suppress input and output handling to the pty/tty. See the 1351be used to suppress input and output handling to the pty/tty. See the
1125description of C<< urxvt::timer->events >>. Make sure to always restore 1352description of C<< urxvt::timer->events >>. Make sure to always restore
1126the previous value. 1353the previous value.
1127 1354
1355=item $fd = $term->pty_fd
1356
1357Returns the master file descriptor for the pty in use, or C<-1> if no pty
1358is used.
1359
1128=item $windowid = $term->parent 1360=item $windowid = $term->parent
1129 1361
1130Return the window id of the toplevel window. 1362Return the window id of the toplevel window.
1131 1363
1132=item $windowid = $term->vt 1364=item $windowid = $term->vt
1133 1365
1134Return the window id of the terminal window. 1366Return the window id of the terminal window.
1135 1367
1368=item $term->vt_emask_add ($x_event_mask)
1369
1370Adds the specified events to the vt event mask. Useful e.g. when you want
1371to receive pointer events all the times:
1372
1373 $term->vt_emask_add (urxvt::PointerMotionMask);
1374
1136=item $window_width = $term->width 1375=item $window_width = $term->width
1137 1376
1138=item $window_height = $term->height 1377=item $window_height = $term->height
1139 1378
1140=item $font_width = $term->fwidth 1379=item $font_width = $term->fwidth
1153 1392
1154=item $max_scrollback = $term->saveLines 1393=item $max_scrollback = $term->saveLines
1155 1394
1156=item $nrow_plus_saveLines = $term->total_rows 1395=item $nrow_plus_saveLines = $term->total_rows
1157 1396
1158=item $lines_in_scrollback = $term->nsaved 1397=item $topmost_scrollback_row = $term->top_row
1159 1398
1160Return various integers describing terminal characteristics. 1399Return various integers describing terminal characteristics.
1161 1400
1162=item $x_display = $term->display_id 1401=item $x_display = $term->display_id
1163 1402
1189=item $modifiermask = $term->ModNumLockMask 1428=item $modifiermask = $term->ModNumLockMask
1190 1429
1191Return the modifier masks corresponding to the "ISO Level 3 Shift" (often 1430Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
1192AltGr), the meta key (often Alt) and the num lock key, if applicable. 1431AltGr), the meta key (often Alt) and the num lock key, if applicable.
1193 1432
1433=item $screen = $term->current_screen
1434
1435Returns the currently displayed screen (0 primary, 1 secondary).
1436
1437=item $cursor_is_hidden = $term->hidden_cursor
1438
1439Returns wether the cursor is currently hidden or not.
1440
1194=item $view_start = $term->view_start ([$newvalue]) 1441=item $view_start = $term->view_start ([$newvalue])
1195 1442
1196Returns the negative row number of the topmost line. Minimum value is 1443Returns the row number of the topmost displayed line. Maximum value is
1197C<0>, which displays the normal terminal contents. Larger values scroll 1444C<0>, which displays the normal terminal contents. Lower values scroll
1198this many lines into the scrollback buffer. 1445this many lines into the scrollback buffer.
1199 1446
1200=item $term->want_refresh 1447=item $term->want_refresh
1201 1448
1202Requests a screen refresh. At the next opportunity, rxvt-unicode will 1449Requests a screen refresh. At the next opportunity, rxvt-unicode will
1217line, starting at column C<$start_col> (default C<0>), which is useful 1464line, starting at column C<$start_col> (default C<0>), which is useful
1218to replace only parts of a line. The font index in the rendition will 1465to replace only parts of a line. The font index in the rendition will
1219automatically be updated. 1466automatically be updated.
1220 1467
1221C<$text> is in a special encoding: tabs and wide characters that use more 1468C<$text> is in a special encoding: tabs and wide characters that use more
1222than one cell when displayed are padded with urxvt::NOCHAR characters 1469than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535)
1223(C<chr 65535>). Characters with combining characters and other characters 1470characters. Characters with combining characters and other characters that
1224that do not fit into the normal tetx encoding will be replaced with 1471do not fit into the normal tetx encoding will be replaced with characters
1225characters in the private use area. 1472in the private use area.
1226 1473
1227You have to obey this encoding when changing text. The advantage is 1474You have to obey this encoding when changing text. The advantage is
1228that C<substr> and similar functions work on screen cells and not on 1475that C<substr> and similar functions work on screen cells and not on
1229characters. 1476characters.
1230 1477
1405 1652
1406Calls XUngrab for the most recent grab. Is called automatically on 1653Calls XUngrab for the most recent grab. Is called automatically on
1407evaluation errors, as it is better to lose the grab in the error case as 1654evaluation errors, as it is better to lose the grab in the error case as
1408the session. 1655the session.
1409 1656
1657=item $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
1658
1659=item $atom_name = $term->XGetAtomName ($atom)
1660
1661=item @atoms = $term->XListProperties ($window)
1662
1663=item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
1664
1665=item $term->XChangeWindowProperty ($window, $property, $type, $format, $octets)
1666
1667=item $term->XDeleteProperty ($window, $property)
1668
1669=item $window = $term->DefaultRootWindow
1670
1671=item $term->XReparentWindow ($window, $parent, [$x, $y])
1672
1673=item $term->XMapWindow ($window)
1674
1675=item $term->XUnmapWindow ($window)
1676
1677=item $term->XMoveResizeWindow ($window, $x, $y, $width, $height)
1678
1679=item ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x, $y)
1680
1681=item $term->XChangeInput ($window, $add_events[, $del_events])
1682
1683Various X or X-related functions. The C<$term> object only serves as
1684the source of the display, otherwise those functions map more-or-less
1685directory onto the X functions of the same name.
1686
1410=back 1687=back
1411 1688
1412=cut 1689=cut
1413 1690
1414package urxvt::popup; 1691package urxvt::popup;
1515 my $env = $self->{term}->env; 1792 my $env = $self->{term}->env;
1516 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE. 1793 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
1517 delete $env->{LC_ALL}; 1794 delete $env->{LC_ALL};
1518 $env->{LC_CTYPE} = $self->{term}->locale; 1795 $env->{LC_CTYPE} = $self->{term}->locale;
1519 1796
1520 urxvt::term->new ($env, $self->{term}->resource ("name"), 1797 urxvt::term->new ($env, "popup",
1521 "--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0, 1798 "--perl-lib" => "", "--perl-ext-common" => "",
1799 "-pty-fd" => -1, "-sl" => 0,
1800 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect",
1522 "--transient-for" => $self->{term}->parent, 1801 "--transient-for" => $self->{term}->parent,
1523 "-display" => $self->{term}->display_id, 1802 "-display" => $self->{term}->display_id,
1524 "-pe" => "urxvt-popup") 1803 "-pe" => "urxvt-popup")
1525 or die "unable to create popup window\n"; 1804 or die "unable to create popup window\n";
1526} 1805}
1531 delete $self->{term}{_destroy}{$self}; 1810 delete $self->{term}{_destroy}{$self};
1532 $self->{term}->ungrab; 1811 $self->{term}->ungrab;
1533} 1812}
1534 1813
1535=back 1814=back
1815
1816=cut
1817
1818package urxvt::watcher;
1819
1820@urxvt::timer::ISA = __PACKAGE__;
1821@urxvt::iow::ISA = __PACKAGE__;
1822@urxvt::pw::ISA = __PACKAGE__;
1823@urxvt::iw::ISA = __PACKAGE__;
1536 1824
1537=head2 The C<urxvt::timer> Class 1825=head2 The C<urxvt::timer> Class
1538 1826
1539This class implements timer watchers/events. Time is represented as a 1827This class implements timer watchers/events. Time is represented as a
1540fractional number of seconds since the epoch. Example: 1828fractional number of seconds since the epoch. Example:
1578Start the timer. 1866Start the timer.
1579 1867
1580=item $timer = $timer->start ($tstamp) 1868=item $timer = $timer->start ($tstamp)
1581 1869
1582Set the event trigger time to C<$tstamp> and start the timer. 1870Set the event trigger time to C<$tstamp> and start the timer.
1871
1872=item $timer = $timer->after ($delay)
1873
1874Like C<start>, but sets the expiry timer to c<urxvt::NOW + $delay>.
1583 1875
1584=item $timer = $timer->stop 1876=item $timer = $timer->stop
1585 1877
1586Stop the timer. 1878Stop the timer.
1587 1879
1634 1926
1635Stop watching for events on the given filehandle. 1927Stop watching for events on the given filehandle.
1636 1928
1637=back 1929=back
1638 1930
1931=head2 The C<urxvt::iw> Class
1932
1933This class implements idle watchers, that get called automatically when
1934the process is idle. They should return as fast as possible, after doing
1935some useful work.
1936
1937=over 4
1938
1939=item $iw = new urxvt::iw
1940
1941Create a new idle watcher object in stopped state.
1942
1943=item $iw = $iw->cb (sub { my ($iw) = @_; ... })
1944
1945Set the callback to be called when the watcher triggers.
1946
1947=item $timer = $timer->start
1948
1949Start the watcher.
1950
1951=item $timer = $timer->stop
1952
1953Stop the watcher.
1954
1955=back
1956
1957=head2 The C<urxvt::pw> Class
1958
1959This class implements process watchers. They create an event whenever a
1960process exits, after which they stop automatically.
1961
1962 my $pid = fork;
1963 ...
1964 $term->{pw} = urxvt::pw
1965 ->new
1966 ->start ($pid)
1967 ->cb (sub {
1968 my ($pw, $exit_status) = @_;
1969 ...
1970 });
1971
1972=over 4
1973
1974=item $pw = new urxvt::pw
1975
1976Create a new process watcher in stopped state.
1977
1978=item $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
1979
1980Set the callback to be called when the timer triggers.
1981
1982=item $pw = $timer->start ($pid)
1983
1984Tells the wqtcher to start watching for process C<$pid>.
1985
1986=item $pw = $pw->stop
1987
1988Stop the watcher.
1989
1990=back
1991
1639=head1 ENVIRONMENT 1992=head1 ENVIRONMENT
1640 1993
1641=head2 URXVT_PERL_VERBOSITY 1994=head2 URXVT_PERL_VERBOSITY
1642 1995
1643This variable controls the verbosity level of the perl extension. Higher 1996This variable controls the verbosity level of the perl extension. Higher

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines