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.97 by elmex, Tue Jan 17 16:53:47 2006 UTC vs.
Revision 1.132 by root, Mon Feb 6 05:40:15 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 following bindable keyboard commands: 82This extension also offers following bindable keyboard commands:
72 83
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
125 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\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/^([^:[:space:]]+(\\d+):?$/\\x1b:e \\Q$1\\E\\x0d:$2\\x0d/ 185 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/
131 186
132Of course, this can be modified to suit your needs and your editor :) 187Of course, this can be modified to suit your needs and your editor :)
133 188
134To expand the example above to typical perl error messages ("XXX at 189To expand the example above to typical perl error messages ("XXX at
135FILENAME line YYY."), you need a slightly more elaborate solution: 190FILENAME line YYY."), you need a slightly more elaborate solution:
136 191
137 URxvt.selection.pattern-0: ( at .*? line \\d+\\.) 192 URxvt.selection.pattern-0: ( at .*? line \\d+[,.])
138 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)\\.$/\x1b:e \\Q$1\E\\x0d:$2\\x0d/ 193 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/
139 194
140The first line tells the selection code to treat the unchanging part of 195The first line tells the selection code to treat the unchanging part of
141every error message as a selection pattern, and the second line transforms 196every error message as a selection pattern, and the second line transforms
142the message into vi commands to load the file. 197the message into vi commands to load the file.
198
199=item tabbed
200
201This transforms the terminal into a tabbar with additional terminals, that
202is, it implements what is commonly refered to as "tabbed terminal". The topmost line
203displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one
204button per tab.
205
206Clicking a button will activate that tab. Pressing B<Shift-Left> and
207B<Shift-Right> will switch to the tab left or right of the current one,
208while B<Shift-Down> creates a new tab.
209
210The tabbar itself can be configured similarly to a normal terminal, but
211with a resource class of C<URxvt.tabbed>. In addition, it supports the
212following four resources (shown with defaults):
213
214 URxvt.tabbed.tabbar-fg: <colour-index, default 3>
215 URxvt.tabbed.tabbar-bg: <colour-index, default 0>
216 URxvt.tabbed.tab-fg: <colour-index, default 0>
217 URxvt.tabbed.tab-bg: <colour-index, default 1>
218
219See I<COLOR AND GRAPHICS> in the @@RXVT_NAME@@(1) manpage for valid
220indices.
143 221
144=item mark-urls 222=item mark-urls
145 223
146Uses per-line display filtering (C<on_line_update>) to underline urls and 224Uses per-line display filtering (C<on_line_update>) to underline urls and
147make them clickable. When middle-clicked, the program specified in the 225make them clickable. When middle-clicked, the program specified in the
148resource C<urlLauncher> (default C<x-www-browser>) will be started with 226resource C<urlLauncher> (default C<x-www-browser>) will be started with
149the URL as first argument. 227the URL as first argument.
150 228
229=item xim-onthespot
230
231This (experimental) perl extension implements OnTheSpot editing. It does
232not work perfectly, and some input methods don't seem to work well with
233OnTheSpot editing in general, but it seems to work at leats for SCIM and
234kinput2.
235
236You enable it by specifying this extension and a preedit style of
237C<OnTheSpot>, i.e.:
238
239 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot
240
241=item automove-background
242
243This is basically a one-line extension that dynamically changes the background pixmap offset
244to the window position, in effect creating the same effect as pseudo transparency with
245a custom pixmap. No scaling is supported in this mode. Exmaple:
246
247 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background
248
151=item block-graphics-to-ascii 249=item block-graphics-to-ascii
152 250
153A not very useful example of filtering all text output to the terminal, 251A not very useful example of filtering all text output to the terminal,
154by replacing all line-drawing characters (U+2500 .. U+259F) by a 252by replacing all line-drawing characters (U+2500 .. U+259F) by a
155similar-looking ascii character. 253similar-looking ascii character.
156 254
157=item digital-clock 255=item digital-clock
158 256
159Displays a digital clock using the built-in overlay. 257Displays a digital clock using the built-in overlay.
160 258
259=item remote-clipboard
260
261Somewhat of a misnomer, this extension adds two menu entries to the
262selection popup that allows one ti run external commands to store the
263selection somewhere and fetch it again.
264
265We use it to implement a "distributed selection mechanism", which just
266means that one command uploads the file to a remote server, and another
267reads it.
268
269The commands can be set using the C<URxvt.remote-selection.store> and
270C<URxvt.remote-selection.fetch> resources. The first should read the
271selection to store from STDIN (always in UTF-8), the second should provide
272the selection data on STDOUT (also in UTF-8).
273
274The defaults (which are likely useless to you) use rsh and cat:
275
276 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
277 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
278
279=item selection-pastebin
280
281This is a little rarely useful extension that Uploads the selection as
282textfile to a remote site (or does other things). (The implementation is
283not currently secure for use in a multiuser environment as it writes to
284F</tmp> directly.).
285
286It listens to the C<selection-pastebin:remote-pastebin> keyboard command,
287i.e.
288
289 URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin
290
291Pressing this combination runs a command with C<%> replaced by the name of
292the textfile. This command can be set via a resource:
293
294 URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
295
296And the default is likely not useful to anybody but the few people around
297here :)
298
299The name of the textfile is the hex encoded md5 sum of the selection, so
300the same content should lead to the same filename.
301
302After a successful upload the selection will be replaced by the text given
303in the C<selection-pastebin-url> resource (again, the % is the placeholder
304for the filename):
305
306 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
307
161=item example-refresh-hooks 308=item example-refresh-hooks
162 309
163Displays a very simple digital clock in the upper right corner of the 310Displays a very simple digital clock in the upper right corner of the
164window. Illustrates overwriting the refresh callbacks to create your own 311window. Illustrates overwriting the refresh callbacks to create your own
165overlays or changes. 312overlays or changes.
166
167=item selection-pastebin
168
169Uploads the selection as textfile to a remote site.
170
171 URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin
172
173To set the command to upload the file set this resource:
174
175 URxvt.selection-pastebin-cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
176
177The % is the placeholder for the textfile. The name of the textfile is the hex encoded
178md5 sum of the selection.
179After an successful upload the selection will be replaced by the following url
180(the % is the placeholder for the filename):
181
182 URxvt.selection-pastebin-url: http://www.ta-sa.org/files/txt/%
183 313
184=back 314=back
185 315
186=head1 API DOCUMENTATION 316=head1 API DOCUMENTATION
187 317
260called whenever the relevant event happens. 390called whenever the relevant event happens.
261 391
262The first argument passed to them is an extension oject as described in 392The first argument passed to them is an extension oject as described in
263the in the C<Extension Objects> section. 393the in the C<Extension Objects> section.
264 394
265B<All> of these hooks must return a boolean value. If it is true, then the 395B<All> of these hooks must return a boolean value. If any of the called
266event counts as being I<consumed>, and the invocation of other hooks is 396hooks returns true, then the event counts as being I<consumed>, and the
267skipped, and the relevant action might not be carried out by the C++ code. 397relevant action might not be carried out by the C++ code.
268 398
269I<< When in doubt, return a false value (preferably C<()>). >> 399I<< When in doubt, return a false value (preferably C<()>). >>
270 400
271=over 4 401=over 4
272 402
273=item on_init $term 403=item on_init $term
274 404
275Called after a new terminal object has been initialized, but before 405Called after a new terminal object has been initialized, but before
276windows are created or the command gets run. Most methods are unsafe to 406windows are created or the command gets run. Most methods are unsafe to
277call or deliver senseless data, as terminal size and other characteristics 407call or deliver senseless data, as terminal size and other characteristics
278have not yet been determined. You can safely query and change resources, 408have not yet been determined. You can safely query and change resources
279though. 409and options, though. For many purposes the C<on_start> hook is a better
410place.
411
412=item on_start $term
413
414Called at the very end of initialisation of a new terminal, just before
415trying to map (display) the toplevel and returning to the mainloop.
416
417=item on_destroy $term
418
419Called whenever something tries to destroy terminal, when the terminal is
420still fully functional (not for long, though).
280 421
281=item on_reset $term 422=item on_reset $term
282 423
283Called after the screen is "reset" for any reason, such as resizing or 424Called after the screen is "reset" for any reason, such as resizing or
284control sequences. Here is where you can react on changes to size-related 425control sequences. Here is where you can react on changes to size-related
285variables. 426variables.
286 427
287=item on_start $term 428=item on_child_start $term, $pid
288 429
289Called at the very end of initialisation of a new terminal, just before 430Called just after the child process has been C<fork>ed.
290returning to the mainloop. 431
432=item on_child_exit $term, $status
433
434Called just after the child process has exited. C<$status> is the status
435from C<waitpid>.
291 436
292=item on_sel_make $term, $eventtime 437=item on_sel_make $term, $eventtime
293 438
294Called whenever a selection has been made by the user, but before the 439Called whenever a selection has been made by the user, but before the
295selection text is copied, so changes to the beginning, end or type of the 440selection text is copied, so changes to the beginning, end or type of the
382 527
383=item on_refresh_end $term 528=item on_refresh_end $term
384 529
385Called just after the screen gets redrawn. See C<on_refresh_begin>. 530Called just after the screen gets redrawn. See C<on_refresh_begin>.
386 531
387=item on_keyboard_command $term, $string 532=item on_user_command $term, $string
388 533
389Called whenever the user presses a key combination that has a 534Called whenever the a user-configured event is being activated (e.g. via
390C<perl:string> action bound to it (see description of the B<keysym> 535a C<perl:string> action bound to a key, see description of the B<keysym>
391resource in the @@RXVT_NAME@@(1) manpage). 536resource in the @@RXVT_NAME@@(1) manpage).
537
538The event is simply the action string. This interface is assumed to change
539slightly in the future.
392 540
393=item on_x_event $term, $event 541=item on_x_event $term, $event
394 542
395Called on every X event received on the vt window (and possibly other 543Called on every X event received on the vt window (and possibly other
396windows). Should only be used as a last resort. Most event structure 544windows). Should only be used as a last resort. Most event structure
404=item on_focus_out $term 552=item on_focus_out $term
405 553
406Called wheneever the window loses keyboard focus, before rxvt-unicode does 554Called wheneever the window loses keyboard focus, before rxvt-unicode does
407focus out processing. 555focus out processing.
408 556
557=item on_configure_notify $term, $event
558
559=item on_property_notify $term, $event
560
409=item on_key_press $term, $event, $keysym, $octets 561=item on_key_press $term, $event, $keysym, $octets
410 562
411=item on_key_release $term, $event, $keysym 563=item on_key_release $term, $event, $keysym
412 564
413=item on_button_press $term, $event 565=item on_button_press $term, $event
422 574
423Called whenever the corresponding X event is received for the terminal If 575Called whenever the corresponding X event is received for the terminal If
424the hook returns true, then the even will be ignored by rxvt-unicode. 576the hook returns true, then the even will be ignored by rxvt-unicode.
425 577
426The event is a hash with most values as named by Xlib (see the XEvent 578The event is a hash with most values as named by Xlib (see the XEvent
427manpage), with the additional members C<row> and C<col>, which are the row 579manpage), with the additional members C<row> and C<col>, which are the
428and column under the mouse cursor. 580(real, not screen-based) row and column under the mouse cursor.
429 581
430C<on_key_press> additionally receives the string rxvt-unicode would 582C<on_key_press> additionally receives the string rxvt-unicode would
431output, if any, in locale-specific encoding. 583output, if any, in locale-specific encoding.
432 584
433subwindow. 585subwindow.
586
587=item on_client_message $term, $event
588
589=item on_wm_protocols $term, $event
590
591=item on_wm_delete_window $term, $event
592
593Called when various types of ClientMessage events are received (all with
594format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
434 595
435=back 596=back
436 597
437=cut 598=cut
438 599
444use Scalar::Util (); 605use Scalar::Util ();
445use List::Util (); 606use List::Util ();
446 607
447our $VERSION = 1; 608our $VERSION = 1;
448our $TERM; 609our $TERM;
610our @TERM_INIT;
611our @TERM_EXT;
449our @HOOKNAME; 612our @HOOKNAME;
450our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME; 613our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
451our %OPTION; 614our %OPTION;
452 615
453our $LIBDIR; 616our $LIBDIR;
454our $RESNAME; 617our $RESNAME;
455our $RESCLASS; 618our $RESCLASS;
456our $RXVTNAME; 619our $RXVTNAME;
457 620
621our $NOCHAR = chr 0xffff;
622
458=head2 Variables in the C<urxvt> Package 623=head2 Variables in the C<urxvt> Package
459 624
460=over 4 625=over 4
461 626
462=item $urxvt::LIBDIR 627=item $urxvt::LIBDIR
474 639
475=item $urxvt::TERM 640=item $urxvt::TERM
476 641
477The current terminal. This variable stores the current C<urxvt::term> 642The current terminal. This variable stores the current C<urxvt::term>
478object, whenever a callback/hook is executing. 643object, whenever a callback/hook is executing.
644
645=item @urxvt::TERM_INIT
646
647All coderefs in this array will be called as methods of the next newly
648created C<urxvt::term> object (during the C<on_init> phase). The array
649gets cleared before the codereferences that were in it are being executed,
650so coderefs can push themselves onto it again if they so desire.
651
652This complements to the perl-eval commandline option, but gets executed
653first.
654
655=item @urxvt::TERM_EXT
656
657Works similar to C<@TERM_INIT>, but contains perl package/class names, which
658get registered as normal extensions after calling the hooks in C<@TERM_INIT>
659but before other extensions. Gets cleared just like C<@TERM_INIT>.
479 660
480=back 661=back
481 662
482=head2 Functions in the C<urxvt> Package 663=head2 Functions in the C<urxvt> Package
483 664
497 678
498Using this function has the advantage that its output ends up in the 679Using this function has the advantage that its output ends up in the
499correct place, e.g. on stderr of the connecting urxvtc client. 680correct place, e.g. on stderr of the connecting urxvtc client.
500 681
501Messages have a size limit of 1023 bytes currently. 682Messages have a size limit of 1023 bytes currently.
683
684=item @terms = urxvt::termlist
685
686Returns all urxvt::term objects that exist in this process, regardless of
687wether they are started, being destroyed etc., so be careful. Only term
688objects that have perl extensions attached will be returned (because there
689is no urxvt::term objet associated with others).
502 690
503=item $time = urxvt::NOW 691=item $time = urxvt::NOW
504 692
505Returns the "current time" (as per the event loop). 693Returns the "current time" (as per the event loop).
506 694
565 753
566=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour 754=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
567 755
568=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour 756=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
569 757
758=item $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
759
570Replace the foreground/background colour in the rendition mask with the 760Replace the foreground/background colour in the rendition mask with the
571specified one. 761specified one.
572 762
573=item $value = urxvt::GET_CUSTOM $rend 763=item $value = urxvt::GET_CUSTOM $rend
574 764
583=back 773=back
584 774
585=cut 775=cut
586 776
587BEGIN { 777BEGIN {
588 urxvt->bootstrap;
589
590 # overwrite perl's warn 778 # overwrite perl's warn
591 *CORE::GLOBAL::warn = sub { 779 *CORE::GLOBAL::warn = sub {
592 my $msg = join "", @_; 780 my $msg = join "", @_;
593 $msg .= "\n" 781 $msg .= "\n"
594 unless $msg =~ /\n$/; 782 unless $msg =~ /\n$/;
595 urxvt::warn ($msg); 783 urxvt::warn ($msg);
596 }; 784 };
597
598 # %ENV is the original startup environment
599 delete $ENV{IFS};
600 delete $ENV{CDPATH};
601 delete $ENV{BASH_ENV};
602 $ENV{PATH} = "/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/opt/bin:/opt/sbin";
603} 785}
786
787no warnings 'utf8';
604 788
605my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 789my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
606 790
607sub verbose { 791sub verbose {
608 my ($level, $msg) = @_; 792 my ($level, $msg) = @_;
609 warn "$msg\n" if $level <= $verbosity; 793 warn "$msg\n" if $level <= $verbosity;
610} 794}
611 795
612my $extension_pkg = "extension0000";
613my %extension_pkg; 796my %extension_pkg;
614 797
615# load a single script into its own package, once only 798# load a single script into its own package, once only
616sub extension_package($) { 799sub extension_package($) {
617 my ($path) = @_; 800 my ($path) = @_;
618 801
619 $extension_pkg{$path} ||= do { 802 $extension_pkg{$path} ||= do {
620 my $pkg = "urxvt::" . ($extension_pkg++); 803 $path =~ /([^\/\\]+)$/;
804 my $pkg = $1;
805 $pkg =~ s/[^[:word:]]/_/g;
806 $pkg = "urxvt::ext::$pkg";
621 807
622 verbose 3, "loading extension '$path' into package '$pkg'"; 808 verbose 3, "loading extension '$path' into package '$pkg'";
623 809
624 open my $fh, "<:raw", $path 810 open my $fh, "<:raw", $path
625 or die "$path: $!"; 811 or die "$path: $!";
626 812
627 my $source = 813 my $source =
628 "package $pkg; use strict; use utf8;\n" 814 "package $pkg; use strict; use utf8; no warnings 'utf8';\n"
629 . "use base urxvt::term::extension::;\n"
630 . "#line 1 \"$path\"\n{\n" 815 . "#line 1 \"$path\"\n{\n"
631 . (do { local $/; <$fh> }) 816 . (do { local $/; <$fh> })
632 . "\n};\n1"; 817 . "\n};\n1";
633 818
634 eval $source 819 eval $source
648 if ($htype == 0) { # INIT 833 if ($htype == 0) { # INIT
649 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 834 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
650 835
651 my %ext_arg; 836 my %ext_arg;
652 837
838 {
839 my @init = @TERM_INIT;
840 @TERM_INIT = ();
841 $_->($TERM) for @init;
842 my @pkg = @TERM_EXT;
843 @TERM_EXT = ();
844 $TERM->register_package ($_) for @pkg;
845 }
846
653 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) { 847 for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
654 if ($_ eq "default") { 848 if ($_ eq "default") {
655 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback); 849 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback readline);
656 } elsif (/^-(.*)$/) { 850 } elsif (/^-(.*)$/) {
657 delete $ext_arg{$1}; 851 delete $ext_arg{$1};
658 } elsif (/^([^<]+)<(.*)>$/) { 852 } elsif (/^([^<]+)<(.*)>$/) {
659 push @{ $ext_arg{$1} }, $2; 853 push @{ $ext_arg{$1} }, $2;
660 } else { 854 } else {
683 if $verbosity >= 10; 877 if $verbosity >= 10;
684 878
685 keys %$cb; 879 keys %$cb;
686 880
687 while (my ($pkg, $cb) = each %$cb) { 881 while (my ($pkg, $cb) = each %$cb) {
688 $retval = eval { $cb->($TERM->{_pkg}{$pkg}, @_) } 882 my $retval_ = eval { $cb->($TERM->{_pkg}{$pkg}, @_) };
689 and last; 883 $retval ||= $retval_;
690 884
691 if ($@) { 885 if ($@) {
692 $TERM->ungrab; # better to lose the grab than the session 886 $TERM->ungrab; # better to lose the grab than the session
693 warn $@; 887 warn $@;
694 } 888 }
707 } 901 }
708 902
709 $retval 903 $retval
710} 904}
711 905
712sub exec_async(@) { 906sub SET_COLOR($$$) {
713 my $pid = fork; 907 SET_BGCOLOR (SET_FGCOLOR ($_[0], $_[1]), $_[2])
714
715 return
716 if !defined $pid or $pid;
717
718 %ENV = %{ $TERM->env };
719
720 exec @_;
721 _exit 255;
722} 908}
723 909
724# urxvt::term::extension 910# urxvt::term::extension
725 911
726package urxvt::term::extension; 912package urxvt::term::extension;
865# find on_xxx subs in the package and register them 1051# find on_xxx subs in the package and register them
866# as hooks 1052# as hooks
867sub register_package { 1053sub register_package {
868 my ($self, $pkg, $argv) = @_; 1054 my ($self, $pkg, $argv) = @_;
869 1055
1056 no strict 'refs';
1057
1058 urxvt::verbose 6, "register package $pkg to $self";
1059
1060 @{"$pkg\::ISA"} = urxvt::term::extension::;
1061
870 my $proxy = bless { 1062 my $proxy = bless {
871 _pkg => $pkg, 1063 _pkg => $pkg,
872 argv => $argv, 1064 argv => $argv,
873 }, $pkg; 1065 }, $pkg;
874 Scalar::Util::weaken ($proxy->{term} = $self); 1066 Scalar::Util::weaken ($proxy->{term} = $self);
889hash which defines the environment of the new terminal. 1081hash which defines the environment of the new terminal.
890 1082
891Croaks (and probably outputs an error message) if the new instance 1083Croaks (and probably outputs an error message) if the new instance
892couldn't be created. Returns C<undef> if the new instance didn't 1084couldn't be created. Returns C<undef> if the new instance didn't
893initialise perl, and the terminal object otherwise. The C<init> and 1085initialise perl, and the terminal object otherwise. The C<init> and
894C<start> hooks will be called during this call. 1086C<start> hooks will be called before this call returns, and are free to
1087refer to global data (which is race free).
895 1088
896=cut 1089=cut
897 1090
898sub new { 1091sub new {
899 my ($class, $env, @args) = @_; 1092 my ($class, $env, @args) = @_;
900 1093
1094 $env or Carp::croak "environment hash missing in call to urxvt::term->new";
1095 @args or Carp::croak "name argument missing in call to urxvt::term->new";
1096
901 _new ([ map "$_=$env->{$_}", keys %$env ], @args); 1097 _new ([ map "$_=$env->{$_}", keys %$env ], \@args);
902} 1098}
903 1099
904=item $term->destroy 1100=item $term->destroy
905 1101
906Destroy the terminal object (close the window, free resources 1102Destroy the terminal object (close the window, free resources
907etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event 1103etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event
908watchers (timers, io watchers) are still active. 1104watchers (timers, io watchers) are still active.
909 1105
1106=item $term->exec_async ($cmd[, @args])
1107
1108Works like the combination of the C<fork>/C<exec> builtins, which executes
1109("starts") programs in the background. This function takes care of setting
1110the user environment before exec'ing the command (e.g. C<PATH>) and should
1111be preferred over explicit calls to C<exec> or C<system>.
1112
1113Returns the pid of the subprocess or C<undef> on error.
1114
1115=cut
1116
1117sub exec_async {
1118 my $self = shift;
1119
1120 my $pid = fork;
1121
1122 return $pid
1123 if !defined $pid or $pid;
1124
1125 %ENV = %{ $self->env };
1126
1127 exec @_;
1128 urxvt::_exit 255;
1129}
1130
910=item $isset = $term->option ($optval[, $set]) 1131=item $isset = $term->option ($optval[, $set])
911 1132
912Returns true if the option specified by C<$optval> is enabled, and 1133Returns true if the option specified by C<$optval> is enabled, and
913optionally change it. All option values are stored by name in the hash 1134optionally change it. All option values are stored by name in the hash
914C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash. 1135C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
916Here is a a likely non-exhaustive list of option names, please see the 1137Here is a a likely non-exhaustive list of option names, please see the
917source file F</src/optinc.h> to see the actual list: 1138source file F</src/optinc.h> to see the actual list:
918 1139
919 borderLess console cursorBlink cursorUnderline hold iconic insecure 1140 borderLess console cursorBlink cursorUnderline hold iconic insecure
920 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 1141 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
921 pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating 1142 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
922 scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer 1143 scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput
923 secondaryScreen secondaryScroll skipBuiltinGlyphs transparent 1144 scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs
924 tripleclickwords utmpInhibit visualBell 1145 transparent tripleclickwords utmpInhibit visualBell
925 1146
926=item $value = $term->resource ($name[, $newval]) 1147=item $value = $term->resource ($name[, $newval])
927 1148
928Returns the current resource value associated with a given name and 1149Returns the current resource value associated with a given name and
929optionally sets a new value. Setting values is most useful in the C<init> 1150optionally sets a new value. Setting values is most useful in the C<init>
946 1167
947 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1168 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
948 borderLess color cursorBlink cursorUnderline cutchars delete_key 1169 borderLess color cursorBlink cursorUnderline cutchars delete_key
949 display_name embed ext_bwidth fade font geometry hold iconName 1170 display_name embed ext_bwidth fade font geometry hold iconName
950 imFont imLocale inputMethod insecure int_bwidth intensityStyles 1171 imFont imLocale inputMethod insecure int_bwidth intensityStyles
951 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier 1172 italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier
952 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2 1173 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
953 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 1174 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
954 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 1175 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
955 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 1176 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
956 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 1177 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
957 shade term_name title transparent transparent_all tripleclickwords 1178 secondaryScreen secondaryScroll selectstyle shade term_name title
958 utmpInhibit visualBell 1179 transient_for transparent transparent_all tripleclickwords utmpInhibit
1180 visualBell
959 1181
960=cut 1182=cut
961 1183
962sub resource($$;$) { 1184sub resource($$;$) {
963 my ($self, $name) = (shift, shift); 1185 my ($self, $name) = (shift, shift);
1137 1359
1138Normally its not a good idea to use this function, as programs might be 1360Normally its not a good idea to use this function, as programs might be
1139confused by changes in cursor position or scrolling. Its useful inside a 1361confused by changes in cursor position or scrolling. Its useful inside a
1140C<on_add_lines> hook, though. 1362C<on_add_lines> hook, though.
1141 1363
1364=item $term->scr_change_screen ($screen)
1365
1366Switch to given screen - 0 primary, 1 secondary.
1367
1142=item $term->cmd_parse ($octets) 1368=item $term->cmd_parse ($octets)
1143 1369
1144Similar to C<scr_add_lines>, but the argument must be in the 1370Similar to C<scr_add_lines>, but the argument must be in the
1145locale-specific encoding of the terminal and can contain command sequences 1371locale-specific encoding of the terminal and can contain command sequences
1146(escape codes) that will be interpreted. 1372(escape codes) that will be interpreted.
1156Replaces the event mask of the pty watcher by the given event mask. Can 1382Replaces the event mask of the pty watcher by the given event mask. Can
1157be used to suppress input and output handling to the pty/tty. See the 1383be used to suppress input and output handling to the pty/tty. See the
1158description of C<< urxvt::timer->events >>. Make sure to always restore 1384description of C<< urxvt::timer->events >>. Make sure to always restore
1159the previous value. 1385the previous value.
1160 1386
1387=item $fd = $term->pty_fd
1388
1389Returns the master file descriptor for the pty in use, or C<-1> if no pty
1390is used.
1391
1161=item $windowid = $term->parent 1392=item $windowid = $term->parent
1162 1393
1163Return the window id of the toplevel window. 1394Return the window id of the toplevel window.
1164 1395
1165=item $windowid = $term->vt 1396=item $windowid = $term->vt
1170 1401
1171Adds the specified events to the vt event mask. Useful e.g. when you want 1402Adds the specified events to the vt event mask. Useful e.g. when you want
1172to receive pointer events all the times: 1403to receive pointer events all the times:
1173 1404
1174 $term->vt_emask_add (urxvt::PointerMotionMask); 1405 $term->vt_emask_add (urxvt::PointerMotionMask);
1406
1407=item $term->focus_in
1408
1409=item $term->focus_out
1410
1411=item $term->key_press ($state, $keycode[, $time])
1412
1413=item $term->key_release ($state, $keycode[, $time])
1414
1415Deliver various fake events to to terminal.
1175 1416
1176=item $window_width = $term->width 1417=item $window_width = $term->width
1177 1418
1178=item $window_height = $term->height 1419=item $window_height = $term->height
1179 1420
1229=item $modifiermask = $term->ModNumLockMask 1470=item $modifiermask = $term->ModNumLockMask
1230 1471
1231Return the modifier masks corresponding to the "ISO Level 3 Shift" (often 1472Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
1232AltGr), the meta key (often Alt) and the num lock key, if applicable. 1473AltGr), the meta key (often Alt) and the num lock key, if applicable.
1233 1474
1475=item $screen = $term->current_screen
1476
1477Returns the currently displayed screen (0 primary, 1 secondary).
1478
1479=item $cursor_is_hidden = $term->hidden_cursor
1480
1481Returns wether the cursor is currently hidden or not.
1482
1234=item $view_start = $term->view_start ([$newvalue]) 1483=item $view_start = $term->view_start ([$newvalue])
1235 1484
1236Returns the row number of the topmost displayed line. Maximum value is 1485Returns the row number of the topmost displayed line. Maximum value is
1237C<0>, which displays the normal terminal contents. Lower values scroll 1486C<0>, which displays the normal terminal contents. Lower values scroll
1238this many lines into the scrollback buffer. 1487this many lines into the scrollback buffer.
1257line, starting at column C<$start_col> (default C<0>), which is useful 1506line, starting at column C<$start_col> (default C<0>), which is useful
1258to replace only parts of a line. The font index in the rendition will 1507to replace only parts of a line. The font index in the rendition will
1259automatically be updated. 1508automatically be updated.
1260 1509
1261C<$text> is in a special encoding: tabs and wide characters that use more 1510C<$text> is in a special encoding: tabs and wide characters that use more
1262than one cell when displayed are padded with urxvt::NOCHAR characters 1511than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535)
1263(C<chr 65535>). Characters with combining characters and other characters 1512characters. Characters with combining characters and other characters that
1264that do not fit into the normal tetx encoding will be replaced with 1513do not fit into the normal tetx encoding will be replaced with characters
1265characters in the private use area. 1514in the private use area.
1266 1515
1267You have to obey this encoding when changing text. The advantage is 1516You have to obey this encoding when changing text. The advantage is
1268that C<substr> and similar functions work on screen cells and not on 1517that C<substr> and similar functions work on screen cells and not on
1269characters. 1518characters.
1270 1519
1417=item $string = $term->special_decode $text 1666=item $string = $term->special_decode $text
1418 1667
1419Converts rxvt-unicodes text reprsentation into a perl string. See 1668Converts rxvt-unicodes text reprsentation into a perl string. See
1420C<< $term->ROW_t >> for details. 1669C<< $term->ROW_t >> for details.
1421 1670
1422=item $success = $term->grab_button ($button, $modifiermask) 1671=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1423 1672
1673=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1674
1424Registers a synchronous button grab. See the XGrabButton manpage. 1675Register/unregister a synchronous button grab. See the XGrabButton
1676manpage.
1425 1677
1426=item $success = $term->grab ($eventtime[, $sync]) 1678=item $success = $term->grab ($eventtime[, $sync])
1427 1679
1428Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1680Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1429synchronous (C<$sync> is true). Also remembers the grab timestampe. 1681synchronous (C<$sync> is true). Also remembers the grab timestampe.
1444=item $term->ungrab 1696=item $term->ungrab
1445 1697
1446Calls XUngrab for the most recent grab. Is called automatically on 1698Calls XUngrab for the most recent grab. Is called automatically on
1447evaluation errors, as it is better to lose the grab in the error case as 1699evaluation errors, as it is better to lose the grab in the error case as
1448the session. 1700the session.
1701
1702=item $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
1703
1704=item $atom_name = $term->XGetAtomName ($atom)
1705
1706=item @atoms = $term->XListProperties ($window)
1707
1708=item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
1709
1710=item $term->XChangeWindowProperty ($window, $property, $type, $format, $octets)
1711
1712=item $term->XDeleteProperty ($window, $property)
1713
1714=item $window = $term->DefaultRootWindow
1715
1716=item $term->XReparentWindow ($window, $parent, [$x, $y])
1717
1718=item $term->XMapWindow ($window)
1719
1720=item $term->XUnmapWindow ($window)
1721
1722=item $term->XMoveResizeWindow ($window, $x, $y, $width, $height)
1723
1724=item ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x, $y)
1725
1726=item $term->XChangeInput ($window, $add_events[, $del_events])
1727
1728Various X or X-related functions. The C<$term> object only serves as
1729the source of the display, otherwise those functions map more-or-less
1730directory onto the X functions of the same name.
1449 1731
1450=back 1732=back
1451 1733
1452=cut 1734=cut
1453 1735
1555 my $env = $self->{term}->env; 1837 my $env = $self->{term}->env;
1556 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE. 1838 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
1557 delete $env->{LC_ALL}; 1839 delete $env->{LC_ALL};
1558 $env->{LC_CTYPE} = $self->{term}->locale; 1840 $env->{LC_CTYPE} = $self->{term}->locale;
1559 1841
1560 urxvt::term->new ($env, $self->{term}->resource ("name"), 1842 urxvt::term->new ($env, "popup",
1561 "--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0, 1843 "--perl-lib" => "", "--perl-ext-common" => "",
1844 "-pty-fd" => -1, "-sl" => 0,
1845 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect",
1562 "--transient-for" => $self->{term}->parent, 1846 "--transient-for" => $self->{term}->parent,
1563 "-display" => $self->{term}->display_id, 1847 "-display" => $self->{term}->display_id,
1564 "-pe" => "urxvt-popup") 1848 "-pe" => "urxvt-popup")
1565 or die "unable to create popup window\n"; 1849 or die "unable to create popup window\n";
1566} 1850}
1571 delete $self->{term}{_destroy}{$self}; 1855 delete $self->{term}{_destroy}{$self};
1572 $self->{term}->ungrab; 1856 $self->{term}->ungrab;
1573} 1857}
1574 1858
1575=back 1859=back
1860
1861=cut
1862
1863package urxvt::watcher;
1864
1865@urxvt::timer::ISA = __PACKAGE__;
1866@urxvt::iow::ISA = __PACKAGE__;
1867@urxvt::pw::ISA = __PACKAGE__;
1868@urxvt::iw::ISA = __PACKAGE__;
1576 1869
1577=head2 The C<urxvt::timer> Class 1870=head2 The C<urxvt::timer> Class
1578 1871
1579This class implements timer watchers/events. Time is represented as a 1872This class implements timer watchers/events. Time is represented as a
1580fractional number of seconds since the epoch. Example: 1873fractional number of seconds since the epoch. Example:
1618Start the timer. 1911Start the timer.
1619 1912
1620=item $timer = $timer->start ($tstamp) 1913=item $timer = $timer->start ($tstamp)
1621 1914
1622Set the event trigger time to C<$tstamp> and start the timer. 1915Set the event trigger time to C<$tstamp> and start the timer.
1916
1917=item $timer = $timer->after ($delay)
1918
1919Like C<start>, but sets the expiry timer to c<urxvt::NOW + $delay>.
1623 1920
1624=item $timer = $timer->stop 1921=item $timer = $timer->stop
1625 1922
1626Stop the timer. 1923Stop the timer.
1627 1924
1674 1971
1675Stop watching for events on the given filehandle. 1972Stop watching for events on the given filehandle.
1676 1973
1677=back 1974=back
1678 1975
1976=head2 The C<urxvt::iw> Class
1977
1978This class implements idle watchers, that get called automatically when
1979the process is idle. They should return as fast as possible, after doing
1980some useful work.
1981
1982=over 4
1983
1984=item $iw = new urxvt::iw
1985
1986Create a new idle watcher object in stopped state.
1987
1988=item $iw = $iw->cb (sub { my ($iw) = @_; ... })
1989
1990Set the callback to be called when the watcher triggers.
1991
1992=item $timer = $timer->start
1993
1994Start the watcher.
1995
1996=item $timer = $timer->stop
1997
1998Stop the watcher.
1999
2000=back
2001
2002=head2 The C<urxvt::pw> Class
2003
2004This class implements process watchers. They create an event whenever a
2005process exits, after which they stop automatically.
2006
2007 my $pid = fork;
2008 ...
2009 $term->{pw} = urxvt::pw
2010 ->new
2011 ->start ($pid)
2012 ->cb (sub {
2013 my ($pw, $exit_status) = @_;
2014 ...
2015 });
2016
2017=over 4
2018
2019=item $pw = new urxvt::pw
2020
2021Create a new process watcher in stopped state.
2022
2023=item $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
2024
2025Set the callback to be called when the timer triggers.
2026
2027=item $pw = $timer->start ($pid)
2028
2029Tells the wqtcher to start watching for process C<$pid>.
2030
2031=item $pw = $pw->stop
2032
2033Stop the watcher.
2034
2035=back
2036
1679=head1 ENVIRONMENT 2037=head1 ENVIRONMENT
1680 2038
1681=head2 URXVT_PERL_VERBOSITY 2039=head2 URXVT_PERL_VERBOSITY
1682 2040
1683This variable controls the verbosity level of the perl extension. Higher 2041This variable controls the verbosity level of the perl extension. Higher

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines