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.124 by root, Sun Jan 22 11:57:06 2006 UTC vs.
Revision 1.146 by root, Thu Aug 17 21:56:11 2006 UTC

17 17
18 @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test 18 @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test
19 19
20=head1 DESCRIPTION 20=head1 DESCRIPTION
21 21
22Everytime a terminal object gets created, extension scripts specified via 22Every time a terminal object gets created, extension scripts specified via
23the C<perl> resource are loaded and associated with it. 23the C<perl> resource are loaded and associated with it.
24 24
25Scripts are compiled in a 'use strict' and 'use utf8' environment, and 25Scripts are compiled in a 'use strict' and 'use utf8' environment, and
26thus must be encoded as UTF-8. 26thus must be encoded as UTF-8.
27 27
62 URxvt.selection.pattern-1: perl-regex 62 URxvt.selection.pattern-1: perl-regex
63 ... 63 ...
64 64
65The index number (0, 1...) must not have any holes, and each regex must 65The index number (0, 1...) must not have any holes, and each regex must
66contain at least one pair of capturing parentheses, which will be used for 66contain at least one pair of capturing parentheses, which will be used for
67the match. For example, the followign adds a regex that matches everything 67the match. For example, the following adds a regex that matches everything
68between two vertical bars: 68between two vertical bars:
69 69
70 URxvt.selection.pattern-0: \\|([^|]+)\\| 70 URxvt.selection.pattern-0: \\|([^|]+)\\|
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: ^(/[^:]+):\
71 78
72You 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
73interesting uses, such as parsing a line from beginning to end. 80interesting uses, such as parsing a line from beginning to end.
74 81
75This extension also offers following bindable keyboard commands: 82This extension also offers following bindable keyboard commands:
86 93
87=item option-popup (enabled by default) 94=item option-popup (enabled by default)
88 95
89Binds 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
90runtime. 97runtime.
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 };
91 115
92=item selection-popup (enabled by default) 116=item selection-popup (enabled by default)
93 117
94Binds 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
95text into various other formats/action (such as uri unescaping, perl 119text into various other formats/action (such as uri unescaping, perl
96evaluation, web-browser starting etc.), depending on content. 120evaluation, web-browser starting etc.), depending on content.
97 121
98Other extensions can extend this popup menu by pushing a code reference 122Other extensions can extend this popup menu by pushing a code reference
99onto C<@{ $term->{selection_popup_hook} }>, that is called whenever the 123onto C<@{ $term->{selection_popup_hook} }>, which gets called whenever the
100popup is displayed. 124popup is being displayed.
101 125
102It'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
103is in C<$_>, which can be used to decide wether to add something or not. 127is in C<$_>, which can be used to decide whether to add something or not.
104It 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
105string 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
106when the button gets activated and should transform C<$_>. 130when the button gets activated and should transform C<$_>.
107 131
108The 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
127bottom. 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
128was 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
129additionally stores the first match in the current line into the primary 153additionally stores the first match in the current line into the primary
130selection. 154selection.
131 155
156The regex defaults to "(?i)", resulting in a case-insensitive search. To
157get a case-sensitive search you can delete this prefix using C<BackSpace>
158or simply use an uppercase character which removes the "(?i)" prefix.
159
160See L<perlre> for more info about perl regular expression syntax.
161
132=item readline (enabled by default) 162=item readline (enabled by default)
133 163
134A support package that tries to make editing with readline easier. At the 164A support package that tries to make editing with readline easier. At
135moment, it reacts to clicking with the left mouse button by trying to 165the moment, it reacts to clicking shift-left mouse button by trying to
136move the text cursor to this position. It does so by generating as many 166move the text cursor to this position. It does so by generating as many
137cursor-left or cursor-right keypresses as required (the this only works 167cursor-left or cursor-right keypresses as required (the this only works
138for programs that correctly support wide characters). 168for programs that correctly support wide characters).
139 169
140To avoid too many false positives, this is only done when: 170To avoid too many false positives, this is only done when:
141 171
142=over 4 172=over 4
143 173
174=item - the tty is in ICANON state.
175
176=item - the text cursor is visible.
177
178=item - the primary screen is currently being displayed.
179
144=item - the mouse is on the same (multi-row-) line as the text cursor. 180=item - the mouse is on the same (multi-row-) line as the text cursor.
145
146=item - the primary screen is currently being displayed.
147
148=item - the text cursor is visible.
149 181
150=back 182=back
151 183
152The normal selection mechanism isn't disabled, so quick successive clicks 184The normal selection mechanism isn't disabled, so quick successive clicks
153might interfere with selection creation in harmless ways. 185might interfere with selection creation in harmless ways.
188the message into vi commands to load the file. 220the message into vi commands to load the file.
189 221
190=item tabbed 222=item tabbed
191 223
192This transforms the terminal into a tabbar with additional terminals, that 224This transforms the terminal into a tabbar with additional terminals, that
193is, it implements what is commonly refered to as "tabbed terminal". The topmost line 225is, it implements what is commonly referred to as "tabbed terminal". The topmost line
194displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one 226displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one
195button per tab. 227button per tab.
196 228
197Clicking a button will activate that tab. Pressing B<Shift-Left> and 229Clicking a button will activate that tab. Pressing B<Shift-Left> and
198B<Shift-Right> will switch to the tab left or right of the current one, 230B<Shift-Right> will switch to the tab left or right of the current one,
199while B<Shift-Down> creates a new tab. 231while B<Shift-Down> creates a new tab.
232
233The tabbar itself can be configured similarly to a normal terminal, but
234with a resource class of C<URxvt.tabbed>. In addition, it supports the
235following four resources (shown with defaults):
236
237 URxvt.tabbed.tabbar-fg: <colour-index, default 3>
238 URxvt.tabbed.tabbar-bg: <colour-index, default 0>
239 URxvt.tabbed.tab-fg: <colour-index, default 0>
240 URxvt.tabbed.tab-bg: <colour-index, default 1>
241
242See I<COLOR AND GRAPHICS> in the @@RXVT_NAME@@(1) manpage for valid
243indices.
200 244
201=item mark-urls 245=item mark-urls
202 246
203Uses per-line display filtering (C<on_line_update>) to underline urls and 247Uses per-line display filtering (C<on_line_update>) to underline urls and
204make them clickable. When middle-clicked, the program specified in the 248make them clickable. When middle-clicked, the program specified in the
205resource C<urlLauncher> (default C<x-www-browser>) will be started with 249resource C<urlLauncher> (default C<x-www-browser>) will be started with
206the URL as first argument. 250the URL as first argument.
207 251
252=item xim-onthespot
253
254This (experimental) perl extension implements OnTheSpot editing. It does
255not work perfectly, and some input methods don't seem to work well with
256OnTheSpot editing in general, but it seems to work at leats for SCIM and
257kinput2.
258
259You enable it by specifying this extension and a preedit style of
260C<OnTheSpot>, i.e.:
261
262 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot
263
264=item kuake<hotkey>
265
266A very primitive quake-console-like extension. It was inspired by a
267description of how the programs C<kuake> and C<yakuake> work: Whenever the
268user presses a global accelerator key (by default C<F10>), the terminal
269will show or hide itself. Another press of the accelerator key will hide
270or show it again.
271
272Initially, the window will not be shown when using this extension.
273
274This is useful if you need a single terminal thats not using any desktop
275space most of the time but is quickly available at the press of a key.
276
277The accelerator key is grabbed regardless of any modifiers, so this
278extension will actually grab a physical key just for this function.
279
280If you want a quake-like animation, tell your window manager to do so
281(fvwm can do it).
282
208=item automove-background 283=item automove-background
209 284
210This is basically a one-line extension that dynamically changes the background pixmap offset 285This is basically a very small extension that dynamically changes the
211to the window position, in effect creating the same effect as pseudo transparency with 286background pixmap offset to the window position, in effect creating the
212a custom pixmap. No scaling is supported in this mode. Exmaple: 287same effect as pseudo transparency with a custom pixmap. No scaling is
288supported in this mode. Example:
213 289
214 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background 290 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background
215 291
216=item block-graphics-to-ascii 292=item block-graphics-to-ascii
217 293
218A not very useful example of filtering all text output to the terminal, 294A not very useful example of filtering all text output to the terminal
219by replacing all line-drawing characters (U+2500 .. U+259F) by a 295by replacing all line-drawing characters (U+2500 .. U+259F) by a
220similar-looking ascii character. 296similar-looking ascii character.
221 297
222=item digital-clock 298=item digital-clock
223 299
224Displays a digital clock using the built-in overlay. 300Displays a digital clock using the built-in overlay.
225 301
226=item example-refresh-hooks 302=item remote-clipboard
227 303
228Displays a very simple digital clock in the upper right corner of the 304Somewhat of a misnomer, this extension adds two menu entries to the
229window. Illustrates overwriting the refresh callbacks to create your own 305selection popup that allows one ti run external commands to store the
230overlays or changes. 306selection somewhere and fetch it again.
307
308We use it to implement a "distributed selection mechanism", which just
309means that one command uploads the file to a remote server, and another
310reads it.
311
312The commands can be set using the C<URxvt.remote-selection.store> and
313C<URxvt.remote-selection.fetch> resources. The first should read the
314selection to store from STDIN (always in UTF-8), the second should provide
315the selection data on STDOUT (also in UTF-8).
316
317The defaults (which are likely useless to you) use rsh and cat:
318
319 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
320 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
231 321
232=item selection-pastebin 322=item selection-pastebin
233 323
234This is a little rarely useful extension that Uploads the selection as 324This is a little rarely useful extension that Uploads the selection as
235textfile to a remote site (or does other things). (The implementation is 325textfile to a remote site (or does other things). (The implementation is
255After a successful upload the selection will be replaced by the text given 345After a successful upload the selection will be replaced by the text given
256in the C<selection-pastebin-url> resource (again, the % is the placeholder 346in the C<selection-pastebin-url> resource (again, the % is the placeholder
257for the filename): 347for the filename):
258 348
259 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/% 349 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
350
351I<Note to xrdb users:> xrdb uses the C preprocessor, which might interpret
352the double C</> characters as comment start. Use C<\057\057> instead,
353which works regardless of wether xrdb is used to parse the resource file
354or not.
355
356=item example-refresh-hooks
357
358Displays a very simple digital clock in the upper right corner of the
359window. Illustrates overwriting the refresh callbacks to create your own
360overlays or changes.
260 361
261=back 362=back
262 363
263=head1 API DOCUMENTATION 364=head1 API DOCUMENTATION
264 365
298 399
299=back 400=back
300 401
301=head2 Extension Objects 402=head2 Extension Objects
302 403
303Very perl extension is a perl class. A separate perl object is created 404Every perl extension is a perl class. A separate perl object is created
304for each terminal and each extension and passed as the first parameter to 405for each terminal, and each terminal has its own set of extenion objects,
305hooks. So extensions can use their C<$self> object without having to think 406which are passed as the first parameter to hooks. So extensions can use
306about other extensions, with the exception of methods and members that 407their C<$self> object without having to think about clashes with other
408extensions or other terminals, with the exception of methods and members
307begin with an underscore character C<_>: these are reserved for internal 409that begin with an underscore character C<_>: these are reserved for
308use. 410internal use.
309 411
310Although it isn't a C<urxvt::term> object, you can call all methods of the 412Although it isn't a C<urxvt::term> object, you can call all methods of the
311C<urxvt::term> class on this object. 413C<urxvt::term> class on this object.
312 414
313It has the following methods and data members: 415It has the following methods and data members:
334=head2 Hooks 436=head2 Hooks
335 437
336The following subroutines can be declared in extension files, and will be 438The following subroutines can be declared in extension files, and will be
337called whenever the relevant event happens. 439called whenever the relevant event happens.
338 440
339The first argument passed to them is an extension oject as described in 441The first argument passed to them is an extension object as described in
340the in the C<Extension Objects> section. 442the in the C<Extension Objects> section.
341 443
342B<All> of these hooks must return a boolean value. If any of the called 444B<All> of these hooks must return a boolean value. If any of the called
343hooks returns true, then the event counts as being I<consumed>, and the 445hooks returns true, then the event counts as being I<consumed>, and the
344relevant action might not be carried out by the C++ code. 446relevant action might not be carried out by the C++ code.
357place. 459place.
358 460
359=item on_start $term 461=item on_start $term
360 462
361Called at the very end of initialisation of a new terminal, just before 463Called at the very end of initialisation of a new terminal, just before
362trying to map (display) the toplevel and returning to the mainloop. 464trying to map (display) the toplevel and returning to the main loop.
363 465
364=item on_destroy $term 466=item on_destroy $term
365 467
366Called whenever something tries to destroy terminal, before doing anything 468Called whenever something tries to destroy terminal, when the terminal is
367yet. If this hook returns true, then destruction is skipped, but this is 469still fully functional (not for long, though).
368rarely a good idea.
369 470
370=item on_reset $term 471=item on_reset $term
371 472
372Called after the screen is "reset" for any reason, such as resizing or 473Called after the screen is "reset" for any reason, such as resizing or
373control sequences. Here is where you can react on changes to size-related 474control sequences. Here is where you can react on changes to size-related
395 496
396Called whenever a selection has been copied, but before the selection is 497Called whenever a selection has been copied, but before the selection is
397requested from the server. The selection text can be queried and changed 498requested from the server. The selection text can be queried and changed
398by calling C<< $term->selection >>. 499by calling C<< $term->selection >>.
399 500
400Returning a true value aborts selection grabbing. It will still be hilighted. 501Returning a true value aborts selection grabbing. It will still be highlighted.
401 502
402=item on_sel_extend $term 503=item on_sel_extend $term
403 504
404Called whenever the user tries to extend the selection (e.g. with a double 505Called whenever the user tries to extend the selection (e.g. with a double
405click) and is either supposed to return false (normal operation), or 506click) and is either supposed to return false (normal operation), or
406should extend the selection itelf and return true to suppress the built-in 507should extend the selection itself and return true to suppress the built-in
407processing. This can happen multiple times, as long as the callback 508processing. This can happen multiple times, as long as the callback
408returns true, it will be called on every further click by the user and is 509returns true, it will be called on every further click by the user and is
409supposed to enlarge the selection more and more, if possible. 510supposed to enlarge the selection more and more, if possible.
410 511
411See the F<selection> example extension. 512See the F<selection> example extension.
412 513
413=item on_view_change $term, $offset 514=item on_view_change $term, $offset
414 515
415Called whenever the view offset changes, i..e the user or program 516Called whenever the view offset changes, i.e. the user or program
416scrolls. Offset C<0> means display the normal terminal, positive values 517scrolls. Offset C<0> means display the normal terminal, positive values
417show this many lines of scrollback. 518show this many lines of scrollback.
418 519
419=item on_scroll_back $term, $lines, $saved 520=item on_scroll_back $term, $lines, $saved
420 521
424 525
425It is called before lines are scrolled out (so rows 0 .. min ($lines - 1, 526It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
426$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total 527$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
427number of lines that will be in the scrollback buffer. 528number of lines that will be in the scrollback buffer.
428 529
530=item on_osc_seq $term, $op, $args
531
532Called on every OSC sequence and can be used to suppress it or modify its
533behaviour. The default should be to return an empty list. A true value
534suppresses execution of the request completely. Make sure you don't get
535confused by recursive invocations when you output an osc sequence within
536this callback.
537
538C<on_osc_seq_perl> should be used for new behaviour.
539
429=item on_osc_seq $term, $string 540=item on_osc_seq_perl $term, $string
430 541
431Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 542Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
432operating system command) is processed. Cursor position and other state 543operating system command) is processed. Cursor position and other state
433information is up-to-date when this happens. For interoperability, the 544information is up-to-date when this happens. For interoperability, the
434string should start with the extension name and a colon, to distinguish 545string should start with the extension name and a colon, to distinguish
435it from commands for other extensions, and this might be enforced in the 546it from commands for other extensions, and this might be enforced in the
436future. 547future.
437 548
438Be careful not ever to trust (in a security sense) the data you receive, 549Be careful not ever to trust (in a security sense) the data you receive,
439as its source can not easily be controleld (e-mail content, messages from 550as its source can not easily be controlled (e-mail content, messages from
440other users on the same system etc.). 551other users on the same system etc.).
441 552
442=item on_add_lines $term, $string 553=item on_add_lines $term, $string
443 554
444Called whenever text is about to be output, with the text as argument. You 555Called whenever text is about to be output, with the text as argument. You
475 586
476=item on_refresh_end $term 587=item on_refresh_end $term
477 588
478Called just after the screen gets redrawn. See C<on_refresh_begin>. 589Called just after the screen gets redrawn. See C<on_refresh_begin>.
479 590
480=item on_keyboard_command $term, $string 591=item on_user_command $term, $string
481 592
482Called whenever the user presses a key combination that has a 593Called whenever a user-configured event is being activated (e.g. via
483C<perl:string> action bound to it (see description of the B<keysym> 594a C<perl:string> action bound to a key, see description of the B<keysym>
484resource in the @@RXVT_NAME@@(1) manpage). 595resource in the @@RXVT_NAME@@(1) manpage).
596
597The event is simply the action string. This interface is assumed to change
598slightly in the future.
599
600=item on_resize_all_windows $tern, $new_width, $new_height
601
602Called just after the new window size has been calculated, but before
603windows are actually being resized or hints are being set. If this hook
604returns TRUE, setting of the window hints is being skipped.
485 605
486=item on_x_event $term, $event 606=item on_x_event $term, $event
487 607
488Called on every X event received on the vt window (and possibly other 608Called on every X event received on the vt window (and possibly other
489windows). Should only be used as a last resort. Most event structure 609windows). Should only be used as a last resort. Most event structure
490members are not passed. 610members are not passed.
491 611
612=item on_root_event $term, $event
613
614Like C<on_x_event>, but is called for events on the root window.
615
492=item on_focus_in $term 616=item on_focus_in $term
493 617
494Called whenever the window gets the keyboard focus, before rxvt-unicode 618Called whenever the window gets the keyboard focus, before rxvt-unicode
495does focus in processing. 619does focus in processing.
496 620
497=item on_focus_out $term 621=item on_focus_out $term
498 622
499Called wheneever the window loses keyboard focus, before rxvt-unicode does 623Called whenever the window loses keyboard focus, before rxvt-unicode does
500focus out processing. 624focus out processing.
501 625
502=item on_configure_notify $term, $event 626=item on_configure_notify $term, $event
503 627
504=item on_property_notify $term, $event 628=item on_property_notify $term, $event
587The current terminal. This variable stores the current C<urxvt::term> 711The current terminal. This variable stores the current C<urxvt::term>
588object, whenever a callback/hook is executing. 712object, whenever a callback/hook is executing.
589 713
590=item @urxvt::TERM_INIT 714=item @urxvt::TERM_INIT
591 715
592All coderefs in this array will be called as methods of the next newly 716All code references in this array will be called as methods of the next newly
593created C<urxvt::term> object (during the C<on_init> phase). The array 717created C<urxvt::term> object (during the C<on_init> phase). The array
594gets cleared before the codereferences that were in it are being executed, 718gets cleared before the code references that were in it are being executed,
595so coderefs can push themselves onto it again if they so desire. 719so references can push themselves onto it again if they so desire.
596 720
597This complements to the perl-eval commandline option, but gets executed 721This complements to the perl-eval command line option, but gets executed
598first. 722first.
599 723
600=item @urxvt::TERM_EXT 724=item @urxvt::TERM_EXT
601 725
602Works similar to C<@TERM_INIT>, but contains perl package/class names, which 726Works similar to C<@TERM_INIT>, but contains perl package/class names, which
623 747
624Using this function has the advantage that its output ends up in the 748Using this function has the advantage that its output ends up in the
625correct place, e.g. on stderr of the connecting urxvtc client. 749correct place, e.g. on stderr of the connecting urxvtc client.
626 750
627Messages have a size limit of 1023 bytes currently. 751Messages have a size limit of 1023 bytes currently.
752
753=item @terms = urxvt::termlist
754
755Returns all urxvt::term objects that exist in this process, regardless of
756whether they are started, being destroyed etc., so be careful. Only term
757objects that have perl extensions attached will be returned (because there
758is no urxvt::term objet associated with others).
628 759
629=item $time = urxvt::NOW 760=item $time = urxvt::NOW
630 761
631Returns the "current time" (as per the event loop). 762Returns the "current time" (as per the event loop).
632 763
690Return the foreground/background colour index, respectively. 821Return the foreground/background colour index, respectively.
691 822
692=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour 823=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
693 824
694=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour 825=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
826
827=item $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
695 828
696Replace the foreground/background colour in the rendition mask with the 829Replace the foreground/background colour in the rendition mask with the
697specified one. 830specified one.
698 831
699=item $value = urxvt::GET_CUSTOM $rend 832=item $value = urxvt::GET_CUSTOM $rend
790 } else { 923 } else {
791 $ext_arg{$_} ||= []; 924 $ext_arg{$_} ||= [];
792 } 925 }
793 } 926 }
794 927
795 while (my ($ext, $argv) = each %ext_arg) { 928 for my $ext (sort keys %ext_arg) {
796 my @files = grep -f $_, map "$_/$ext", @dirs; 929 my @files = grep -f $_, map "$_/$ext", @dirs;
797 930
798 if (@files) { 931 if (@files) {
799 $TERM->register_package (extension_package $files[0], $argv); 932 $TERM->register_package (extension_package $files[0], $ext_arg{$ext});
800 } else { 933 } else {
801 warn "perl extension '$ext' not found in perl library search path\n"; 934 warn "perl extension '$ext' not found in perl library search path\n";
802 } 935 }
803 } 936 }
804 937
810 943
811 if (my $cb = $TERM->{_hook}[$htype]) { 944 if (my $cb = $TERM->{_hook}[$htype]) {
812 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")" 945 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
813 if $verbosity >= 10; 946 if $verbosity >= 10;
814 947
815 keys %$cb; 948 for my $pkg (keys %$cb) {
816
817 while (my ($pkg, $cb) = each %$cb) {
818 my $retval_ = eval { $cb->($TERM->{_pkg}{$pkg}, @_) }; 949 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg}, @_) };
819 $retval ||= $retval_; 950 $retval ||= $retval_;
820 951
821 if ($@) { 952 if ($@) {
822 $TERM->ungrab; # better to lose the grab than the session 953 $TERM->ungrab; # better to lose the grab than the session
823 warn $@; 954 warn $@;
835 # clear package 966 # clear package
836 %$TERM = (); 967 %$TERM = ();
837 } 968 }
838 969
839 $retval 970 $retval
971}
972
973sub SET_COLOR($$$) {
974 SET_BGCOLOR (SET_FGCOLOR ($_[0], $_[1]), $_[2])
840} 975}
841 976
842# urxvt::term::extension 977# urxvt::term::extension
843 978
844package urxvt::term::extension; 979package urxvt::term::extension;
1013hash which defines the environment of the new terminal. 1148hash which defines the environment of the new terminal.
1014 1149
1015Croaks (and probably outputs an error message) if the new instance 1150Croaks (and probably outputs an error message) if the new instance
1016couldn't be created. Returns C<undef> if the new instance didn't 1151couldn't be created. Returns C<undef> if the new instance didn't
1017initialise perl, and the terminal object otherwise. The C<init> and 1152initialise perl, and the terminal object otherwise. The C<init> and
1018C<start> hooks will be called during this call. 1153C<start> hooks will be called before this call returns, and are free to
1154refer to global data (which is race free).
1019 1155
1020=cut 1156=cut
1021 1157
1022sub new { 1158sub new {
1023 my ($class, $env, @args) = @_; 1159 my ($class, $env, @args) = @_;
1024 1160
1161 $env or Carp::croak "environment hash missing in call to urxvt::term->new";
1162 @args or Carp::croak "name argument missing in call to urxvt::term->new";
1163
1025 _new ([ map "$_=$env->{$_}", keys %$env ], @args); 1164 _new ([ map "$_=$env->{$_}", keys %$env ], \@args);
1026} 1165}
1027 1166
1028=item $term->destroy 1167=item $term->destroy
1029 1168
1030Destroy the terminal object (close the window, free resources 1169Destroy the terminal object (close the window, free resources
1060 1199
1061Returns true if the option specified by C<$optval> is enabled, and 1200Returns true if the option specified by C<$optval> is enabled, and
1062optionally change it. All option values are stored by name in the hash 1201optionally change it. All option values are stored by name in the hash
1063C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash. 1202C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
1064 1203
1065Here is a a likely non-exhaustive list of option names, please see the 1204Here is a likely non-exhaustive list of option names, please see the
1066source file F</src/optinc.h> to see the actual list: 1205source file F</src/optinc.h> to see the actual list:
1067 1206
1068 borderLess console cursorBlink cursorUnderline hold iconic insecure 1207 borderLess console cursorBlink cursorUnderline hold iconic insecure
1069 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 1208 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
1070 override-redirect pastableTabs pointerBlank reverseVideo scrollBar 1209 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
1087likely change). 1226likely change).
1088 1227
1089Please note that resource strings will currently only be freed when the 1228Please note that resource strings will currently only be freed when the
1090terminal is destroyed, so changing options frequently will eat memory. 1229terminal is destroyed, so changing options frequently will eat memory.
1091 1230
1092Here is a a likely non-exhaustive list of resource names, not all of which 1231Here is a likely non-exhaustive list of resource names, not all of which
1093are supported in every build, please see the source file F</src/rsinc.h> 1232are supported in every build, please see the source file F</src/rsinc.h>
1094to see the actual list: 1233to see the actual list:
1095 1234
1096 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1235 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
1097 borderLess color cursorBlink cursorUnderline cutchars delete_key 1236 borderLess color cursorBlink cursorUnderline cutchars delete_key
1310Replaces the event mask of the pty watcher by the given event mask. Can 1449Replaces the event mask of the pty watcher by the given event mask. Can
1311be used to suppress input and output handling to the pty/tty. See the 1450be used to suppress input and output handling to the pty/tty. See the
1312description of C<< urxvt::timer->events >>. Make sure to always restore 1451description of C<< urxvt::timer->events >>. Make sure to always restore
1313the previous value. 1452the previous value.
1314 1453
1454=item $fd = $term->pty_fd
1455
1456Returns the master file descriptor for the pty in use, or C<-1> if no pty
1457is used.
1458
1315=item $windowid = $term->parent 1459=item $windowid = $term->parent
1316 1460
1317Return the window id of the toplevel window. 1461Return the window id of the toplevel window.
1318 1462
1319=item $windowid = $term->vt 1463=item $windowid = $term->vt
1325Adds the specified events to the vt event mask. Useful e.g. when you want 1469Adds the specified events to the vt event mask. Useful e.g. when you want
1326to receive pointer events all the times: 1470to receive pointer events all the times:
1327 1471
1328 $term->vt_emask_add (urxvt::PointerMotionMask); 1472 $term->vt_emask_add (urxvt::PointerMotionMask);
1329 1473
1474=item $term->focus_in
1475
1476=item $term->focus_out
1477
1478=item $term->key_press ($state, $keycode[, $time])
1479
1480=item $term->key_release ($state, $keycode[, $time])
1481
1482Deliver various fake events to to terminal.
1483
1330=item $window_width = $term->width 1484=item $window_width = $term->width
1331 1485
1332=item $window_height = $term->height 1486=item $window_height = $term->height
1333 1487
1334=item $font_width = $term->fwidth 1488=item $font_width = $term->fwidth
1364=item $env = $term->env 1518=item $env = $term->env
1365 1519
1366Returns a copy of the environment in effect for the terminal as a hashref 1520Returns a copy of the environment in effect for the terminal as a hashref
1367similar to C<\%ENV>. 1521similar to C<\%ENV>.
1368 1522
1523=item @envv = $term->envv
1524
1525Returns the environment as array of strings of the form C<VAR=VALUE>.
1526
1527=item @argv = $term->argv
1528
1529Return the argument vector as this terminal, similar to @ARGV, but
1530includes the program name as first element.
1531
1369=cut 1532=cut
1370 1533
1371sub env { 1534sub env {
1372 if (my $env = $_[0]->_env) {
1373 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env } 1535 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), $_[0]->envv }
1374 } else {
1375 +{ %ENV }
1376 }
1377} 1536}
1378 1537
1379=item $modifiermask = $term->ModLevel3Mask 1538=item $modifiermask = $term->ModLevel3Mask
1380 1539
1381=item $modifiermask = $term->ModMetaMask 1540=item $modifiermask = $term->ModMetaMask
1389 1548
1390Returns the currently displayed screen (0 primary, 1 secondary). 1549Returns the currently displayed screen (0 primary, 1 secondary).
1391 1550
1392=item $cursor_is_hidden = $term->hidden_cursor 1551=item $cursor_is_hidden = $term->hidden_cursor
1393 1552
1394Returns wether the cursor is currently hidden or not. 1553Returns whether the cursor is currently hidden or not.
1395 1554
1396=item $view_start = $term->view_start ([$newvalue]) 1555=item $view_start = $term->view_start ([$newvalue])
1397 1556
1398Returns the row number of the topmost displayed line. Maximum value is 1557Returns the row number of the topmost displayed line. Maximum value is
1399C<0>, which displays the normal terminal contents. Lower values scroll 1558C<0>, which displays the normal terminal contents. Lower values scroll
1576where one character corresponds to one screen cell. See 1735where one character corresponds to one screen cell. See
1577C<< $term->ROW_t >> for details. 1736C<< $term->ROW_t >> for details.
1578 1737
1579=item $string = $term->special_decode $text 1738=item $string = $term->special_decode $text
1580 1739
1581Converts rxvt-unicodes text reprsentation into a perl string. See 1740Converts rxvt-unicodes text representation into a perl string. See
1582C<< $term->ROW_t >> for details. 1741C<< $term->ROW_t >> for details.
1583 1742
1584=item $success = $term->grab_button ($button, $modifiermask) 1743=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1585 1744
1745=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1746
1586Registers a synchronous button grab. See the XGrabButton manpage. 1747Register/unregister a synchronous button grab. See the XGrabButton
1748manpage.
1587 1749
1588=item $success = $term->grab ($eventtime[, $sync]) 1750=item $success = $term->grab ($eventtime[, $sync])
1589 1751
1590Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1752Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1591synchronous (C<$sync> is true). Also remembers the grab timestampe. 1753synchronous (C<$sync> is true). Also remembers the grab timestamp.
1592 1754
1593=item $term->allow_events_async 1755=item $term->allow_events_async
1594 1756
1595Calls XAllowEvents with AsyncBoth for the most recent grab. 1757Calls XAllowEvents with AsyncBoth for the most recent grab.
1596 1758
1709 my ($self, $text, $cb) = @_; 1871 my ($self, $text, $cb) = @_;
1710 1872
1711 $self->add_item ({ type => "button", text => $text, activate => $cb}); 1873 $self->add_item ({ type => "button", text => $text, activate => $cb});
1712} 1874}
1713 1875
1714=item $popup->add_toggle ($text, $cb, $initial_value) 1876=item $popup->add_toggle ($text, $initial_value, $cb)
1715 1877
1716Adds a toggle/checkbox item to the popup. Teh callback gets called 1878Adds a toggle/checkbox item to the popup. The callback gets called
1717whenever it gets toggled, with a boolean indicating its value as its first 1879whenever it gets toggled, with a boolean indicating its new value as its
1718argument. 1880first argument.
1719 1881
1720=cut 1882=cut
1721 1883
1722sub add_toggle { 1884sub add_toggle {
1723 my ($self, $text, $cb, $value) = @_; 1885 my ($self, $text, $value, $cb) = @_;
1724 1886
1725 my $item; $item = { 1887 my $item; $item = {
1726 type => "button", 1888 type => "button",
1727 text => " $text", 1889 text => " $text",
1728 value => $value, 1890 value => $value,
1863Set the callback to be called when io events are triggered. C<$reventmask> 2025Set the callback to be called when io events are triggered. C<$reventmask>
1864is a bitset as described in the C<events> method. 2026is a bitset as described in the C<events> method.
1865 2027
1866=item $iow = $iow->fd ($fd) 2028=item $iow = $iow->fd ($fd)
1867 2029
1868Set the filedescriptor (not handle) to watch. 2030Set the file descriptor (not handle) to watch.
1869 2031
1870=item $iow = $iow->events ($eventmask) 2032=item $iow = $iow->events ($eventmask)
1871 2033
1872Set the event mask to watch. The only allowed values are 2034Set the event mask to watch. The only allowed values are
1873C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed 2035C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed
1877 2039
1878Start watching for requested events on the given handle. 2040Start watching for requested events on the given handle.
1879 2041
1880=item $iow = $iow->stop 2042=item $iow = $iow->stop
1881 2043
1882Stop watching for events on the given filehandle. 2044Stop watching for events on the given file handle.
1883 2045
1884=back 2046=back
1885 2047
1886=head2 The C<urxvt::iw> Class 2048=head2 The C<urxvt::iw> Class
1887 2049
1934 2096
1935Set the callback to be called when the timer triggers. 2097Set the callback to be called when the timer triggers.
1936 2098
1937=item $pw = $timer->start ($pid) 2099=item $pw = $timer->start ($pid)
1938 2100
1939Tells the wqtcher to start watching for process C<$pid>. 2101Tells the watcher to start watching for process C<$pid>.
1940 2102
1941=item $pw = $pw->stop 2103=item $pw = $pw->stop
1942 2104
1943Stop the watcher. 2105Stop the watcher.
1944 2106
1957 2119
1958=item >= 3 - script loading and management 2120=item >= 3 - script loading and management
1959 2121
1960=item >=10 - all called hooks 2122=item >=10 - all called hooks
1961 2123
1962=item >=11 - hook reutrn values 2124=item >=11 - hook return values
1963 2125
1964=back 2126=back
1965 2127
1966=head1 AUTHOR 2128=head1 AUTHOR
1967 2129

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines