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.107 by root, Wed Jan 18 21:30:50 2006 UTC vs.
Revision 1.141 by root, Mon Jul 3 19:11:41 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
83=item option-popup (enabled by default) 94=item option-popup (enabled by default)
84 95
85Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at 96Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at
86runtime. 97runtime.
87 98
99Other extensions can extend this popup menu by pushing a code reference
100onto C<@{ $term->{option_popup_hook} }>, which gets called whenever the
101popup is being displayed.
102
103It's sole argument is the popup menu, which can be modified. It should
104either return nothing or a string, the initial boolean value and a code
105reference. The string will be used as button text and the code reference
106will be called when the toggle changes, with the new boolean value as
107first argument.
108
109The following will add an entry C<myoption> that changes
110C<$self->{myoption}>:
111
112 push @{ $self->{term}{option_popup_hook} }, sub {
113 ("my option" => $myoption, sub { $self->{myoption} = $_[0] })
114 };
115
88=item selection-popup (enabled by default) 116=item selection-popup (enabled by default)
89 117
90Binds a popup menu to Ctrl-Button3 that lets you convert the selection 118Binds a popup menu to Ctrl-Button3 that lets you convert the selection
91text into various other formats/action (such as uri unescaping, perl 119text into various other formats/action (such as uri unescaping, perl
92evalution, web-browser starting etc.), depending on content. 120evaluation, web-browser starting etc.), depending on content.
93 121
94Other extensions can extend this popup menu by pushing a code reference onto 122Other extensions can extend this popup menu by pushing a code reference
95C<@urxvt::ext::selection_popup::hook>, that is called whenever the popup is displayed. 123onto C<@{ $term->{selection_popup_hook} }>, which gets called whenever the
124popup is being displayed.
96 125
97It's sole argument is the popup menu, which can be modified. The selection 126It's sole argument is the popup menu, which can be modified. The selection
98is in C<$_>, which can be used to decide wether to add something or not. 127is in C<$_>, which can be used to decide wether to add something or not.
99It should either return nothing or a string and a code reference. The 128It should either return nothing or a string and a code reference. The
100string will be used as button text and the code reference will be called 129string will be used as button text and the code reference will be called
102 131
103The following will add an entry C<a to b> that transforms all C<a>s in 132The following will add an entry C<a to b> that transforms all C<a>s in
104the selection to C<b>s, but only if the selection currently contains any 133the selection to C<b>s, but only if the selection currently contains any
105C<a>s: 134C<a>s:
106 135
107 push urxvt::ext::selection_popup::hook, sub { 136 push @{ $self->{term}{selection_popup_hook} }, sub {
108 /a/ ? ("a to be" => sub { s/a/b/g } 137 /a/ ? ("a to be" => sub { s/a/b/g }
109 : () 138 : ()
110 }; 139 };
111 140
112=item searchable-scrollback<hotkey> (enabled by default) 141=item searchable-scrollback<hotkey> (enabled by default)
122bottom. C<Escape> leaves search mode and returns to the point where search 151bottom. C<Escape> leaves search mode and returns to the point where search
123was started, while C<Enter> or C<Return> stay at the current position and 152was started, while C<Enter> or C<Return> stay at the current position and
124additionally stores the first match in the current line into the primary 153additionally stores the first match in the current line into the primary
125selection. 154selection.
126 155
156=item readline (enabled by default)
157
158A support package that tries to make editing with readline easier. At
159the moment, it reacts to clicking shift-left mouse button by trying to
160move the text cursor to this position. It does so by generating as many
161cursor-left or cursor-right keypresses as required (the this only works
162for programs that correctly support wide characters).
163
164To avoid too many false positives, this is only done when:
165
166=over 4
167
168=item - the tty is in ICANON state.
169
170=item - the text cursor is visible.
171
172=item - the primary screen is currently being displayed.
173
174=item - the mouse is on the same (multi-row-) line as the text cursor.
175
176=back
177
178The normal selection mechanism isn't disabled, so quick successive clicks
179might interfere with selection creation in harmless ways.
180
127=item selection-autotransform 181=item selection-autotransform
128 182
129This selection allows you to do automatic transforms on a selection 183This selection allows you to do automatic transforms on a selection
130whenever a selection is made. 184whenever a selection is made.
131 185
143 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/ 197 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
144 198
145And this example matches the same,but replaces it with vi-commands you can 199And this example matches the same,but replaces it with vi-commands you can
146paste directly into your (vi :) editor: 200paste directly into your (vi :) editor:
147 201
148 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/\\x1b:e \\Q$1\\E\\x0d:$2\\x0d/ 202 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/
149 203
150Of course, this can be modified to suit your needs and your editor :) 204Of course, this can be modified to suit your needs and your editor :)
151 205
152To expand the example above to typical perl error messages ("XXX at 206To expand the example above to typical perl error messages ("XXX at
153FILENAME line YYY."), you need a slightly more elaborate solution: 207FILENAME line YYY."), you need a slightly more elaborate solution:
154 208
155 URxvt.selection.pattern-0: ( at .*? line \\d+\\.) 209 URxvt.selection.pattern-0: ( at .*? line \\d+[,.])
156 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)\\.$/\x1b:e \\Q$1\E\\x0d:$2\\x0d/ 210 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/
157 211
158The first line tells the selection code to treat the unchanging part of 212The first line tells the selection code to treat the unchanging part of
159every error message as a selection pattern, and the second line transforms 213every error message as a selection pattern, and the second line transforms
160the message into vi commands to load the file. 214the message into vi commands to load the file.
215
216=item tabbed
217
218This transforms the terminal into a tabbar with additional terminals, that
219is, it implements what is commonly refered to as "tabbed terminal". The topmost line
220displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one
221button per tab.
222
223Clicking a button will activate that tab. Pressing B<Shift-Left> and
224B<Shift-Right> will switch to the tab left or right of the current one,
225while B<Shift-Down> creates a new tab.
226
227The tabbar itself can be configured similarly to a normal terminal, but
228with a resource class of C<URxvt.tabbed>. In addition, it supports the
229following four resources (shown with defaults):
230
231 URxvt.tabbed.tabbar-fg: <colour-index, default 3>
232 URxvt.tabbed.tabbar-bg: <colour-index, default 0>
233 URxvt.tabbed.tab-fg: <colour-index, default 0>
234 URxvt.tabbed.tab-bg: <colour-index, default 1>
235
236See I<COLOR AND GRAPHICS> in the @@RXVT_NAME@@(1) manpage for valid
237indices.
161 238
162=item mark-urls 239=item mark-urls
163 240
164Uses per-line display filtering (C<on_line_update>) to underline urls and 241Uses per-line display filtering (C<on_line_update>) to underline urls and
165make them clickable. When middle-clicked, the program specified in the 242make them clickable. When middle-clicked, the program specified in the
166resource C<urlLauncher> (default C<x-www-browser>) will be started with 243resource C<urlLauncher> (default C<x-www-browser>) will be started with
167the URL as first argument. 244the URL as first argument.
168 245
246=item xim-onthespot
247
248This (experimental) perl extension implements OnTheSpot editing. It does
249not work perfectly, and some input methods don't seem to work well with
250OnTheSpot editing in general, but it seems to work at leats for SCIM and
251kinput2.
252
253You enable it by specifying this extension and a preedit style of
254C<OnTheSpot>, i.e.:
255
256 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot
257
169=item automove-background 258=item automove-background
170 259
171This is basically a one-line extension that dynamically changes the background pixmap offset 260This is basically a very small extension that dynamically changes the
172to the window position, in effect creating the same effect as pseudo transparency with 261background pixmap offset to the window position, in effect creating the
173a custom pixmap. No scaling is supported in this mode. Exmaple: 262same effect as pseudo transparency with a custom pixmap. No scaling is
263supported in this mode. Exmaple:
174 264
175 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background 265 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background
176 266
177=item block-graphics-to-ascii 267=item block-graphics-to-ascii
178 268
179A not very useful example of filtering all text output to the terminal, 269A not very useful example of filtering all text output to the terminal
180by replacing all line-drawing characters (U+2500 .. U+259F) by a 270by replacing all line-drawing characters (U+2500 .. U+259F) by a
181similar-looking ascii character. 271similar-looking ascii character.
182 272
183=item digital-clock 273=item digital-clock
184 274
185Displays a digital clock using the built-in overlay. 275Displays a digital clock using the built-in overlay.
186 276
187=item example-refresh-hooks 277=item remote-clipboard
188 278
189Displays a very simple digital clock in the upper right corner of the 279Somewhat of a misnomer, this extension adds two menu entries to the
190window. Illustrates overwriting the refresh callbacks to create your own 280selection popup that allows one ti run external commands to store the
191overlays or changes. 281selection somewhere and fetch it again.
282
283We use it to implement a "distributed selection mechanism", which just
284means that one command uploads the file to a remote server, and another
285reads it.
286
287The commands can be set using the C<URxvt.remote-selection.store> and
288C<URxvt.remote-selection.fetch> resources. The first should read the
289selection to store from STDIN (always in UTF-8), the second should provide
290the selection data on STDOUT (also in UTF-8).
291
292The defaults (which are likely useless to you) use rsh and cat:
293
294 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
295 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
192 296
193=item selection-pastebin 297=item selection-pastebin
194 298
195This is a little rarely useful extension that Uploads the selection as 299This is a little rarely useful extension that Uploads the selection as
196textfile to a remote site (or does other things). (The implementation is 300textfile to a remote site (or does other things). (The implementation is
216After a successful upload the selection will be replaced by the text given 320After a successful upload the selection will be replaced by the text given
217in the C<selection-pastebin-url> resource (again, the % is the placeholder 321in the C<selection-pastebin-url> resource (again, the % is the placeholder
218for the filename): 322for the filename):
219 323
220 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/% 324 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
325
326=item example-refresh-hooks
327
328Displays a very simple digital clock in the upper right corner of the
329window. Illustrates overwriting the refresh callbacks to create your own
330overlays or changes.
221 331
222=back 332=back
223 333
224=head1 API DOCUMENTATION 334=head1 API DOCUMENTATION
225 335
259 369
260=back 370=back
261 371
262=head2 Extension Objects 372=head2 Extension Objects
263 373
264Very perl extension is a perl class. A separate perl object is created 374Every perl extension is a perl class. A separate perl object is created
265for each terminal and each extension and passed as the first parameter to 375for each terminal and each extension and passed as the first parameter to
266hooks. So extensions can use their C<$self> object without having to think 376hooks. So extensions can use their C<$self> object without having to think
267about other extensions, with the exception of methods and members that 377about other extensions, with the exception of methods and members that
268begin with an underscore character C<_>: these are reserved for internal 378begin with an underscore character C<_>: these are reserved for internal
269use. 379use.
298called whenever the relevant event happens. 408called whenever the relevant event happens.
299 409
300The first argument passed to them is an extension oject as described in 410The first argument passed to them is an extension oject as described in
301the in the C<Extension Objects> section. 411the in the C<Extension Objects> section.
302 412
303B<All> of these hooks must return a boolean value. If it is true, then the 413B<All> of these hooks must return a boolean value. If any of the called
304event counts as being I<consumed>, and the invocation of other hooks is 414hooks returns true, then the event counts as being I<consumed>, and the
305skipped, and the relevant action might not be carried out by the C++ code. 415relevant action might not be carried out by the C++ code.
306 416
307I<< When in doubt, return a false value (preferably C<()>). >> 417I<< When in doubt, return a false value (preferably C<()>). >>
308 418
309=over 4 419=over 4
310 420
311=item on_init $term 421=item on_init $term
312 422
313Called after a new terminal object has been initialized, but before 423Called after a new terminal object has been initialized, but before
314windows are created or the command gets run. Most methods are unsafe to 424windows are created or the command gets run. Most methods are unsafe to
315call or deliver senseless data, as terminal size and other characteristics 425call or deliver senseless data, as terminal size and other characteristics
316have not yet been determined. You can safely query and change resources, 426have not yet been determined. You can safely query and change resources
317though. 427and options, though. For many purposes the C<on_start> hook is a better
428place.
429
430=item on_start $term
431
432Called at the very end of initialisation of a new terminal, just before
433trying to map (display) the toplevel and returning to the mainloop.
434
435=item on_destroy $term
436
437Called whenever something tries to destroy terminal, when the terminal is
438still fully functional (not for long, though).
318 439
319=item on_reset $term 440=item on_reset $term
320 441
321Called after the screen is "reset" for any reason, such as resizing or 442Called after the screen is "reset" for any reason, such as resizing or
322control sequences. Here is where you can react on changes to size-related 443control sequences. Here is where you can react on changes to size-related
323variables. 444variables.
324 445
325=item on_start $term 446=item on_child_start $term, $pid
326 447
327Called at the very end of initialisation of a new terminal, just before 448Called just after the child process has been C<fork>ed.
328returning to the mainloop. 449
450=item on_child_exit $term, $status
451
452Called just after the child process has exited. C<$status> is the status
453from C<waitpid>.
329 454
330=item on_sel_make $term, $eventtime 455=item on_sel_make $term, $eventtime
331 456
332Called whenever a selection has been made by the user, but before the 457Called whenever a selection has been made by the user, but before the
333selection text is copied, so changes to the beginning, end or type of the 458selection text is copied, so changes to the beginning, end or type of the
369 494
370It is called before lines are scrolled out (so rows 0 .. min ($lines - 1, 495It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
371$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total 496$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
372number of lines that will be in the scrollback buffer. 497number of lines that will be in the scrollback buffer.
373 498
499=item on_osc_seq $term, $op, $args
500
501Called on every OSC sequence and can be used to suppress it or modify its
502behaviour. The default should be to return an empty list. A true value
503suppresses execution of the request completely. Make sure you don't get
504confused by recursive invocations when you output an osc sequence within
505this callback.
506
507C<on_osc_seq_perl> should be used for new behaviour.
508
374=item on_osc_seq $term, $string 509=item on_osc_seq_perl $term, $string
375 510
376Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 511Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
377operating system command) is processed. Cursor position and other state 512operating system command) is processed. Cursor position and other state
378information is up-to-date when this happens. For interoperability, the 513information is up-to-date when this happens. For interoperability, the
379string should start with the extension name and a colon, to distinguish 514string should start with the extension name and a colon, to distinguish
420 555
421=item on_refresh_end $term 556=item on_refresh_end $term
422 557
423Called just after the screen gets redrawn. See C<on_refresh_begin>. 558Called just after the screen gets redrawn. See C<on_refresh_begin>.
424 559
425=item on_keyboard_command $term, $string 560=item on_user_command $term, $string
426 561
427Called whenever the user presses a key combination that has a 562Called whenever the a user-configured event is being activated (e.g. via
428C<perl:string> action bound to it (see description of the B<keysym> 563a C<perl:string> action bound to a key, see description of the B<keysym>
429resource in the @@RXVT_NAME@@(1) manpage). 564resource in the @@RXVT_NAME@@(1) manpage).
565
566The event is simply the action string. This interface is assumed to change
567slightly in the future.
568
569=item on_resize_all_windows $tern, $new_width, $new_height
570
571Called just after the new window size has been calculcated, but before
572windows are actually being resized or hints are being set. If this hook
573returns TRUE, setting of the window hints is being skipped.
430 574
431=item on_x_event $term, $event 575=item on_x_event $term, $event
432 576
433Called on every X event received on the vt window (and possibly other 577Called on every X event received on the vt window (and possibly other
434windows). Should only be used as a last resort. Most event structure 578windows). Should only be used as a last resort. Most event structure
444Called wheneever the window loses keyboard focus, before rxvt-unicode does 588Called wheneever the window loses keyboard focus, before rxvt-unicode does
445focus out processing. 589focus out processing.
446 590
447=item on_configure_notify $term, $event 591=item on_configure_notify $term, $event
448 592
593=item on_property_notify $term, $event
594
449=item on_key_press $term, $event, $keysym, $octets 595=item on_key_press $term, $event, $keysym, $octets
450 596
451=item on_key_release $term, $event, $keysym 597=item on_key_release $term, $event, $keysym
452 598
453=item on_button_press $term, $event 599=item on_button_press $term, $event
462 608
463Called whenever the corresponding X event is received for the terminal If 609Called whenever the corresponding X event is received for the terminal If
464the hook returns true, then the even will be ignored by rxvt-unicode. 610the hook returns true, then the even will be ignored by rxvt-unicode.
465 611
466The event is a hash with most values as named by Xlib (see the XEvent 612The event is a hash with most values as named by Xlib (see the XEvent
467manpage), with the additional members C<row> and C<col>, which are the row 613manpage), with the additional members C<row> and C<col>, which are the
468and column under the mouse cursor. 614(real, not screen-based) row and column under the mouse cursor.
469 615
470C<on_key_press> additionally receives the string rxvt-unicode would 616C<on_key_press> additionally receives the string rxvt-unicode would
471output, if any, in locale-specific encoding. 617output, if any, in locale-specific encoding.
472 618
473subwindow. 619subwindow.
620
621=item on_client_message $term, $event
622
623=item on_wm_protocols $term, $event
624
625=item on_wm_delete_window $term, $event
626
627Called when various types of ClientMessage events are received (all with
628format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
474 629
475=back 630=back
476 631
477=cut 632=cut
478 633
484use Scalar::Util (); 639use Scalar::Util ();
485use List::Util (); 640use List::Util ();
486 641
487our $VERSION = 1; 642our $VERSION = 1;
488our $TERM; 643our $TERM;
644our @TERM_INIT;
645our @TERM_EXT;
489our @HOOKNAME; 646our @HOOKNAME;
490our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME; 647our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
491our %OPTION; 648our %OPTION;
492 649
493our $LIBDIR; 650our $LIBDIR;
494our $RESNAME; 651our $RESNAME;
495our $RESCLASS; 652our $RESCLASS;
496our $RXVTNAME; 653our $RXVTNAME;
497 654
655our $NOCHAR = chr 0xffff;
656
498=head2 Variables in the C<urxvt> Package 657=head2 Variables in the C<urxvt> Package
499 658
500=over 4 659=over 4
501 660
502=item $urxvt::LIBDIR 661=item $urxvt::LIBDIR
514 673
515=item $urxvt::TERM 674=item $urxvt::TERM
516 675
517The current terminal. This variable stores the current C<urxvt::term> 676The current terminal. This variable stores the current C<urxvt::term>
518object, whenever a callback/hook is executing. 677object, whenever a callback/hook is executing.
678
679=item @urxvt::TERM_INIT
680
681All coderefs in this array will be called as methods of the next newly
682created C<urxvt::term> object (during the C<on_init> phase). The array
683gets cleared before the codereferences that were in it are being executed,
684so coderefs can push themselves onto it again if they so desire.
685
686This complements to the perl-eval commandline option, but gets executed
687first.
688
689=item @urxvt::TERM_EXT
690
691Works similar to C<@TERM_INIT>, but contains perl package/class names, which
692get registered as normal extensions after calling the hooks in C<@TERM_INIT>
693but before other extensions. Gets cleared just like C<@TERM_INIT>.
519 694
520=back 695=back
521 696
522=head2 Functions in the C<urxvt> Package 697=head2 Functions in the C<urxvt> Package
523 698
537 712
538Using this function has the advantage that its output ends up in the 713Using this function has the advantage that its output ends up in the
539correct place, e.g. on stderr of the connecting urxvtc client. 714correct place, e.g. on stderr of the connecting urxvtc client.
540 715
541Messages have a size limit of 1023 bytes currently. 716Messages have a size limit of 1023 bytes currently.
717
718=item @terms = urxvt::termlist
719
720Returns all urxvt::term objects that exist in this process, regardless of
721wether they are started, being destroyed etc., so be careful. Only term
722objects that have perl extensions attached will be returned (because there
723is no urxvt::term objet associated with others).
542 724
543=item $time = urxvt::NOW 725=item $time = urxvt::NOW
544 726
545Returns the "current time" (as per the event loop). 727Returns the "current time" (as per the event loop).
546 728
604Return the foreground/background colour index, respectively. 786Return the foreground/background colour index, respectively.
605 787
606=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour 788=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
607 789
608=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour 790=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
791
792=item $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
609 793
610Replace the foreground/background colour in the rendition mask with the 794Replace the foreground/background colour in the rendition mask with the
611specified one. 795specified one.
612 796
613=item $value = urxvt::GET_CUSTOM $rend 797=item $value = urxvt::GET_CUSTOM $rend
632 unless $msg =~ /\n$/; 816 unless $msg =~ /\n$/;
633 urxvt::warn ($msg); 817 urxvt::warn ($msg);
634 }; 818 };
635} 819}
636 820
821no warnings 'utf8';
822
637my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 823my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
638 824
639sub verbose { 825sub verbose {
640 my ($level, $msg) = @_; 826 my ($level, $msg) = @_;
641 warn "$msg\n" if $level <= $verbosity; 827 warn "$msg\n" if $level <= $verbosity;
644my %extension_pkg; 830my %extension_pkg;
645 831
646# load a single script into its own package, once only 832# load a single script into its own package, once only
647sub extension_package($) { 833sub extension_package($) {
648 my ($path) = @_; 834 my ($path) = @_;
649
650 no strict 'refs';
651 835
652 $extension_pkg{$path} ||= do { 836 $extension_pkg{$path} ||= do {
653 $path =~ /([^\/\\]+)$/; 837 $path =~ /([^\/\\]+)$/;
654 my $pkg = $1; 838 my $pkg = $1;
655 $pkg =~ s/[^[:word:]]/_/g; 839 $pkg =~ s/[^[:word:]]/_/g;
658 verbose 3, "loading extension '$path' into package '$pkg'"; 842 verbose 3, "loading extension '$path' into package '$pkg'";
659 843
660 open my $fh, "<:raw", $path 844 open my $fh, "<:raw", $path
661 or die "$path: $!"; 845 or die "$path: $!";
662 846
663 @{"$pkg\::ISA"} = urxvt::term::extension::;
664
665 my $source = 847 my $source =
666 "package $pkg; use strict; use utf8;\n" 848 "package $pkg; use strict; use utf8; no warnings 'utf8';\n"
667 . "#line 1 \"$path\"\n{\n" 849 . "#line 1 \"$path\"\n{\n"
668 . (do { local $/; <$fh> }) 850 . (do { local $/; <$fh> })
669 . "\n};\n1"; 851 . "\n};\n1";
670 852
671 eval $source 853 eval $source
685 if ($htype == 0) { # INIT 867 if ($htype == 0) { # INIT
686 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 868 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
687 869
688 my %ext_arg; 870 my %ext_arg;
689 871
872 {
873 my @init = @TERM_INIT;
874 @TERM_INIT = ();
875 $_->($TERM) for @init;
876 my @pkg = @TERM_EXT;
877 @TERM_EXT = ();
878 $TERM->register_package ($_) for @pkg;
879 }
880
690 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) { 881 for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
691 if ($_ eq "default") { 882 if ($_ eq "default") {
692 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback); 883 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback readline);
693 } elsif (/^-(.*)$/) { 884 } elsif (/^-(.*)$/) {
694 delete $ext_arg{$1}; 885 delete $ext_arg{$1};
695 } elsif (/^([^<]+)<(.*)>$/) { 886 } elsif (/^([^<]+)<(.*)>$/) {
696 push @{ $ext_arg{$1} }, $2; 887 push @{ $ext_arg{$1} }, $2;
697 } else { 888 } else {
698 $ext_arg{$_} ||= []; 889 $ext_arg{$_} ||= [];
699 } 890 }
700 } 891 }
701 892
702 while (my ($ext, $argv) = each %ext_arg) { 893 for my $ext (sort keys %ext_arg) {
703 my @files = grep -f $_, map "$_/$ext", @dirs; 894 my @files = grep -f $_, map "$_/$ext", @dirs;
704 895
705 if (@files) { 896 if (@files) {
706 $TERM->register_package (extension_package $files[0], $argv); 897 $TERM->register_package (extension_package $files[0], $ext_arg{$ext});
707 } else { 898 } else {
708 warn "perl extension '$ext' not found in perl library search path\n"; 899 warn "perl extension '$ext' not found in perl library search path\n";
709 } 900 }
710 } 901 }
711 902
717 908
718 if (my $cb = $TERM->{_hook}[$htype]) { 909 if (my $cb = $TERM->{_hook}[$htype]) {
719 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")" 910 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
720 if $verbosity >= 10; 911 if $verbosity >= 10;
721 912
722 keys %$cb; 913 for my $pkg (keys %$cb) {
723
724 while (my ($pkg, $cb) = each %$cb) {
725 $retval = eval { $cb->($TERM->{_pkg}{$pkg}, @_) } 914 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg}, @_) };
726 and last; 915 $retval ||= $retval_;
727 916
728 if ($@) { 917 if ($@) {
729 $TERM->ungrab; # better to lose the grab than the session 918 $TERM->ungrab; # better to lose the grab than the session
730 warn $@; 919 warn $@;
731 } 920 }
744 } 933 }
745 934
746 $retval 935 $retval
747} 936}
748 937
749sub exec_async(@) { 938sub SET_COLOR($$$) {
750 my $pid = fork; 939 SET_BGCOLOR (SET_FGCOLOR ($_[0], $_[1]), $_[2])
751
752 return
753 if !defined $pid or $pid;
754
755 %ENV = %{ $TERM->env };
756
757 exec @_;
758 _exit 255;
759} 940}
760 941
761# urxvt::term::extension 942# urxvt::term::extension
762 943
763package urxvt::term::extension; 944package urxvt::term::extension;
902# find on_xxx subs in the package and register them 1083# find on_xxx subs in the package and register them
903# as hooks 1084# as hooks
904sub register_package { 1085sub register_package {
905 my ($self, $pkg, $argv) = @_; 1086 my ($self, $pkg, $argv) = @_;
906 1087
1088 no strict 'refs';
1089
1090 urxvt::verbose 6, "register package $pkg to $self";
1091
1092 @{"$pkg\::ISA"} = urxvt::term::extension::;
1093
907 my $proxy = bless { 1094 my $proxy = bless {
908 _pkg => $pkg, 1095 _pkg => $pkg,
909 argv => $argv, 1096 argv => $argv,
910 }, $pkg; 1097 }, $pkg;
911 Scalar::Util::weaken ($proxy->{term} = $self); 1098 Scalar::Util::weaken ($proxy->{term} = $self);
926hash which defines the environment of the new terminal. 1113hash which defines the environment of the new terminal.
927 1114
928Croaks (and probably outputs an error message) if the new instance 1115Croaks (and probably outputs an error message) if the new instance
929couldn't be created. Returns C<undef> if the new instance didn't 1116couldn't be created. Returns C<undef> if the new instance didn't
930initialise perl, and the terminal object otherwise. The C<init> and 1117initialise perl, and the terminal object otherwise. The C<init> and
931C<start> hooks will be called during this call. 1118C<start> hooks will be called before this call returns, and are free to
1119refer to global data (which is race free).
932 1120
933=cut 1121=cut
934 1122
935sub new { 1123sub new {
936 my ($class, $env, @args) = @_; 1124 my ($class, $env, @args) = @_;
937 1125
1126 $env or Carp::croak "environment hash missing in call to urxvt::term->new";
1127 @args or Carp::croak "name argument missing in call to urxvt::term->new";
1128
938 _new ([ map "$_=$env->{$_}", keys %$env ], @args); 1129 _new ([ map "$_=$env->{$_}", keys %$env ], \@args);
939} 1130}
940 1131
941=item $term->destroy 1132=item $term->destroy
942 1133
943Destroy the terminal object (close the window, free resources 1134Destroy the terminal object (close the window, free resources
944etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event 1135etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event
945watchers (timers, io watchers) are still active. 1136watchers (timers, io watchers) are still active.
1137
1138=item $term->exec_async ($cmd[, @args])
1139
1140Works like the combination of the C<fork>/C<exec> builtins, which executes
1141("starts") programs in the background. This function takes care of setting
1142the user environment before exec'ing the command (e.g. C<PATH>) and should
1143be preferred over explicit calls to C<exec> or C<system>.
1144
1145Returns the pid of the subprocess or C<undef> on error.
1146
1147=cut
1148
1149sub exec_async {
1150 my $self = shift;
1151
1152 my $pid = fork;
1153
1154 return $pid
1155 if !defined $pid or $pid;
1156
1157 %ENV = %{ $self->env };
1158
1159 exec @_;
1160 urxvt::_exit 255;
1161}
946 1162
947=item $isset = $term->option ($optval[, $set]) 1163=item $isset = $term->option ($optval[, $set])
948 1164
949Returns true if the option specified by C<$optval> is enabled, and 1165Returns true if the option specified by C<$optval> is enabled, and
950optionally change it. All option values are stored by name in the hash 1166optionally change it. All option values are stored by name in the hash
1175 1391
1176Normally its not a good idea to use this function, as programs might be 1392Normally its not a good idea to use this function, as programs might be
1177confused by changes in cursor position or scrolling. Its useful inside a 1393confused by changes in cursor position or scrolling. Its useful inside a
1178C<on_add_lines> hook, though. 1394C<on_add_lines> hook, though.
1179 1395
1396=item $term->scr_change_screen ($screen)
1397
1398Switch to given screen - 0 primary, 1 secondary.
1399
1180=item $term->cmd_parse ($octets) 1400=item $term->cmd_parse ($octets)
1181 1401
1182Similar to C<scr_add_lines>, but the argument must be in the 1402Similar to C<scr_add_lines>, but the argument must be in the
1183locale-specific encoding of the terminal and can contain command sequences 1403locale-specific encoding of the terminal and can contain command sequences
1184(escape codes) that will be interpreted. 1404(escape codes) that will be interpreted.
1194Replaces the event mask of the pty watcher by the given event mask. Can 1414Replaces the event mask of the pty watcher by the given event mask. Can
1195be used to suppress input and output handling to the pty/tty. See the 1415be used to suppress input and output handling to the pty/tty. See the
1196description of C<< urxvt::timer->events >>. Make sure to always restore 1416description of C<< urxvt::timer->events >>. Make sure to always restore
1197the previous value. 1417the previous value.
1198 1418
1419=item $fd = $term->pty_fd
1420
1421Returns the master file descriptor for the pty in use, or C<-1> if no pty
1422is used.
1423
1199=item $windowid = $term->parent 1424=item $windowid = $term->parent
1200 1425
1201Return the window id of the toplevel window. 1426Return the window id of the toplevel window.
1202 1427
1203=item $windowid = $term->vt 1428=item $windowid = $term->vt
1209Adds the specified events to the vt event mask. Useful e.g. when you want 1434Adds the specified events to the vt event mask. Useful e.g. when you want
1210to receive pointer events all the times: 1435to receive pointer events all the times:
1211 1436
1212 $term->vt_emask_add (urxvt::PointerMotionMask); 1437 $term->vt_emask_add (urxvt::PointerMotionMask);
1213 1438
1439=item $term->focus_in
1440
1441=item $term->focus_out
1442
1443=item $term->key_press ($state, $keycode[, $time])
1444
1445=item $term->key_release ($state, $keycode[, $time])
1446
1447Deliver various fake events to to terminal.
1448
1214=item $window_width = $term->width 1449=item $window_width = $term->width
1215 1450
1216=item $window_height = $term->height 1451=item $window_height = $term->height
1217 1452
1218=item $font_width = $term->fwidth 1453=item $font_width = $term->fwidth
1248=item $env = $term->env 1483=item $env = $term->env
1249 1484
1250Returns a copy of the environment in effect for the terminal as a hashref 1485Returns a copy of the environment in effect for the terminal as a hashref
1251similar to C<\%ENV>. 1486similar to C<\%ENV>.
1252 1487
1488=item @envv = $term->envv
1489
1490Returns the environment as array of strings of the form C<VAR=VALUE>.
1491
1492=item @argv = $term->argv
1493
1494Return the argument vector as this terminal, similar to @ARGV, but
1495includes the program name as first element.
1496
1253=cut 1497=cut
1254 1498
1255sub env { 1499sub env {
1256 if (my $env = $_[0]->_env) {
1257 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env } 1500 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), $_[0]->envv }
1258 } else {
1259 +{ %ENV }
1260 }
1261} 1501}
1262 1502
1263=item $modifiermask = $term->ModLevel3Mask 1503=item $modifiermask = $term->ModLevel3Mask
1264 1504
1265=item $modifiermask = $term->ModMetaMask 1505=item $modifiermask = $term->ModMetaMask
1266 1506
1267=item $modifiermask = $term->ModNumLockMask 1507=item $modifiermask = $term->ModNumLockMask
1268 1508
1269Return the modifier masks corresponding to the "ISO Level 3 Shift" (often 1509Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
1270AltGr), the meta key (often Alt) and the num lock key, if applicable. 1510AltGr), the meta key (often Alt) and the num lock key, if applicable.
1511
1512=item $screen = $term->current_screen
1513
1514Returns the currently displayed screen (0 primary, 1 secondary).
1515
1516=item $cursor_is_hidden = $term->hidden_cursor
1517
1518Returns wether the cursor is currently hidden or not.
1271 1519
1272=item $view_start = $term->view_start ([$newvalue]) 1520=item $view_start = $term->view_start ([$newvalue])
1273 1521
1274Returns the row number of the topmost displayed line. Maximum value is 1522Returns the row number of the topmost displayed line. Maximum value is
1275C<0>, which displays the normal terminal contents. Lower values scroll 1523C<0>, which displays the normal terminal contents. Lower values scroll
1295line, starting at column C<$start_col> (default C<0>), which is useful 1543line, starting at column C<$start_col> (default C<0>), which is useful
1296to replace only parts of a line. The font index in the rendition will 1544to replace only parts of a line. The font index in the rendition will
1297automatically be updated. 1545automatically be updated.
1298 1546
1299C<$text> is in a special encoding: tabs and wide characters that use more 1547C<$text> is in a special encoding: tabs and wide characters that use more
1300than one cell when displayed are padded with urxvt::NOCHAR characters 1548than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535)
1301(C<chr 65535>). Characters with combining characters and other characters 1549characters. Characters with combining characters and other characters that
1302that do not fit into the normal tetx encoding will be replaced with 1550do not fit into the normal tetx encoding will be replaced with characters
1303characters in the private use area. 1551in the private use area.
1304 1552
1305You have to obey this encoding when changing text. The advantage is 1553You have to obey this encoding when changing text. The advantage is
1306that C<substr> and similar functions work on screen cells and not on 1554that C<substr> and similar functions work on screen cells and not on
1307characters. 1555characters.
1308 1556
1455=item $string = $term->special_decode $text 1703=item $string = $term->special_decode $text
1456 1704
1457Converts rxvt-unicodes text reprsentation into a perl string. See 1705Converts rxvt-unicodes text reprsentation into a perl string. See
1458C<< $term->ROW_t >> for details. 1706C<< $term->ROW_t >> for details.
1459 1707
1460=item $success = $term->grab_button ($button, $modifiermask) 1708=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1461 1709
1710=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1711
1462Registers a synchronous button grab. See the XGrabButton manpage. 1712Register/unregister a synchronous button grab. See the XGrabButton
1713manpage.
1463 1714
1464=item $success = $term->grab ($eventtime[, $sync]) 1715=item $success = $term->grab ($eventtime[, $sync])
1465 1716
1466Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1717Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1467synchronous (C<$sync> is true). Also remembers the grab timestampe. 1718synchronous (C<$sync> is true). Also remembers the grab timestampe.
1482=item $term->ungrab 1733=item $term->ungrab
1483 1734
1484Calls XUngrab for the most recent grab. Is called automatically on 1735Calls XUngrab for the most recent grab. Is called automatically on
1485evaluation errors, as it is better to lose the grab in the error case as 1736evaluation errors, as it is better to lose the grab in the error case as
1486the session. 1737the session.
1738
1739=item $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
1740
1741=item $atom_name = $term->XGetAtomName ($atom)
1742
1743=item @atoms = $term->XListProperties ($window)
1744
1745=item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
1746
1747=item $term->XChangeWindowProperty ($window, $property, $type, $format, $octets)
1748
1749=item $term->XDeleteProperty ($window, $property)
1750
1751=item $window = $term->DefaultRootWindow
1752
1753=item $term->XReparentWindow ($window, $parent, [$x, $y])
1754
1755=item $term->XMapWindow ($window)
1756
1757=item $term->XUnmapWindow ($window)
1758
1759=item $term->XMoveResizeWindow ($window, $x, $y, $width, $height)
1760
1761=item ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x, $y)
1762
1763=item $term->XChangeInput ($window, $add_events[, $del_events])
1764
1765Various X or X-related functions. The C<$term> object only serves as
1766the source of the display, otherwise those functions map more-or-less
1767directory onto the X functions of the same name.
1487 1768
1488=back 1769=back
1489 1770
1490=cut 1771=cut
1491 1772
1555 my ($self, $text, $cb) = @_; 1836 my ($self, $text, $cb) = @_;
1556 1837
1557 $self->add_item ({ type => "button", text => $text, activate => $cb}); 1838 $self->add_item ({ type => "button", text => $text, activate => $cb});
1558} 1839}
1559 1840
1560=item $popup->add_toggle ($text, $cb, $initial_value) 1841=item $popup->add_toggle ($text, $initial_value, $cb)
1561 1842
1562Adds a toggle/checkbox item to the popup. Teh callback gets called 1843Adds a toggle/checkbox item to the popup. The callback gets called
1563whenever it gets toggled, with a boolean indicating its value as its first 1844whenever it gets toggled, with a boolean indicating its new value as its
1564argument. 1845first argument.
1565 1846
1566=cut 1847=cut
1567 1848
1568sub add_toggle { 1849sub add_toggle {
1569 my ($self, $text, $cb, $value) = @_; 1850 my ($self, $text, $value, $cb) = @_;
1570 1851
1571 my $item; $item = { 1852 my $item; $item = {
1572 type => "button", 1853 type => "button",
1573 text => " $text", 1854 text => " $text",
1574 value => $value, 1855 value => $value,
1611 delete $self->{term}{_destroy}{$self}; 1892 delete $self->{term}{_destroy}{$self};
1612 $self->{term}->ungrab; 1893 $self->{term}->ungrab;
1613} 1894}
1614 1895
1615=back 1896=back
1897
1898=cut
1899
1900package urxvt::watcher;
1901
1902@urxvt::timer::ISA = __PACKAGE__;
1903@urxvt::iow::ISA = __PACKAGE__;
1904@urxvt::pw::ISA = __PACKAGE__;
1905@urxvt::iw::ISA = __PACKAGE__;
1616 1906
1617=head2 The C<urxvt::timer> Class 1907=head2 The C<urxvt::timer> Class
1618 1908
1619This class implements timer watchers/events. Time is represented as a 1909This class implements timer watchers/events. Time is represented as a
1620fractional number of seconds since the epoch. Example: 1910fractional number of seconds since the epoch. Example:
1718 2008
1719Stop watching for events on the given filehandle. 2009Stop watching for events on the given filehandle.
1720 2010
1721=back 2011=back
1722 2012
2013=head2 The C<urxvt::iw> Class
2014
2015This class implements idle watchers, that get called automatically when
2016the process is idle. They should return as fast as possible, after doing
2017some useful work.
2018
2019=over 4
2020
2021=item $iw = new urxvt::iw
2022
2023Create a new idle watcher object in stopped state.
2024
2025=item $iw = $iw->cb (sub { my ($iw) = @_; ... })
2026
2027Set the callback to be called when the watcher triggers.
2028
2029=item $timer = $timer->start
2030
2031Start the watcher.
2032
2033=item $timer = $timer->stop
2034
2035Stop the watcher.
2036
2037=back
2038
2039=head2 The C<urxvt::pw> Class
2040
2041This class implements process watchers. They create an event whenever a
2042process exits, after which they stop automatically.
2043
2044 my $pid = fork;
2045 ...
2046 $term->{pw} = urxvt::pw
2047 ->new
2048 ->start ($pid)
2049 ->cb (sub {
2050 my ($pw, $exit_status) = @_;
2051 ...
2052 });
2053
2054=over 4
2055
2056=item $pw = new urxvt::pw
2057
2058Create a new process watcher in stopped state.
2059
2060=item $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
2061
2062Set the callback to be called when the timer triggers.
2063
2064=item $pw = $timer->start ($pid)
2065
2066Tells the wqtcher to start watching for process C<$pid>.
2067
2068=item $pw = $pw->stop
2069
2070Stop the watcher.
2071
2072=back
2073
1723=head1 ENVIRONMENT 2074=head1 ENVIRONMENT
1724 2075
1725=head2 URXVT_PERL_VERBOSITY 2076=head2 URXVT_PERL_VERBOSITY
1726 2077
1727This variable controls the verbosity level of the perl extension. Higher 2078This variable controls the verbosity level of the perl extension. Higher

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines