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.90 by root, Thu Jan 12 12:15:10 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/
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 :)
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.
133 209
134=item mark-urls 210=item mark-urls
135 211
136Uses 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
137make them clickable. When middle-clicked, the program specified in the 213make them clickable. When middle-clicked, the program specified in the
138resource C<urlLauncher> (default C<x-www-browser>) will be started with 214resource C<urlLauncher> (default C<x-www-browser>) will be started with
139the URL as first argument. 215the URL as first argument.
140 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
141=item block-graphics-to-ascii 237=item block-graphics-to-ascii
142 238
143A 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,
144by replacing all line-drawing characters (U+2500 .. U+259F) by a 240by replacing all line-drawing characters (U+2500 .. U+259F) by a
145similar-looking ascii character. 241similar-looking ascii character.
146 242
147=item digital-clock 243=item digital-clock
148 244
149Displays 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/%
150 295
151=item example-refresh-hooks 296=item example-refresh-hooks
152 297
153Displays 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
154window. Illustrates overwriting the refresh callbacks to create your own 299window. Illustrates overwriting the refresh callbacks to create your own
233called whenever the relevant event happens. 378called whenever the relevant event happens.
234 379
235The 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
236the in the C<Extension Objects> section. 381the in the C<Extension Objects> section.
237 382
238B<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
239event 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
240skipped, and the relevant action might not be carried out by the C++ code. 385relevant action might not be carried out by the C++ code.
241 386
242I<< When in doubt, return a false value (preferably C<()>). >> 387I<< When in doubt, return a false value (preferably C<()>). >>
243 388
244=over 4 389=over 4
245 390
246=item on_init $term 391=item on_init $term
247 392
248Called after a new terminal object has been initialized, but before 393Called after a new terminal object has been initialized, but before
249windows 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
250call or deliver senseless data, as terminal size and other characteristics 395call or deliver senseless data, as terminal size and other characteristics
251have not yet been determined. You can safely query and change resources, 396have not yet been determined. You can safely query and change resources
252though. 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).
253 409
254=item on_reset $term 410=item on_reset $term
255 411
256Called 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
257control 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
258variables. 414variables.
259 415
260=item on_start $term 416=item on_child_start $term, $pid
261 417
262Called at the very end of initialisation of a new terminal, just before 418Called just after the child process has been C<fork>ed.
263returning 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>.
264 424
265=item on_sel_make $term, $eventtime 425=item on_sel_make $term, $eventtime
266 426
267Called 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
268selection 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
361 521
362Called whenever the user presses a key combination that has a 522Called whenever the user presses a key combination that has a
363C<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>
364resource in the @@RXVT_NAME@@(1) manpage). 524resource in the @@RXVT_NAME@@(1) manpage).
365 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
366=item on_focus_in $term 532=item on_focus_in $term
367 533
368Called whenever the window gets the keyboard focus, before rxvt-unicode 534Called whenever the window gets the keyboard focus, before rxvt-unicode
369does focus in processing. 535does focus in processing.
370 536
371=item on_focus_out $term 537=item on_focus_out $term
372 538
373Called wheneever the window loses keyboard focus, before rxvt-unicode does 539Called wheneever the window loses keyboard focus, before rxvt-unicode does
374focus out processing. 540focus out processing.
375 541
542=item on_configure_notify $term, $event
543
544=item on_property_notify $term, $event
545
376=item on_key_press $term, $event, $keysym, $octets 546=item on_key_press $term, $event, $keysym, $octets
377 547
378=item on_key_release $term, $event, $keysym 548=item on_key_release $term, $event, $keysym
379 549
380=item on_button_press $term, $event 550=item on_button_press $term, $event
389 559
390Called whenever the corresponding X event is received for the terminal If 560Called whenever the corresponding X event is received for the terminal If
391the 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.
392 562
393The 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
394manpage), 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
395and column under the mouse cursor. 565(real, not screen-based) row and column under the mouse cursor.
396 566
397C<on_key_press> additionally receives the string rxvt-unicode would 567C<on_key_press> additionally receives the string rxvt-unicode would
398output, if any, in locale-specific encoding. 568output, if any, in locale-specific encoding.
399 569
400subwindow. 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).
401 580
402=back 581=back
403 582
404=cut 583=cut
405 584
411use Scalar::Util (); 590use Scalar::Util ();
412use List::Util (); 591use List::Util ();
413 592
414our $VERSION = 1; 593our $VERSION = 1;
415our $TERM; 594our $TERM;
595our @TERM_INIT;
596our @TERM_EXT;
416our @HOOKNAME; 597our @HOOKNAME;
417our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME; 598our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
418our %OPTION; 599our %OPTION;
419 600
420our $LIBDIR; 601our $LIBDIR;
421our $RESNAME; 602our $RESNAME;
422our $RESCLASS; 603our $RESCLASS;
423our $RXVTNAME; 604our $RXVTNAME;
424 605
606our $NOCHAR = chr 0xffff;
607
425=head2 Variables in the C<urxvt> Package 608=head2 Variables in the C<urxvt> Package
426 609
427=over 4 610=over 4
428 611
429=item $urxvt::LIBDIR 612=item $urxvt::LIBDIR
441 624
442=item $urxvt::TERM 625=item $urxvt::TERM
443 626
444The current terminal. This variable stores the current C<urxvt::term> 627The current terminal. This variable stores the current C<urxvt::term>
445object, 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>.
446 645
447=back 646=back
448 647
449=head2 Functions in the C<urxvt> Package 648=head2 Functions in the C<urxvt> Package
450 649
465Using 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
466correct place, e.g. on stderr of the connecting urxvtc client. 665correct place, e.g. on stderr of the connecting urxvtc client.
467 666
468Messages have a size limit of 1023 bytes currently. 667Messages have a size limit of 1023 bytes currently.
469 668
470=item $is_safe = urxvt::safe
471
472Returns true when it is safe to do potentially unsafe things, such as
473evaluating perl code specified by the user. This is true when urxvt was
474started setuid or setgid.
475
476=item $time = urxvt::NOW 669=item $time = urxvt::NOW
477 670
478Returns the "current time" (as per the event loop). 671Returns the "current time" (as per the event loop).
479 672
480=item urxvt::CurrentTime 673=item urxvt::CurrentTime
481 674
482=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, 675=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
483Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, 676Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
484Button4Mask, 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
485 694
486Various constants for use in X calls and event processing. 695Various constants for use in X calls and event processing.
487 696
488=back 697=back
489 698
540=back 749=back
541 750
542=cut 751=cut
543 752
544BEGIN { 753BEGIN {
545 urxvt->bootstrap;
546
547 # overwrite perl's warn 754 # overwrite perl's warn
548 *CORE::GLOBAL::warn = sub { 755 *CORE::GLOBAL::warn = sub {
549 my $msg = join "", @_; 756 my $msg = join "", @_;
550 $msg .= "\n" 757 $msg .= "\n"
551 unless $msg =~ /\n$/; 758 unless $msg =~ /\n$/;
552 urxvt::warn ($msg); 759 urxvt::warn ($msg);
553 }; 760 };
554
555 # %ENV is the original startup environment
556 delete $ENV{IFS};
557 delete $ENV{CDPATH};
558 delete $ENV{BASH_ENV};
559 $ENV{PATH} = "/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/opt/bin:/opt/sbin";
560} 761}
561 762
562my @hook_count; 763no warnings 'utf8';
764
563my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 765my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
564 766
565sub verbose { 767sub verbose {
566 my ($level, $msg) = @_; 768 my ($level, $msg) = @_;
567 warn "$msg\n" if $level <= $verbosity; 769 warn "$msg\n" if $level <= $verbosity;
568} 770}
569 771
570my $extension_pkg = "extension0000";
571my %extension_pkg; 772my %extension_pkg;
572 773
573# load a single script into its own package, once only 774# load a single script into its own package, once only
574sub extension_package($) { 775sub extension_package($) {
575 my ($path) = @_; 776 my ($path) = @_;
576 777
577 $extension_pkg{$path} ||= do { 778 $extension_pkg{$path} ||= do {
578 my $pkg = "urxvt::" . ($extension_pkg++); 779 $path =~ /([^\/\\]+)$/;
780 my $pkg = $1;
781 $pkg =~ s/[^[:word:]]/_/g;
782 $pkg = "urxvt::ext::$pkg";
579 783
580 verbose 3, "loading extension '$path' into package '$pkg'"; 784 verbose 3, "loading extension '$path' into package '$pkg'";
581 785
582 open my $fh, "<:raw", $path 786 open my $fh, "<:raw", $path
583 or die "$path: $!"; 787 or die "$path: $!";
584 788
585 my $source = untaint 789 my $source =
586 "package $pkg; use strict; use utf8;\n" 790 "package $pkg; use strict; use utf8; no warnings 'utf8';\n"
587 . "use base urxvt::term::extension::;\n"
588 . "#line 1 \"$path\"\n{\n" 791 . "#line 1 \"$path\"\n{\n"
589 . (do { local $/; <$fh> }) 792 . (do { local $/; <$fh> })
590 . "\n};\n1"; 793 . "\n};\n1";
591 794
592 eval $source 795 eval $source
606 if ($htype == 0) { # INIT 809 if ($htype == 0) { # INIT
607 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 810 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
608 811
609 my %ext_arg; 812 my %ext_arg;
610 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
611 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) { 823 for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
612 if ($_ eq "default") { 824 if ($_ eq "default") {
613 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback); 825 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback readline);
614 } elsif (/^-(.*)$/) { 826 } elsif (/^-(.*)$/) {
615 delete $ext_arg{$1}; 827 delete $ext_arg{$1};
616 } elsif (/^([^<]+)<(.*)>$/) { 828 } elsif (/^([^<]+)<(.*)>$/) {
617 push @{ $ext_arg{$1} }, $2; 829 push @{ $ext_arg{$1} }, $2;
618 } else { 830 } else {
641 if $verbosity >= 10; 853 if $verbosity >= 10;
642 854
643 keys %$cb; 855 keys %$cb;
644 856
645 while (my ($pkg, $cb) = each %$cb) { 857 while (my ($pkg, $cb) = each %$cb) {
646 $retval = eval { $cb->($TERM->{_pkg}{$pkg}, @_) } 858 my $retval_ = eval { $cb->($TERM->{_pkg}{$pkg}, @_) };
647 and last; 859 $retval ||= $retval_;
648 860
649 if ($@) { 861 if ($@) {
650 $TERM->ungrab; # better to lose the grab than the session 862 $TERM->ungrab; # better to lose the grab than the session
651 warn $@; 863 warn $@;
652 } 864 }
655 verbose 11, "$HOOKNAME[$htype] returning <$retval>" 867 verbose 11, "$HOOKNAME[$htype] returning <$retval>"
656 if $verbosity >= 11; 868 if $verbosity >= 11;
657 } 869 }
658 870
659 if ($htype == 1) { # DESTROY 871 if ($htype == 1) { # DESTROY
660 if (my $hook = delete $TERM->{_hook}) {
661 for my $htype (0..$#$hook) {
662 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
663 or set_should_invoke $htype, 0;
664 }
665 }
666
667 # clear package objects 872 # clear package objects
668 %$_ = () for values %{ $TERM->{_pkg} }; 873 %$_ = () for values %{ $TERM->{_pkg} };
669 874
670 # clear package 875 # clear package
671 %$TERM = (); 876 %$TERM = ();
672 } 877 }
673 878
674 $retval 879 $retval
675}
676
677sub exec_async(@) {
678 my $pid = fork;
679
680 return
681 if !defined $pid or $pid;
682
683 %ENV = %{ $TERM->env };
684
685 exec @_;
686 _exit 255;
687} 880}
688 881
689# urxvt::term::extension 882# urxvt::term::extension
690 883
691package urxvt::term::extension; 884package urxvt::term::extension;
697 while (my ($name, $cb) = each %hook) { 890 while (my ($name, $cb) = each %hook) {
698 my $htype = $HOOKTYPE{uc $name}; 891 my $htype = $HOOKTYPE{uc $name};
699 defined $htype 892 defined $htype
700 or Carp::croak "unsupported hook type '$name'"; 893 or Carp::croak "unsupported hook type '$name'";
701 894
895 $self->set_should_invoke ($htype, +1)
702 unless (exists $self->{term}{_hook}[$htype]{$pkg}) { 896 unless exists $self->{term}{_hook}[$htype]{$pkg};
703 $hook_count[$htype]++
704 or urxvt::set_should_invoke $htype, 1;
705 }
706 897
707 $self->{term}{_hook}[$htype]{$pkg} = $cb; 898 $self->{term}{_hook}[$htype]{$pkg} = $cb;
708 } 899 }
709} 900}
710 901
715 for my $name (@hook) { 906 for my $name (@hook) {
716 my $htype = $HOOKTYPE{uc $name}; 907 my $htype = $HOOKTYPE{uc $name};
717 defined $htype 908 defined $htype
718 or Carp::croak "unsupported hook type '$name'"; 909 or Carp::croak "unsupported hook type '$name'";
719 910
911 $self->set_should_invoke ($htype, -1)
720 if (delete $self->{term}{_hook}[$htype]{$pkg}) { 912 if delete $self->{term}{_hook}[$htype]{$pkg};
721 --$hook_count[$htype]
722 or urxvt::set_should_invoke $htype, 0;
723 }
724 } 913 }
725} 914}
726 915
727our $AUTOLOAD; 916our $AUTOLOAD;
728 917
834# find on_xxx subs in the package and register them 1023# find on_xxx subs in the package and register them
835# as hooks 1024# as hooks
836sub register_package { 1025sub register_package {
837 my ($self, $pkg, $argv) = @_; 1026 my ($self, $pkg, $argv) = @_;
838 1027
1028 no strict 'refs';
1029
1030 urxvt::verbose 6, "register package $pkg to $self";
1031
1032 @{"$pkg\::ISA"} = urxvt::term::extension::;
1033
839 my $proxy = bless { 1034 my $proxy = bless {
840 _pkg => $pkg, 1035 _pkg => $pkg,
841 argv => $argv, 1036 argv => $argv,
842 }, $pkg; 1037 }, $pkg;
843 Scalar::Util::weaken ($proxy->{term} = $self); 1038 Scalar::Util::weaken ($proxy->{term} = $self);
874 1069
875Destroy the terminal object (close the window, free resources 1070Destroy the terminal object (close the window, free resources
876etc.). 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
877watchers (timers, io watchers) are still active. 1072watchers (timers, io watchers) are still active.
878 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
879=item $isset = $term->option ($optval[, $set]) 1099=item $isset = $term->option ($optval[, $set])
880 1100
881Returns true if the option specified by C<$optval> is enabled, and 1101Returns true if the option specified by C<$optval> is enabled, and
882optionally 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
883C<%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.
885Here 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
886source file F</src/optinc.h> to see the actual list: 1106source file F</src/optinc.h> to see the actual list:
887 1107
888 borderLess console cursorBlink cursorUnderline hold iconic insecure 1108 borderLess console cursorBlink cursorUnderline hold iconic insecure
889 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 1109 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
890 pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating 1110 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
891 scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer 1111 scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput
892 secondaryScreen secondaryScroll skipBuiltinGlyphs transparent 1112 scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs
893 tripleclickwords utmpInhibit visualBell 1113 transparent tripleclickwords utmpInhibit visualBell
894 1114
895=item $value = $term->resource ($name[, $newval]) 1115=item $value = $term->resource ($name[, $newval])
896 1116
897Returns the current resource value associated with a given name and 1117Returns the current resource value associated with a given name and
898optionally 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>
915 1135
916 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1136 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
917 borderLess color cursorBlink cursorUnderline cutchars delete_key 1137 borderLess color cursorBlink cursorUnderline cutchars delete_key
918 display_name embed ext_bwidth fade font geometry hold iconName 1138 display_name embed ext_bwidth fade font geometry hold iconName
919 imFont imLocale inputMethod insecure int_bwidth intensityStyles 1139 imFont imLocale inputMethod insecure int_bwidth intensityStyles
920 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier 1140 italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier
921 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2 1141 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
922 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 1142 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
923 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 1143 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
924 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 1144 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
925 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 1145 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
926 shade term_name title transparent transparent_all tripleclickwords 1146 secondaryScreen secondaryScroll selectstyle shade term_name title
927 utmpInhibit visualBell 1147 transient_for transparent transparent_all tripleclickwords utmpInhibit
1148 visualBell
928 1149
929=cut 1150=cut
930 1151
931sub resource($$;$) { 1152sub resource($$;$) {
932 my ($self, $name) = (shift, shift); 1153 my ($self, $name) = (shift, shift);
1106 1327
1107Normally 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
1108confused by changes in cursor position or scrolling. Its useful inside a 1329confused by changes in cursor position or scrolling. Its useful inside a
1109C<on_add_lines> hook, though. 1330C<on_add_lines> hook, though.
1110 1331
1332=item $term->scr_change_screen ($screen)
1333
1334Switch to given screen - 0 primary, 1 secondary.
1335
1111=item $term->cmd_parse ($octets) 1336=item $term->cmd_parse ($octets)
1112 1337
1113Similar 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
1114locale-specific encoding of the terminal and can contain command sequences 1339locale-specific encoding of the terminal and can contain command sequences
1115(escape codes) that will be interpreted. 1340(escape codes) that will be interpreted.
1125Replaces 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
1126be 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
1127description of C<< urxvt::timer->events >>. Make sure to always restore 1352description of C<< urxvt::timer->events >>. Make sure to always restore
1128the previous value. 1353the previous value.
1129 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
1130=item $windowid = $term->parent 1360=item $windowid = $term->parent
1131 1361
1132Return the window id of the toplevel window. 1362Return the window id of the toplevel window.
1133 1363
1134=item $windowid = $term->vt 1364=item $windowid = $term->vt
1135 1365
1136Return the window id of the terminal window. 1366Return the window id of the terminal window.
1137 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
1138=item $window_width = $term->width 1375=item $window_width = $term->width
1139 1376
1140=item $window_height = $term->height 1377=item $window_height = $term->height
1141 1378
1142=item $font_width = $term->fwidth 1379=item $font_width = $term->fwidth
1155 1392
1156=item $max_scrollback = $term->saveLines 1393=item $max_scrollback = $term->saveLines
1157 1394
1158=item $nrow_plus_saveLines = $term->total_rows 1395=item $nrow_plus_saveLines = $term->total_rows
1159 1396
1160=item $lines_in_scrollback = $term->nsaved 1397=item $topmost_scrollback_row = $term->top_row
1161 1398
1162Return various integers describing terminal characteristics. 1399Return various integers describing terminal characteristics.
1163 1400
1164=item $x_display = $term->display_id 1401=item $x_display = $term->display_id
1165 1402
1191=item $modifiermask = $term->ModNumLockMask 1428=item $modifiermask = $term->ModNumLockMask
1192 1429
1193Return the modifier masks corresponding to the "ISO Level 3 Shift" (often 1430Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
1194AltGr), 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.
1195 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
1196=item $view_start = $term->view_start ([$newvalue]) 1441=item $view_start = $term->view_start ([$newvalue])
1197 1442
1198Returns the negative row number of the topmost line. Minimum value is 1443Returns the row number of the topmost displayed line. Maximum value is
1199C<0>, which displays the normal terminal contents. Larger values scroll 1444C<0>, which displays the normal terminal contents. Lower values scroll
1200this many lines into the scrollback buffer. 1445this many lines into the scrollback buffer.
1201 1446
1202=item $term->want_refresh 1447=item $term->want_refresh
1203 1448
1204Requests a screen refresh. At the next opportunity, rxvt-unicode will 1449Requests a screen refresh. At the next opportunity, rxvt-unicode will
1219line, 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
1220to 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
1221automatically be updated. 1466automatically be updated.
1222 1467
1223C<$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
1224than one cell when displayed are padded with urxvt::NOCHAR characters 1469than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535)
1225(C<chr 65535>). Characters with combining characters and other characters 1470characters. Characters with combining characters and other characters that
1226that 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
1227characters in the private use area. 1472in the private use area.
1228 1473
1229You have to obey this encoding when changing text. The advantage is 1474You have to obey this encoding when changing text. The advantage is
1230that 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
1231characters. 1476characters.
1232 1477
1407 1652
1408Calls XUngrab for the most recent grab. Is called automatically on 1653Calls XUngrab for the most recent grab. Is called automatically on
1409evaluation 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
1410the session. 1655the session.
1411 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
1412=back 1687=back
1413 1688
1414=cut 1689=cut
1415 1690
1416package urxvt::popup; 1691package urxvt::popup;
1517 my $env = $self->{term}->env; 1792 my $env = $self->{term}->env;
1518 # 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.
1519 delete $env->{LC_ALL}; 1794 delete $env->{LC_ALL};
1520 $env->{LC_CTYPE} = $self->{term}->locale; 1795 $env->{LC_CTYPE} = $self->{term}->locale;
1521 1796
1522 urxvt::term->new ($env, $self->{term}->resource ("name"), 1797 urxvt::term->new ($env, "popup",
1523 "--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",
1524 "--transient-for" => $self->{term}->parent, 1801 "--transient-for" => $self->{term}->parent,
1525 "-display" => $self->{term}->display_id, 1802 "-display" => $self->{term}->display_id,
1526 "-pe" => "urxvt-popup") 1803 "-pe" => "urxvt-popup")
1527 or die "unable to create popup window\n"; 1804 or die "unable to create popup window\n";
1528} 1805}
1533 delete $self->{term}{_destroy}{$self}; 1810 delete $self->{term}{_destroy}{$self};
1534 $self->{term}->ungrab; 1811 $self->{term}->ungrab;
1535} 1812}
1536 1813
1537=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__;
1538 1824
1539=head2 The C<urxvt::timer> Class 1825=head2 The C<urxvt::timer> Class
1540 1826
1541This class implements timer watchers/events. Time is represented as a 1827This class implements timer watchers/events. Time is represented as a
1542fractional number of seconds since the epoch. Example: 1828fractional number of seconds since the epoch. Example:
1580Start the timer. 1866Start the timer.
1581 1867
1582=item $timer = $timer->start ($tstamp) 1868=item $timer = $timer->start ($tstamp)
1583 1869
1584Set 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>.
1585 1875
1586=item $timer = $timer->stop 1876=item $timer = $timer->stop
1587 1877
1588Stop the timer. 1878Stop the timer.
1589 1879
1636 1926
1637Stop watching for events on the given filehandle. 1927Stop watching for events on the given filehandle.
1638 1928
1639=back 1929=back
1640 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
1641=head1 ENVIRONMENT 1992=head1 ENVIRONMENT
1642 1993
1643=head2 URXVT_PERL_VERBOSITY 1994=head2 URXVT_PERL_VERBOSITY
1644 1995
1645This 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