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