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.126 by root, Tue Jan 24 19:14:36 2006 UTC vs.
Revision 1.148 by root, Tue Oct 3 21:41:07 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 71
72Another example: Programs I use often output "absolute path: " at the 72Another example: Programs I use often output "absolute path: " at the
94=item option-popup (enabled by default) 94=item option-popup (enabled by default)
95 95
96Binds 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
97runtime. 97runtime.
98 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
99=item selection-popup (enabled by default) 116=item selection-popup (enabled by default)
100 117
101Binds 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
102text into various other formats/action (such as uri unescaping, perl 119text into various other formats/action (such as uri unescaping, perl
103evaluation, web-browser starting etc.), depending on content. 120evaluation, web-browser starting etc.), depending on content.
104 121
105Other extensions can extend this popup menu by pushing a code reference 122Other extensions can extend this popup menu by pushing a code reference
106onto C<@{ $term->{selection_popup_hook} }>, that is called whenever the 123onto C<@{ $term->{selection_popup_hook} }>, which gets called whenever the
107popup is displayed. 124popup is being displayed.
108 125
109It'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
110is 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.
111It 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
112string 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
113when the button gets activated and should transform C<$_>. 130when the button gets activated and should transform C<$_>.
114 131
115The 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
134bottom. 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
135was 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
136additionally stores the first match in the current line into the primary 153additionally stores the first match in the current line into the primary
137selection. 154selection.
138 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
139=item readline (enabled by default) 162=item readline (enabled by default)
140 163
141A support package that tries to make editing with readline easier. At the 164A support package that tries to make editing with readline easier. At
142moment, 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
143move 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
144cursor-left or cursor-right keypresses as required (the this only works 167cursor-left or cursor-right keypresses as required (the this only works
145for programs that correctly support wide characters). 168for programs that correctly support wide characters).
146 169
147To avoid too many false positives, this is only done when: 170To avoid too many false positives, this is only done when:
197the message into vi commands to load the file. 220the message into vi commands to load the file.
198 221
199=item tabbed 222=item tabbed
200 223
201This transforms the terminal into a tabbar with additional terminals, that 224This transforms the terminal into a tabbar with additional terminals, that
202is, 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
203displays 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
204button per tab. 227button per tab.
205 228
206Clicking a button will activate that tab. Pressing B<Shift-Left> and 229Clicking 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, 230B<Shift-Right> will switch to the tab left or right of the current one,
208while B<Shift-Down> creates a new tab. 231while B<Shift-Down> creates a new tab.
209 232
210=item mark-urls 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):
211 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.
244
245=item matcher
246
212Uses per-line display filtering (C<on_line_update>) to underline urls and 247Uses per-line display filtering (C<on_line_update>) to underline text
213make them clickable. When middle-clicked, the program specified in the 248matching a certain pattern and make it clickable. When clicked with the
214resource C<urlLauncher> (default C<x-www-browser>) will be started with 249mouse button specified in the C<matcher.button> resource (default 2, or
215the URL as first argument. 250middle), the program specified in the C<matcher.launcher> resource
251(default, the C<urlLauncher> resource, C<sensible-browser>) will be started
252with the matched text as first argument. The default configuration is
253suitable for matching URLs and launching a web browser, like the
254former "mark-urls" extension.
255
256The default pattern to match URLs can be overridden with the
257C<matcher.pattern.0> resource, and additional patterns can be specified
258with numbered patterns, in a manner similar to the "selection" extension.
259The launcher can also be overridden on a per-pattern basis.
260
261Example configuration:
262
263 URxvt.perl-ext: default,matcher
264 URxvt.urlLauncher: sensible-browser
265 URxvt.matcher.button: 1
266 URxvt.matcher.pattern.1: \\bwww\\.[\\w-]+\\.[\\w./?&@#-]*[\\w/-]
267 URxvt.matcher.pattern.2: \\B(/\\S+?):(\\d+)(?=:|$)
268 URxvt.matcher.launcher.2: gvim +$2 $1
269
270=item xim-onthespot
271
272This (experimental) perl extension implements OnTheSpot editing. It does
273not work perfectly, and some input methods don't seem to work well with
274OnTheSpot editing in general, but it seems to work at leats for SCIM and
275kinput2.
276
277You enable it by specifying this extension and a preedit style of
278C<OnTheSpot>, i.e.:
279
280 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot
281
282=item kuake<hotkey>
283
284A very primitive quake-console-like extension. It was inspired by a
285description of how the programs C<kuake> and C<yakuake> work: Whenever the
286user presses a global accelerator key (by default C<F10>), the terminal
287will show or hide itself. Another press of the accelerator key will hide
288or show it again.
289
290Initially, the window will not be shown when using this extension.
291
292This is useful if you need a single terminal thats not using any desktop
293space most of the time but is quickly available at the press of a key.
294
295The accelerator key is grabbed regardless of any modifiers, so this
296extension will actually grab a physical key just for this function.
297
298If you want a quake-like animation, tell your window manager to do so
299(fvwm can do it).
216 300
217=item automove-background 301=item automove-background
218 302
219This is basically a one-line extension that dynamically changes the background pixmap offset 303This is basically a very small extension that dynamically changes the
220to the window position, in effect creating the same effect as pseudo transparency with 304background pixmap offset to the window position, in effect creating the
221a custom pixmap. No scaling is supported in this mode. Exmaple: 305same effect as pseudo transparency with a custom pixmap. No scaling is
306supported in this mode. Example:
222 307
223 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background 308 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background
224 309
225=item block-graphics-to-ascii 310=item block-graphics-to-ascii
226 311
227A not very useful example of filtering all text output to the terminal, 312A not very useful example of filtering all text output to the terminal
228by replacing all line-drawing characters (U+2500 .. U+259F) by a 313by replacing all line-drawing characters (U+2500 .. U+259F) by a
229similar-looking ascii character. 314similar-looking ascii character.
230 315
231=item digital-clock 316=item digital-clock
232 317
233Displays a digital clock using the built-in overlay. 318Displays a digital clock using the built-in overlay.
234 319
235=item example-refresh-hooks 320=item remote-clipboard
236 321
237Displays a very simple digital clock in the upper right corner of the 322Somewhat of a misnomer, this extension adds two menu entries to the
238window. Illustrates overwriting the refresh callbacks to create your own 323selection popup that allows one ti run external commands to store the
239overlays or changes. 324selection somewhere and fetch it again.
325
326We use it to implement a "distributed selection mechanism", which just
327means that one command uploads the file to a remote server, and another
328reads it.
329
330The commands can be set using the C<URxvt.remote-selection.store> and
331C<URxvt.remote-selection.fetch> resources. The first should read the
332selection to store from STDIN (always in UTF-8), the second should provide
333the selection data on STDOUT (also in UTF-8).
334
335The defaults (which are likely useless to you) use rsh and cat:
336
337 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
338 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
240 339
241=item selection-pastebin 340=item selection-pastebin
242 341
243This is a little rarely useful extension that Uploads the selection as 342This is a little rarely useful extension that Uploads the selection as
244textfile to a remote site (or does other things). (The implementation is 343textfile to a remote site (or does other things). (The implementation is
264After a successful upload the selection will be replaced by the text given 363After a successful upload the selection will be replaced by the text given
265in the C<selection-pastebin-url> resource (again, the % is the placeholder 364in the C<selection-pastebin-url> resource (again, the % is the placeholder
266for the filename): 365for the filename):
267 366
268 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/% 367 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
368
369I<Note to xrdb users:> xrdb uses the C preprocessor, which might interpret
370the double C</> characters as comment start. Use C<\057\057> instead,
371which works regardless of wether xrdb is used to parse the resource file
372or not.
373
374=item example-refresh-hooks
375
376Displays a very simple digital clock in the upper right corner of the
377window. Illustrates overwriting the refresh callbacks to create your own
378overlays or changes.
269 379
270=back 380=back
271 381
272=head1 API DOCUMENTATION 382=head1 API DOCUMENTATION
273 383
307 417
308=back 418=back
309 419
310=head2 Extension Objects 420=head2 Extension Objects
311 421
312Very perl extension is a perl class. A separate perl object is created 422Every perl extension is a perl class. A separate perl object is created
313for each terminal and each extension and passed as the first parameter to 423for each terminal, and each terminal has its own set of extenion objects,
314hooks. So extensions can use their C<$self> object without having to think 424which are passed as the first parameter to hooks. So extensions can use
315about other extensions, with the exception of methods and members that 425their C<$self> object without having to think about clashes with other
426extensions or other terminals, with the exception of methods and members
316begin with an underscore character C<_>: these are reserved for internal 427that begin with an underscore character C<_>: these are reserved for
317use. 428internal use.
318 429
319Although it isn't a C<urxvt::term> object, you can call all methods of the 430Although it isn't a C<urxvt::term> object, you can call all methods of the
320C<urxvt::term> class on this object. 431C<urxvt::term> class on this object.
321 432
322It has the following methods and data members: 433It has the following methods and data members:
343=head2 Hooks 454=head2 Hooks
344 455
345The following subroutines can be declared in extension files, and will be 456The following subroutines can be declared in extension files, and will be
346called whenever the relevant event happens. 457called whenever the relevant event happens.
347 458
348The first argument passed to them is an extension oject as described in 459The first argument passed to them is an extension object as described in
349the in the C<Extension Objects> section. 460the in the C<Extension Objects> section.
350 461
351B<All> of these hooks must return a boolean value. If any of the called 462B<All> of these hooks must return a boolean value. If any of the called
352hooks returns true, then the event counts as being I<consumed>, and the 463hooks returns true, then the event counts as being I<consumed>, and the
353relevant action might not be carried out by the C++ code. 464relevant action might not be carried out by the C++ code.
366place. 477place.
367 478
368=item on_start $term 479=item on_start $term
369 480
370Called at the very end of initialisation of a new terminal, just before 481Called at the very end of initialisation of a new terminal, just before
371trying to map (display) the toplevel and returning to the mainloop. 482trying to map (display) the toplevel and returning to the main loop.
372 483
373=item on_destroy $term 484=item on_destroy $term
374 485
375Called whenever something tries to destroy terminal, before doing anything 486Called whenever something tries to destroy terminal, when the terminal is
376yet. If this hook returns true, then destruction is skipped, but this is 487still fully functional (not for long, though).
377rarely a good idea.
378 488
379=item on_reset $term 489=item on_reset $term
380 490
381Called after the screen is "reset" for any reason, such as resizing or 491Called after the screen is "reset" for any reason, such as resizing or
382control sequences. Here is where you can react on changes to size-related 492control sequences. Here is where you can react on changes to size-related
404 514
405Called whenever a selection has been copied, but before the selection is 515Called whenever a selection has been copied, but before the selection is
406requested from the server. The selection text can be queried and changed 516requested from the server. The selection text can be queried and changed
407by calling C<< $term->selection >>. 517by calling C<< $term->selection >>.
408 518
409Returning a true value aborts selection grabbing. It will still be hilighted. 519Returning a true value aborts selection grabbing. It will still be highlighted.
410 520
411=item on_sel_extend $term 521=item on_sel_extend $term
412 522
413Called whenever the user tries to extend the selection (e.g. with a double 523Called whenever the user tries to extend the selection (e.g. with a double
414click) and is either supposed to return false (normal operation), or 524click) and is either supposed to return false (normal operation), or
415should extend the selection itelf and return true to suppress the built-in 525should extend the selection itself and return true to suppress the built-in
416processing. This can happen multiple times, as long as the callback 526processing. This can happen multiple times, as long as the callback
417returns true, it will be called on every further click by the user and is 527returns true, it will be called on every further click by the user and is
418supposed to enlarge the selection more and more, if possible. 528supposed to enlarge the selection more and more, if possible.
419 529
420See the F<selection> example extension. 530See the F<selection> example extension.
421 531
422=item on_view_change $term, $offset 532=item on_view_change $term, $offset
423 533
424Called whenever the view offset changes, i..e the user or program 534Called whenever the view offset changes, i.e. the user or program
425scrolls. Offset C<0> means display the normal terminal, positive values 535scrolls. Offset C<0> means display the normal terminal, positive values
426show this many lines of scrollback. 536show this many lines of scrollback.
427 537
428=item on_scroll_back $term, $lines, $saved 538=item on_scroll_back $term, $lines, $saved
429 539
433 543
434It is called before lines are scrolled out (so rows 0 .. min ($lines - 1, 544It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
435$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total 545$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
436number of lines that will be in the scrollback buffer. 546number of lines that will be in the scrollback buffer.
437 547
548=item on_osc_seq $term, $op, $args
549
550Called on every OSC sequence and can be used to suppress it or modify its
551behaviour. The default should be to return an empty list. A true value
552suppresses execution of the request completely. Make sure you don't get
553confused by recursive invocations when you output an osc sequence within
554this callback.
555
556C<on_osc_seq_perl> should be used for new behaviour.
557
438=item on_osc_seq $term, $string 558=item on_osc_seq_perl $term, $string
439 559
440Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 560Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
441operating system command) is processed. Cursor position and other state 561operating system command) is processed. Cursor position and other state
442information is up-to-date when this happens. For interoperability, the 562information is up-to-date when this happens. For interoperability, the
443string should start with the extension name and a colon, to distinguish 563string should start with the extension name and a colon, to distinguish
444it from commands for other extensions, and this might be enforced in the 564it from commands for other extensions, and this might be enforced in the
445future. 565future.
446 566
447Be careful not ever to trust (in a security sense) the data you receive, 567Be careful not ever to trust (in a security sense) the data you receive,
448as its source can not easily be controleld (e-mail content, messages from 568as its source can not easily be controlled (e-mail content, messages from
449other users on the same system etc.). 569other users on the same system etc.).
450 570
451=item on_add_lines $term, $string 571=item on_add_lines $term, $string
452 572
453Called whenever text is about to be output, with the text as argument. You 573Called whenever text is about to be output, with the text as argument. You
484 604
485=item on_refresh_end $term 605=item on_refresh_end $term
486 606
487Called just after the screen gets redrawn. See C<on_refresh_begin>. 607Called just after the screen gets redrawn. See C<on_refresh_begin>.
488 608
489=item on_keyboard_command $term, $string 609=item on_user_command $term, $string
490 610
491Called whenever the user presses a key combination that has a 611Called whenever a user-configured event is being activated (e.g. via
492C<perl:string> action bound to it (see description of the B<keysym> 612a C<perl:string> action bound to a key, see description of the B<keysym>
493resource in the @@RXVT_NAME@@(1) manpage). 613resource in the @@RXVT_NAME@@(1) manpage).
614
615The event is simply the action string. This interface is assumed to change
616slightly in the future.
617
618=item on_resize_all_windows $tern, $new_width, $new_height
619
620Called just after the new window size has been calculated, but before
621windows are actually being resized or hints are being set. If this hook
622returns TRUE, setting of the window hints is being skipped.
494 623
495=item on_x_event $term, $event 624=item on_x_event $term, $event
496 625
497Called on every X event received on the vt window (and possibly other 626Called on every X event received on the vt window (and possibly other
498windows). Should only be used as a last resort. Most event structure 627windows). Should only be used as a last resort. Most event structure
499members are not passed. 628members are not passed.
500 629
630=item on_root_event $term, $event
631
632Like C<on_x_event>, but is called for events on the root window.
633
501=item on_focus_in $term 634=item on_focus_in $term
502 635
503Called whenever the window gets the keyboard focus, before rxvt-unicode 636Called whenever the window gets the keyboard focus, before rxvt-unicode
504does focus in processing. 637does focus in processing.
505 638
506=item on_focus_out $term 639=item on_focus_out $term
507 640
508Called wheneever the window loses keyboard focus, before rxvt-unicode does 641Called whenever the window loses keyboard focus, before rxvt-unicode does
509focus out processing. 642focus out processing.
510 643
511=item on_configure_notify $term, $event 644=item on_configure_notify $term, $event
512 645
513=item on_property_notify $term, $event 646=item on_property_notify $term, $event
596The current terminal. This variable stores the current C<urxvt::term> 729The current terminal. This variable stores the current C<urxvt::term>
597object, whenever a callback/hook is executing. 730object, whenever a callback/hook is executing.
598 731
599=item @urxvt::TERM_INIT 732=item @urxvt::TERM_INIT
600 733
601All coderefs in this array will be called as methods of the next newly 734All code references in this array will be called as methods of the next newly
602created C<urxvt::term> object (during the C<on_init> phase). The array 735created C<urxvt::term> object (during the C<on_init> phase). The array
603gets cleared before the codereferences that were in it are being executed, 736gets cleared before the code references that were in it are being executed,
604so coderefs can push themselves onto it again if they so desire. 737so references can push themselves onto it again if they so desire.
605 738
606This complements to the perl-eval commandline option, but gets executed 739This complements to the perl-eval command line option, but gets executed
607first. 740first.
608 741
609=item @urxvt::TERM_EXT 742=item @urxvt::TERM_EXT
610 743
611Works similar to C<@TERM_INIT>, but contains perl package/class names, which 744Works similar to C<@TERM_INIT>, but contains perl package/class names, which
632 765
633Using this function has the advantage that its output ends up in the 766Using this function has the advantage that its output ends up in the
634correct place, e.g. on stderr of the connecting urxvtc client. 767correct place, e.g. on stderr of the connecting urxvtc client.
635 768
636Messages have a size limit of 1023 bytes currently. 769Messages have a size limit of 1023 bytes currently.
770
771=item @terms = urxvt::termlist
772
773Returns all urxvt::term objects that exist in this process, regardless of
774whether they are started, being destroyed etc., so be careful. Only term
775objects that have perl extensions attached will be returned (because there
776is no urxvt::term objet associated with others).
637 777
638=item $time = urxvt::NOW 778=item $time = urxvt::NOW
639 779
640Returns the "current time" (as per the event loop). 780Returns the "current time" (as per the event loop).
641 781
699Return the foreground/background colour index, respectively. 839Return the foreground/background colour index, respectively.
700 840
701=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour 841=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
702 842
703=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour 843=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
844
845=item $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
704 846
705Replace the foreground/background colour in the rendition mask with the 847Replace the foreground/background colour in the rendition mask with the
706specified one. 848specified one.
707 849
708=item $value = urxvt::GET_CUSTOM $rend 850=item $value = urxvt::GET_CUSTOM $rend
799 } else { 941 } else {
800 $ext_arg{$_} ||= []; 942 $ext_arg{$_} ||= [];
801 } 943 }
802 } 944 }
803 945
804 while (my ($ext, $argv) = each %ext_arg) { 946 for my $ext (sort keys %ext_arg) {
805 my @files = grep -f $_, map "$_/$ext", @dirs; 947 my @files = grep -f $_, map "$_/$ext", @dirs;
806 948
807 if (@files) { 949 if (@files) {
808 $TERM->register_package (extension_package $files[0], $argv); 950 $TERM->register_package (extension_package $files[0], $ext_arg{$ext});
809 } else { 951 } else {
810 warn "perl extension '$ext' not found in perl library search path\n"; 952 warn "perl extension '$ext' not found in perl library search path\n";
811 } 953 }
812 } 954 }
813 955
819 961
820 if (my $cb = $TERM->{_hook}[$htype]) { 962 if (my $cb = $TERM->{_hook}[$htype]) {
821 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")" 963 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
822 if $verbosity >= 10; 964 if $verbosity >= 10;
823 965
824 keys %$cb; 966 for my $pkg (keys %$cb) {
825
826 while (my ($pkg, $cb) = each %$cb) {
827 my $retval_ = eval { $cb->($TERM->{_pkg}{$pkg}, @_) }; 967 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg}, @_) };
828 $retval ||= $retval_; 968 $retval ||= $retval_;
829 969
830 if ($@) { 970 if ($@) {
831 $TERM->ungrab; # better to lose the grab than the session 971 $TERM->ungrab; # better to lose the grab than the session
832 warn $@; 972 warn $@;
844 # clear package 984 # clear package
845 %$TERM = (); 985 %$TERM = ();
846 } 986 }
847 987
848 $retval 988 $retval
989}
990
991sub SET_COLOR($$$) {
992 SET_BGCOLOR (SET_FGCOLOR ($_[0], $_[1]), $_[2])
849} 993}
850 994
851# urxvt::term::extension 995# urxvt::term::extension
852 996
853package urxvt::term::extension; 997package urxvt::term::extension;
1022hash which defines the environment of the new terminal. 1166hash which defines the environment of the new terminal.
1023 1167
1024Croaks (and probably outputs an error message) if the new instance 1168Croaks (and probably outputs an error message) if the new instance
1025couldn't be created. Returns C<undef> if the new instance didn't 1169couldn't be created. Returns C<undef> if the new instance didn't
1026initialise perl, and the terminal object otherwise. The C<init> and 1170initialise perl, and the terminal object otherwise. The C<init> and
1027C<start> hooks will be called during this call. 1171C<start> hooks will be called before this call returns, and are free to
1172refer to global data (which is race free).
1028 1173
1029=cut 1174=cut
1030 1175
1031sub new { 1176sub new {
1032 my ($class, $env, @args) = @_; 1177 my ($class, $env, @args) = @_;
1033 1178
1179 $env or Carp::croak "environment hash missing in call to urxvt::term->new";
1180 @args or Carp::croak "name argument missing in call to urxvt::term->new";
1181
1034 _new ([ map "$_=$env->{$_}", keys %$env ], @args); 1182 _new ([ map "$_=$env->{$_}", keys %$env ], \@args);
1035} 1183}
1036 1184
1037=item $term->destroy 1185=item $term->destroy
1038 1186
1039Destroy the terminal object (close the window, free resources 1187Destroy the terminal object (close the window, free resources
1069 1217
1070Returns true if the option specified by C<$optval> is enabled, and 1218Returns true if the option specified by C<$optval> is enabled, and
1071optionally change it. All option values are stored by name in the hash 1219optionally change it. All option values are stored by name in the hash
1072C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash. 1220C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
1073 1221
1074Here is a a likely non-exhaustive list of option names, please see the 1222Here is a likely non-exhaustive list of option names, please see the
1075source file F</src/optinc.h> to see the actual list: 1223source file F</src/optinc.h> to see the actual list:
1076 1224
1077 borderLess console cursorBlink cursorUnderline hold iconic insecure 1225 borderLess console cursorBlink cursorUnderline hold iconic insecure
1078 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 1226 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
1079 override-redirect pastableTabs pointerBlank reverseVideo scrollBar 1227 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
1096likely change). 1244likely change).
1097 1245
1098Please note that resource strings will currently only be freed when the 1246Please note that resource strings will currently only be freed when the
1099terminal is destroyed, so changing options frequently will eat memory. 1247terminal is destroyed, so changing options frequently will eat memory.
1100 1248
1101Here is a a likely non-exhaustive list of resource names, not all of which 1249Here is a likely non-exhaustive list of resource names, not all of which
1102are supported in every build, please see the source file F</src/rsinc.h> 1250are supported in every build, please see the source file F</src/rsinc.h>
1103to see the actual list: 1251to see the actual list:
1104 1252
1105 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1253 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
1106 borderLess color cursorBlink cursorUnderline cutchars delete_key 1254 borderLess color cursorBlink cursorUnderline cutchars delete_key
1339Adds the specified events to the vt event mask. Useful e.g. when you want 1487Adds the specified events to the vt event mask. Useful e.g. when you want
1340to receive pointer events all the times: 1488to receive pointer events all the times:
1341 1489
1342 $term->vt_emask_add (urxvt::PointerMotionMask); 1490 $term->vt_emask_add (urxvt::PointerMotionMask);
1343 1491
1492=item $term->focus_in
1493
1494=item $term->focus_out
1495
1496=item $term->key_press ($state, $keycode[, $time])
1497
1498=item $term->key_release ($state, $keycode[, $time])
1499
1500Deliver various fake events to to terminal.
1501
1344=item $window_width = $term->width 1502=item $window_width = $term->width
1345 1503
1346=item $window_height = $term->height 1504=item $window_height = $term->height
1347 1505
1348=item $font_width = $term->fwidth 1506=item $font_width = $term->fwidth
1378=item $env = $term->env 1536=item $env = $term->env
1379 1537
1380Returns a copy of the environment in effect for the terminal as a hashref 1538Returns a copy of the environment in effect for the terminal as a hashref
1381similar to C<\%ENV>. 1539similar to C<\%ENV>.
1382 1540
1541=item @envv = $term->envv
1542
1543Returns the environment as array of strings of the form C<VAR=VALUE>.
1544
1545=item @argv = $term->argv
1546
1547Return the argument vector as this terminal, similar to @ARGV, but
1548includes the program name as first element.
1549
1383=cut 1550=cut
1384 1551
1385sub env { 1552sub env {
1386 if (my $env = $_[0]->_env) {
1387 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env } 1553 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), $_[0]->envv }
1388 } else {
1389 +{ %ENV }
1390 }
1391} 1554}
1392 1555
1393=item $modifiermask = $term->ModLevel3Mask 1556=item $modifiermask = $term->ModLevel3Mask
1394 1557
1395=item $modifiermask = $term->ModMetaMask 1558=item $modifiermask = $term->ModMetaMask
1403 1566
1404Returns the currently displayed screen (0 primary, 1 secondary). 1567Returns the currently displayed screen (0 primary, 1 secondary).
1405 1568
1406=item $cursor_is_hidden = $term->hidden_cursor 1569=item $cursor_is_hidden = $term->hidden_cursor
1407 1570
1408Returns wether the cursor is currently hidden or not. 1571Returns whether the cursor is currently hidden or not.
1409 1572
1410=item $view_start = $term->view_start ([$newvalue]) 1573=item $view_start = $term->view_start ([$newvalue])
1411 1574
1412Returns the row number of the topmost displayed line. Maximum value is 1575Returns the row number of the topmost displayed line. Maximum value is
1413C<0>, which displays the normal terminal contents. Lower values scroll 1576C<0>, which displays the normal terminal contents. Lower values scroll
1590where one character corresponds to one screen cell. See 1753where one character corresponds to one screen cell. See
1591C<< $term->ROW_t >> for details. 1754C<< $term->ROW_t >> for details.
1592 1755
1593=item $string = $term->special_decode $text 1756=item $string = $term->special_decode $text
1594 1757
1595Converts rxvt-unicodes text reprsentation into a perl string. See 1758Converts rxvt-unicodes text representation into a perl string. See
1596C<< $term->ROW_t >> for details. 1759C<< $term->ROW_t >> for details.
1597 1760
1598=item $success = $term->grab_button ($button, $modifiermask) 1761=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1599 1762
1763=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1764
1600Registers a synchronous button grab. See the XGrabButton manpage. 1765Register/unregister a synchronous button grab. See the XGrabButton
1766manpage.
1601 1767
1602=item $success = $term->grab ($eventtime[, $sync]) 1768=item $success = $term->grab ($eventtime[, $sync])
1603 1769
1604Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1770Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1605synchronous (C<$sync> is true). Also remembers the grab timestampe. 1771synchronous (C<$sync> is true). Also remembers the grab timestamp.
1606 1772
1607=item $term->allow_events_async 1773=item $term->allow_events_async
1608 1774
1609Calls XAllowEvents with AsyncBoth for the most recent grab. 1775Calls XAllowEvents with AsyncBoth for the most recent grab.
1610 1776
1723 my ($self, $text, $cb) = @_; 1889 my ($self, $text, $cb) = @_;
1724 1890
1725 $self->add_item ({ type => "button", text => $text, activate => $cb}); 1891 $self->add_item ({ type => "button", text => $text, activate => $cb});
1726} 1892}
1727 1893
1728=item $popup->add_toggle ($text, $cb, $initial_value) 1894=item $popup->add_toggle ($text, $initial_value, $cb)
1729 1895
1730Adds a toggle/checkbox item to the popup. Teh callback gets called 1896Adds a toggle/checkbox item to the popup. The callback gets called
1731whenever it gets toggled, with a boolean indicating its value as its first 1897whenever it gets toggled, with a boolean indicating its new value as its
1732argument. 1898first argument.
1733 1899
1734=cut 1900=cut
1735 1901
1736sub add_toggle { 1902sub add_toggle {
1737 my ($self, $text, $cb, $value) = @_; 1903 my ($self, $text, $value, $cb) = @_;
1738 1904
1739 my $item; $item = { 1905 my $item; $item = {
1740 type => "button", 1906 type => "button",
1741 text => " $text", 1907 text => " $text",
1742 value => $value, 1908 value => $value,
1877Set the callback to be called when io events are triggered. C<$reventmask> 2043Set the callback to be called when io events are triggered. C<$reventmask>
1878is a bitset as described in the C<events> method. 2044is a bitset as described in the C<events> method.
1879 2045
1880=item $iow = $iow->fd ($fd) 2046=item $iow = $iow->fd ($fd)
1881 2047
1882Set the filedescriptor (not handle) to watch. 2048Set the file descriptor (not handle) to watch.
1883 2049
1884=item $iow = $iow->events ($eventmask) 2050=item $iow = $iow->events ($eventmask)
1885 2051
1886Set the event mask to watch. The only allowed values are 2052Set the event mask to watch. The only allowed values are
1887C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed 2053C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed
1891 2057
1892Start watching for requested events on the given handle. 2058Start watching for requested events on the given handle.
1893 2059
1894=item $iow = $iow->stop 2060=item $iow = $iow->stop
1895 2061
1896Stop watching for events on the given filehandle. 2062Stop watching for events on the given file handle.
1897 2063
1898=back 2064=back
1899 2065
1900=head2 The C<urxvt::iw> Class 2066=head2 The C<urxvt::iw> Class
1901 2067
1948 2114
1949Set the callback to be called when the timer triggers. 2115Set the callback to be called when the timer triggers.
1950 2116
1951=item $pw = $timer->start ($pid) 2117=item $pw = $timer->start ($pid)
1952 2118
1953Tells the wqtcher to start watching for process C<$pid>. 2119Tells the watcher to start watching for process C<$pid>.
1954 2120
1955=item $pw = $pw->stop 2121=item $pw = $pw->stop
1956 2122
1957Stop the watcher. 2123Stop the watcher.
1958 2124
1971 2137
1972=item >= 3 - script loading and management 2138=item >= 3 - script loading and management
1973 2139
1974=item >=10 - all called hooks 2140=item >=10 - all called hooks
1975 2141
1976=item >=11 - hook reutrn values 2142=item >=11 - hook return values
1977 2143
1978=back 2144=back
1979 2145
1980=head1 AUTHOR 2146=head1 AUTHOR
1981 2147

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines