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.130 by root, Wed Jan 25 15:32:48 2006 UTC vs.
Revision 1.156 by ayin, Wed Aug 1 17:55:37 2007 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
28Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where 28Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where
29scripts will be shared (but not enabled) for all terminals. 29scripts will be shared (but not enabled) for all terminals.
30
31You can disable the embedded perl interpreter by setting both "perl-ext"
32and "perl-ext-common" resources to the empty string.
30 33
31=head1 PREPACKAGED EXTENSIONS 34=head1 PREPACKAGED EXTENSIONS
32 35
33This section describes the extensions delivered with this release. You can 36This section describes the extensions delivered with this release. You can
34find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>. 37find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>.
62 URxvt.selection.pattern-1: perl-regex 65 URxvt.selection.pattern-1: perl-regex
63 ... 66 ...
64 67
65The index number (0, 1...) must not have any holes, and each regex must 68The 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 69contain at least one pair of capturing parentheses, which will be used for
67the match. For example, the followign adds a regex that matches everything 70the match. For example, the following adds a regex that matches everything
68between two vertical bars: 71between two vertical bars:
69 72
70 URxvt.selection.pattern-0: \\|([^|]+)\\| 73 URxvt.selection.pattern-0: \\|([^|]+)\\|
71 74
72Another example: Programs I use often output "absolute path: " at the 75Another example: Programs I use often output "absolute path: " at the
94=item option-popup (enabled by default) 97=item option-popup (enabled by default)
95 98
96Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at 99Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at
97runtime. 100runtime.
98 101
102Other extensions can extend this popup menu by pushing a code reference
103onto C<@{ $term->{option_popup_hook} }>, which gets called whenever the
104popup is being displayed.
105
106It's sole argument is the popup menu, which can be modified. It should
107either return nothing or a string, the initial boolean value and a code
108reference. The string will be used as button text and the code reference
109will be called when the toggle changes, with the new boolean value as
110first argument.
111
112The following will add an entry C<myoption> that changes
113C<$self->{myoption}>:
114
115 push @{ $self->{term}{option_popup_hook} }, sub {
116 ("my option" => $myoption, sub { $self->{myoption} = $_[0] })
117 };
118
99=item selection-popup (enabled by default) 119=item selection-popup (enabled by default)
100 120
101Binds a popup menu to Ctrl-Button3 that lets you convert the selection 121Binds a popup menu to Ctrl-Button3 that lets you convert the selection
102text into various other formats/action (such as uri unescaping, perl 122text into various other formats/action (such as uri unescaping, perl
103evaluation, web-browser starting etc.), depending on content. 123evaluation, web-browser starting etc.), depending on content.
104 124
105Other extensions can extend this popup menu by pushing a code reference 125Other extensions can extend this popup menu by pushing a code reference
106onto C<@{ $term->{selection_popup_hook} }>, that is called whenever the 126onto C<@{ $term->{selection_popup_hook} }>, which gets called whenever the
107popup is displayed. 127popup is being displayed.
108 128
109It's sole argument is the popup menu, which can be modified. The selection 129It'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. 130is 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 131It 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 132string will be used as button text and the code reference will be called
113when the button gets activated and should transform C<$_>. 133when the button gets activated and should transform C<$_>.
114 134
115The following will add an entry C<a to b> that transforms all C<a>s in 135The following will add an entry C<a to b> that transforms all C<a>s in
132search. C<BackSpace> removes a character from the regex, C<Up> and C<Down> 152search. C<BackSpace> removes a character from the regex, C<Up> and C<Down>
133search upwards/downwards in the scrollback buffer, C<End> jumps to the 153search upwards/downwards in the scrollback buffer, C<End> jumps to the
134bottom. C<Escape> leaves search mode and returns to the point where search 154bottom. 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 155was 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 156additionally stores the first match in the current line into the primary
137selection. 157selection if the C<Shift> modifier is active.
158
159The regex defaults to "(?i)", resulting in a case-insensitive search. To
160get a case-sensitive search you can delete this prefix using C<BackSpace>
161or simply use an uppercase character which removes the "(?i)" prefix.
162
163See L<perlre> for more info about perl regular expression syntax.
138 164
139=item readline (enabled by default) 165=item readline (enabled by default)
140 166
141A support package that tries to make editing with readline easier. At the 167A support package that tries to make editing with readline easier. At
142moment, it reacts to clicking with the left mouse button by trying to 168the 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 169move 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 170cursor-left or cursor-right keypresses as required (the this only works
145for programs that correctly support wide characters). 171for programs that correctly support wide characters).
146 172
147To avoid too many false positives, this is only done when: 173To avoid too many false positives, this is only done when:
197the message into vi commands to load the file. 223the message into vi commands to load the file.
198 224
199=item tabbed 225=item tabbed
200 226
201This transforms the terminal into a tabbar with additional terminals, that 227This transforms the terminal into a tabbar with additional terminals, that
202is, it implements what is commonly refered to as "tabbed terminal". The topmost line 228is, 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 229displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one
204button per tab. 230button per tab.
205 231
206Clicking a button will activate that tab. Pressing B<Shift-Left> and 232Clicking 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, 233B<Shift-Right> will switch to the tab left or right of the current one,
208while B<Shift-Down> creates a new tab. 234while B<Shift-Down> creates a new tab.
209 235
210=item mark-urls 236The tabbar itself can be configured similarly to a normal terminal, but
237with a resource class of C<URxvt.tabbed>. In addition, it supports the
238following four resources (shown with defaults):
211 239
240 URxvt.tabbed.tabbar-fg: <colour-index, default 3>
241 URxvt.tabbed.tabbar-bg: <colour-index, default 0>
242 URxvt.tabbed.tab-fg: <colour-index, default 0>
243 URxvt.tabbed.tab-bg: <colour-index, default 1>
244
245See I<COLOR AND GRAPHICS> in the @@RXVT_NAME@@(1) manpage for valid
246indices.
247
248=item matcher
249
212Uses per-line display filtering (C<on_line_update>) to underline urls and 250Uses per-line display filtering (C<on_line_update>) to underline text
213make them clickable. When middle-clicked, the program specified in the 251matching a certain pattern and make it clickable. When clicked with the
214resource C<urlLauncher> (default C<x-www-browser>) will be started with 252mouse button specified in the C<matcher.button> resource (default 2, or
215the URL as first argument. 253middle), the program specified in the C<matcher.launcher> resource
254(default, the C<urlLauncher> resource, C<sensible-browser>) will be started
255with the matched text as first argument. The default configuration is
256suitable for matching URLs and launching a web browser, like the
257former "mark-urls" extension.
258
259The default pattern to match URLs can be overridden with the
260C<matcher.pattern.0> resource, and additional patterns can be specified
261with numbered patterns, in a manner similar to the "selection" extension.
262The launcher can also be overridden on a per-pattern basis.
263
264It is possible to activate the most recently seen match from the keyboard.
265Simply bind a keysym to "perl:matcher" as seen in the example below.
266
267Example configuration:
268
269 URxvt.perl-ext: default,matcher
270 URxvt.urlLauncher: sensible-browser
271 URxvt.keysym.C-Delete: perl:matcher
272 URxvt.matcher.button: 1
273 URxvt.matcher.pattern.1: \\bwww\\.[\\w-]+\\.[\\w./?&@#-]*[\\w/-]
274 URxvt.matcher.pattern.2: \\B(/\\S+?):(\\d+)(?=:|$)
275 URxvt.matcher.launcher.2: gvim +$2 $1
216 276
217=item xim-onthespot 277=item xim-onthespot
218 278
219This (experimental) perl extension implements OnTheSpot editing. It does 279This (experimental) perl extension implements OnTheSpot editing. It does
220not work perfectly, and some input methods don't seem to work well with 280not work perfectly, and some input methods don't seem to work well with
224You enable it by specifying this extension and a preedit style of 284You enable it by specifying this extension and a preedit style of
225C<OnTheSpot>, i.e.: 285C<OnTheSpot>, i.e.:
226 286
227 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot 287 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot
228 288
289=item kuake<hotkey>
290
291A very primitive quake-console-like extension. It was inspired by a
292description of how the programs C<kuake> and C<yakuake> work: Whenever the
293user presses a global accelerator key (by default C<F10>), the terminal
294will show or hide itself. Another press of the accelerator key will hide
295or show it again.
296
297Initially, the window will not be shown when using this extension.
298
299This is useful if you need a single terminal thats not using any desktop
300space most of the time but is quickly available at the press of a key.
301
302The accelerator key is grabbed regardless of any modifiers, so this
303extension will actually grab a physical key just for this function.
304
305If you want a quake-like animation, tell your window manager to do so
306(fvwm can do it).
307
229=item automove-background 308=item automove-background
230 309
231This is basically a one-line extension that dynamically changes the background pixmap offset 310This is basically a very small extension that dynamically changes the
232to the window position, in effect creating the same effect as pseudo transparency with 311background pixmap offset to the window position, in effect creating the
233a custom pixmap. No scaling is supported in this mode. Exmaple: 312same effect as pseudo transparency with a custom pixmap. No scaling is
313supported in this mode. Example:
234 314
235 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background 315 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background
236 316
317L<http://wiki.archlinux.org/index.php/Perl_Background_Rotation/Extensions>
318shows how this extension can be used to implement an automatically blurred
319transparent background.
320
237=item block-graphics-to-ascii 321=item block-graphics-to-ascii
238 322
239A not very useful example of filtering all text output to the terminal, 323A not very useful example of filtering all text output to the terminal
240by replacing all line-drawing characters (U+2500 .. U+259F) by a 324by replacing all line-drawing characters (U+2500 .. U+259F) by a
241similar-looking ascii character. 325similar-looking ascii character.
242 326
243=item digital-clock 327=item digital-clock
244 328
290After a successful upload the selection will be replaced by the text given 374After a successful upload the selection will be replaced by the text given
291in the C<selection-pastebin-url> resource (again, the % is the placeholder 375in the C<selection-pastebin-url> resource (again, the % is the placeholder
292for the filename): 376for the filename):
293 377
294 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/% 378 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
379
380I<Note to xrdb users:> xrdb uses the C preprocessor, which might interpret
381the double C</> characters as comment start. Use C<\057\057> instead,
382which works regardless of wether xrdb is used to parse the resource file
383or not.
295 384
296=item example-refresh-hooks 385=item example-refresh-hooks
297 386
298Displays a very simple digital clock in the upper right corner of the 387Displays a very simple digital clock in the upper right corner of the
299window. Illustrates overwriting the refresh callbacks to create your own 388window. Illustrates overwriting the refresh callbacks to create your own
339 428
340=back 429=back
341 430
342=head2 Extension Objects 431=head2 Extension Objects
343 432
344Very perl extension is a perl class. A separate perl object is created 433Every perl extension is a perl class. A separate perl object is created
345for each terminal and each extension and passed as the first parameter to 434for each terminal, and each terminal has its own set of extenion objects,
346hooks. So extensions can use their C<$self> object without having to think 435which are passed as the first parameter to hooks. So extensions can use
347about other extensions, with the exception of methods and members that 436their C<$self> object without having to think about clashes with other
437extensions or other terminals, with the exception of methods and members
348begin with an underscore character C<_>: these are reserved for internal 438that begin with an underscore character C<_>: these are reserved for
349use. 439internal use.
350 440
351Although it isn't a C<urxvt::term> object, you can call all methods of the 441Although it isn't a C<urxvt::term> object, you can call all methods of the
352C<urxvt::term> class on this object. 442C<urxvt::term> class on this object.
353 443
354It has the following methods and data members: 444It has the following methods and data members:
375=head2 Hooks 465=head2 Hooks
376 466
377The following subroutines can be declared in extension files, and will be 467The following subroutines can be declared in extension files, and will be
378called whenever the relevant event happens. 468called whenever the relevant event happens.
379 469
380The first argument passed to them is an extension oject as described in 470The first argument passed to them is an extension object as described in
381the in the C<Extension Objects> section. 471the in the C<Extension Objects> section.
382 472
383B<All> of these hooks must return a boolean value. If any of the called 473B<All> of these hooks must return a boolean value. If any of the called
384hooks returns true, then the event counts as being I<consumed>, and the 474hooks returns true, then the event counts as being I<consumed>, and the
385relevant action might not be carried out by the C++ code. 475relevant action might not be carried out by the C++ code.
398place. 488place.
399 489
400=item on_start $term 490=item on_start $term
401 491
402Called at the very end of initialisation of a new terminal, just before 492Called at the very end of initialisation of a new terminal, just before
403trying to map (display) the toplevel and returning to the mainloop. 493trying to map (display) the toplevel and returning to the main loop.
404 494
405=item on_destroy $term 495=item on_destroy $term
406 496
407Called whenever something tries to destroy terminal, when the terminal is 497Called whenever something tries to destroy terminal, when the terminal is
408still fully functional (not for long, though). 498still fully functional (not for long, though).
435 525
436Called whenever a selection has been copied, but before the selection is 526Called whenever a selection has been copied, but before the selection is
437requested from the server. The selection text can be queried and changed 527requested from the server. The selection text can be queried and changed
438by calling C<< $term->selection >>. 528by calling C<< $term->selection >>.
439 529
440Returning a true value aborts selection grabbing. It will still be hilighted. 530Returning a true value aborts selection grabbing. It will still be highlighted.
441 531
442=item on_sel_extend $term 532=item on_sel_extend $term
443 533
444Called whenever the user tries to extend the selection (e.g. with a double 534Called whenever the user tries to extend the selection (e.g. with a double
445click) and is either supposed to return false (normal operation), or 535click) and is either supposed to return false (normal operation), or
446should extend the selection itelf and return true to suppress the built-in 536should extend the selection itself and return true to suppress the built-in
447processing. This can happen multiple times, as long as the callback 537processing. This can happen multiple times, as long as the callback
448returns true, it will be called on every further click by the user and is 538returns true, it will be called on every further click by the user and is
449supposed to enlarge the selection more and more, if possible. 539supposed to enlarge the selection more and more, if possible.
450 540
451See the F<selection> example extension. 541See the F<selection> example extension.
452 542
453=item on_view_change $term, $offset 543=item on_view_change $term, $offset
454 544
455Called whenever the view offset changes, i..e the user or program 545Called whenever the view offset changes, i.e. the user or program
456scrolls. Offset C<0> means display the normal terminal, positive values 546scrolls. Offset C<0> means display the normal terminal, positive values
457show this many lines of scrollback. 547show this many lines of scrollback.
458 548
459=item on_scroll_back $term, $lines, $saved 549=item on_scroll_back $term, $lines, $saved
460 550
464 554
465It is called before lines are scrolled out (so rows 0 .. min ($lines - 1, 555It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
466$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total 556$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
467number of lines that will be in the scrollback buffer. 557number of lines that will be in the scrollback buffer.
468 558
559=item on_osc_seq $term, $op, $args
560
561Called on every OSC sequence and can be used to suppress it or modify its
562behaviour. The default should be to return an empty list. A true value
563suppresses execution of the request completely. Make sure you don't get
564confused by recursive invocations when you output an osc sequence within
565this callback.
566
567C<on_osc_seq_perl> should be used for new behaviour.
568
469=item on_osc_seq $term, $string 569=item on_osc_seq_perl $term, $string
470 570
471Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 571Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
472operating system command) is processed. Cursor position and other state 572operating system command) is processed. Cursor position and other state
473information is up-to-date when this happens. For interoperability, the 573information is up-to-date when this happens. For interoperability, the
474string should start with the extension name and a colon, to distinguish 574string should start with the extension name and a colon, to distinguish
475it from commands for other extensions, and this might be enforced in the 575it from commands for other extensions, and this might be enforced in the
476future. 576future.
477 577
478Be careful not ever to trust (in a security sense) the data you receive, 578Be careful not ever to trust (in a security sense) the data you receive,
479as its source can not easily be controleld (e-mail content, messages from 579as its source can not easily be controlled (e-mail content, messages from
480other users on the same system etc.). 580other users on the same system etc.).
481 581
482=item on_add_lines $term, $string 582=item on_add_lines $term, $string
483 583
484Called whenever text is about to be output, with the text as argument. You 584Called whenever text is about to be output, with the text as argument. You
517 617
518Called just after the screen gets redrawn. See C<on_refresh_begin>. 618Called just after the screen gets redrawn. See C<on_refresh_begin>.
519 619
520=item on_user_command $term, $string 620=item on_user_command $term, $string
521 621
522Called whenever the a user-configured event is being activated (e.g. via 622Called whenever a user-configured event is being activated (e.g. via
523a C<perl:string> action bound to a key, see description of the B<keysym> 623a C<perl:string> action bound to a key, see description of the B<keysym>
524resource in the @@RXVT_NAME@@(1) manpage). 624resource in the @@RXVT_NAME@@(1) manpage).
525 625
526The event is simply the action string. This interface is assumed to change 626The event is simply the action string. This interface is assumed to change
527slightly in the future. 627slightly in the future.
628
629=item on_resize_all_windows $tern, $new_width, $new_height
630
631Called just after the new window size has been calculated, but before
632windows are actually being resized or hints are being set. If this hook
633returns TRUE, setting of the window hints is being skipped.
528 634
529=item on_x_event $term, $event 635=item on_x_event $term, $event
530 636
531Called on every X event received on the vt window (and possibly other 637Called on every X event received on the vt window (and possibly other
532windows). Should only be used as a last resort. Most event structure 638windows). Should only be used as a last resort. Most event structure
533members are not passed. 639members are not passed.
534 640
641=item on_root_event $term, $event
642
643Like C<on_x_event>, but is called for events on the root window.
644
535=item on_focus_in $term 645=item on_focus_in $term
536 646
537Called whenever the window gets the keyboard focus, before rxvt-unicode 647Called whenever the window gets the keyboard focus, before rxvt-unicode
538does focus in processing. 648does focus in processing.
539 649
540=item on_focus_out $term 650=item on_focus_out $term
541 651
542Called wheneever the window loses keyboard focus, before rxvt-unicode does 652Called whenever the window loses keyboard focus, before rxvt-unicode does
543focus out processing. 653focus out processing.
544 654
545=item on_configure_notify $term, $event 655=item on_configure_notify $term, $event
546 656
547=item on_property_notify $term, $event 657=item on_property_notify $term, $event
630The current terminal. This variable stores the current C<urxvt::term> 740The current terminal. This variable stores the current C<urxvt::term>
631object, whenever a callback/hook is executing. 741object, whenever a callback/hook is executing.
632 742
633=item @urxvt::TERM_INIT 743=item @urxvt::TERM_INIT
634 744
635All coderefs in this array will be called as methods of the next newly 745All code references in this array will be called as methods of the next newly
636created C<urxvt::term> object (during the C<on_init> phase). The array 746created C<urxvt::term> object (during the C<on_init> phase). The array
637gets cleared before the codereferences that were in it are being executed, 747gets cleared before the code references that were in it are being executed,
638so coderefs can push themselves onto it again if they so desire. 748so references can push themselves onto it again if they so desire.
639 749
640This complements to the perl-eval commandline option, but gets executed 750This complements to the perl-eval command line option, but gets executed
641first. 751first.
642 752
643=item @urxvt::TERM_EXT 753=item @urxvt::TERM_EXT
644 754
645Works similar to C<@TERM_INIT>, but contains perl package/class names, which 755Works similar to C<@TERM_INIT>, but contains perl package/class names, which
666 776
667Using this function has the advantage that its output ends up in the 777Using this function has the advantage that its output ends up in the
668correct place, e.g. on stderr of the connecting urxvtc client. 778correct place, e.g. on stderr of the connecting urxvtc client.
669 779
670Messages have a size limit of 1023 bytes currently. 780Messages have a size limit of 1023 bytes currently.
781
782=item @terms = urxvt::termlist
783
784Returns all urxvt::term objects that exist in this process, regardless of
785whether they are started, being destroyed etc., so be careful. Only term
786objects that have perl extensions attached will be returned (because there
787is no urxvt::term objet associated with others).
671 788
672=item $time = urxvt::NOW 789=item $time = urxvt::NOW
673 790
674Returns the "current time" (as per the event loop). 791Returns the "current time" (as per the event loop).
675 792
733Return the foreground/background colour index, respectively. 850Return the foreground/background colour index, respectively.
734 851
735=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour 852=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
736 853
737=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour 854=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
855
856=item $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
738 857
739Replace the foreground/background colour in the rendition mask with the 858Replace the foreground/background colour in the rendition mask with the
740specified one. 859specified one.
741 860
742=item $value = urxvt::GET_CUSTOM $rend 861=item $value = urxvt::GET_CUSTOM $rend
833 } else { 952 } else {
834 $ext_arg{$_} ||= []; 953 $ext_arg{$_} ||= [];
835 } 954 }
836 } 955 }
837 956
838 while (my ($ext, $argv) = each %ext_arg) { 957 for my $ext (sort keys %ext_arg) {
839 my @files = grep -f $_, map "$_/$ext", @dirs; 958 my @files = grep -f $_, map "$_/$ext", @dirs;
840 959
841 if (@files) { 960 if (@files) {
842 $TERM->register_package (extension_package $files[0], $argv); 961 $TERM->register_package (extension_package $files[0], $ext_arg{$ext});
843 } else { 962 } else {
844 warn "perl extension '$ext' not found in perl library search path\n"; 963 warn "perl extension '$ext' not found in perl library search path\n";
845 } 964 }
846 } 965 }
847 966
853 972
854 if (my $cb = $TERM->{_hook}[$htype]) { 973 if (my $cb = $TERM->{_hook}[$htype]) {
855 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")" 974 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
856 if $verbosity >= 10; 975 if $verbosity >= 10;
857 976
858 keys %$cb; 977 for my $pkg (keys %$cb) {
859
860 while (my ($pkg, $cb) = each %$cb) {
861 my $retval_ = eval { $cb->($TERM->{_pkg}{$pkg}, @_) }; 978 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg}, @_) };
862 $retval ||= $retval_; 979 $retval ||= $retval_;
863 980
864 if ($@) { 981 if ($@) {
865 $TERM->ungrab; # better to lose the grab than the session 982 $TERM->ungrab; # better to lose the grab than the session
866 warn $@; 983 warn $@;
878 # clear package 995 # clear package
879 %$TERM = (); 996 %$TERM = ();
880 } 997 }
881 998
882 $retval 999 $retval
1000}
1001
1002sub SET_COLOR($$$) {
1003 SET_BGCOLOR (SET_FGCOLOR ($_[0], $_[1]), $_[2])
1004}
1005
1006sub rend2mask {
1007 no strict 'refs';
1008 my ($str, $mask) = (@_, 0);
1009 my %color = ( fg => undef, bg => undef );
1010 my @failed;
1011 for my $spec ( split /\s+/, $str ) {
1012 if ( $spec =~ /^([fb]g)[_:-]?(\d+)/i ) {
1013 $color{lc($1)} = $2;
1014 } else {
1015 my $neg = $spec =~ s/^[-^]//;
1016 unless ( exists &{"RS_$spec"} ) {
1017 push @failed, $spec;
1018 next;
1019 }
1020 my $cur = &{"RS_$spec"};
1021 if ( $neg ) {
1022 $mask &= ~$cur;
1023 } else {
1024 $mask |= $cur;
1025 }
1026 }
1027 }
1028 ($mask, @color{qw(fg bg)}, \@failed)
883} 1029}
884 1030
885# urxvt::term::extension 1031# urxvt::term::extension
886 1032
887package urxvt::term::extension; 1033package urxvt::term::extension;
1000sub DESTROY { 1146sub DESTROY {
1001 $_[0][1]->stop; 1147 $_[0][1]->stop;
1002} 1148}
1003 1149
1004sub condvar { 1150sub condvar {
1005 bless \my $flag, urxvt::anyevent::condvar:: 1151 bless \my $flag, urxvt::anyevent::
1006} 1152}
1007 1153
1008sub urxvt::anyevent::condvar::broadcast { 1154sub broadcast {
1009 ${$_[0]}++; 1155 ${$_[0]}++;
1010} 1156}
1011 1157
1012sub urxvt::anyevent::condvar::wait { 1158sub wait {
1013 unless (${$_[0]}) { 1159 unless (${$_[0]}) {
1014 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API"; 1160 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API";
1015 } 1161 }
1162}
1163
1164sub one_event {
1165 Carp::croak "AnyEvent->one_event blocking wait unsupported in urxvt, use a non-blocking API";
1016} 1166}
1017 1167
1018package urxvt::term; 1168package urxvt::term;
1019 1169
1020=head2 The C<urxvt::term> Class 1170=head2 The C<urxvt::term> Class
1056hash which defines the environment of the new terminal. 1206hash which defines the environment of the new terminal.
1057 1207
1058Croaks (and probably outputs an error message) if the new instance 1208Croaks (and probably outputs an error message) if the new instance
1059couldn't be created. Returns C<undef> if the new instance didn't 1209couldn't be created. Returns C<undef> if the new instance didn't
1060initialise perl, and the terminal object otherwise. The C<init> and 1210initialise perl, and the terminal object otherwise. The C<init> and
1061C<start> hooks will be called during this call. 1211C<start> hooks will be called before this call returns, and are free to
1212refer to global data (which is race free).
1062 1213
1063=cut 1214=cut
1064 1215
1065sub new { 1216sub new {
1066 my ($class, $env, @args) = @_; 1217 my ($class, $env, @args) = @_;
1067 1218
1219 $env or Carp::croak "environment hash missing in call to urxvt::term->new";
1220 @args or Carp::croak "name argument missing in call to urxvt::term->new";
1221
1068 _new ([ map "$_=$env->{$_}", keys %$env ], @args); 1222 _new ([ map "$_=$env->{$_}", keys %$env ], \@args);
1069} 1223}
1070 1224
1071=item $term->destroy 1225=item $term->destroy
1072 1226
1073Destroy the terminal object (close the window, free resources 1227Destroy the terminal object (close the window, free resources
1103 1257
1104Returns true if the option specified by C<$optval> is enabled, and 1258Returns true if the option specified by C<$optval> is enabled, and
1105optionally change it. All option values are stored by name in the hash 1259optionally change it. All option values are stored by name in the hash
1106C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash. 1260C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
1107 1261
1108Here is a a likely non-exhaustive list of option names, please see the 1262Here is a likely non-exhaustive list of option names, please see the
1109source file F</src/optinc.h> to see the actual list: 1263source file F</src/optinc.h> to see the actual list:
1110 1264
1111 borderLess console cursorBlink cursorUnderline hold iconic insecure 1265 borderLess console cursorBlink cursorUnderline hold iconic insecure
1112 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 1266 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
1113 override-redirect pastableTabs pointerBlank reverseVideo scrollBar 1267 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
1130likely change). 1284likely change).
1131 1285
1132Please note that resource strings will currently only be freed when the 1286Please note that resource strings will currently only be freed when the
1133terminal is destroyed, so changing options frequently will eat memory. 1287terminal is destroyed, so changing options frequently will eat memory.
1134 1288
1135Here is a a likely non-exhaustive list of resource names, not all of which 1289Here is a likely non-exhaustive list of resource names, not all of which
1136are supported in every build, please see the source file F</src/rsinc.h> 1290are supported in every build, please see the source file F</src/rsinc.h>
1137to see the actual list: 1291to see the actual list:
1138 1292
1139 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1293 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
1140 borderLess color cursorBlink cursorUnderline cutchars delete_key 1294 borderLess color cursorBlink cursorUnderline cutchars delete_key
1373Adds the specified events to the vt event mask. Useful e.g. when you want 1527Adds the specified events to the vt event mask. Useful e.g. when you want
1374to receive pointer events all the times: 1528to receive pointer events all the times:
1375 1529
1376 $term->vt_emask_add (urxvt::PointerMotionMask); 1530 $term->vt_emask_add (urxvt::PointerMotionMask);
1377 1531
1532=item $term->focus_in
1533
1534=item $term->focus_out
1535
1536=item $term->key_press ($state, $keycode[, $time])
1537
1538=item $term->key_release ($state, $keycode[, $time])
1539
1540Deliver various fake events to to terminal.
1541
1378=item $window_width = $term->width 1542=item $window_width = $term->width
1379 1543
1380=item $window_height = $term->height 1544=item $window_height = $term->height
1381 1545
1382=item $font_width = $term->fwidth 1546=item $font_width = $term->fwidth
1412=item $env = $term->env 1576=item $env = $term->env
1413 1577
1414Returns a copy of the environment in effect for the terminal as a hashref 1578Returns a copy of the environment in effect for the terminal as a hashref
1415similar to C<\%ENV>. 1579similar to C<\%ENV>.
1416 1580
1581=item @envv = $term->envv
1582
1583Returns the environment as array of strings of the form C<VAR=VALUE>.
1584
1585=item @argv = $term->argv
1586
1587Return the argument vector as this terminal, similar to @ARGV, but
1588includes the program name as first element.
1589
1417=cut 1590=cut
1418 1591
1419sub env { 1592sub env {
1420 if (my $env = $_[0]->_env) {
1421 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env } 1593 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), $_[0]->envv }
1422 } else {
1423 +{ %ENV }
1424 }
1425} 1594}
1426 1595
1427=item $modifiermask = $term->ModLevel3Mask 1596=item $modifiermask = $term->ModLevel3Mask
1428 1597
1429=item $modifiermask = $term->ModMetaMask 1598=item $modifiermask = $term->ModMetaMask
1437 1606
1438Returns the currently displayed screen (0 primary, 1 secondary). 1607Returns the currently displayed screen (0 primary, 1 secondary).
1439 1608
1440=item $cursor_is_hidden = $term->hidden_cursor 1609=item $cursor_is_hidden = $term->hidden_cursor
1441 1610
1442Returns wether the cursor is currently hidden or not. 1611Returns whether the cursor is currently hidden or not.
1443 1612
1444=item $view_start = $term->view_start ([$newvalue]) 1613=item $view_start = $term->view_start ([$newvalue])
1445 1614
1446Returns the row number of the topmost displayed line. Maximum value is 1615Returns the row number of the topmost displayed line. Maximum value is
1447C<0>, which displays the normal terminal contents. Lower values scroll 1616C<0>, which displays the normal terminal contents. Lower values scroll
1624where one character corresponds to one screen cell. See 1793where one character corresponds to one screen cell. See
1625C<< $term->ROW_t >> for details. 1794C<< $term->ROW_t >> for details.
1626 1795
1627=item $string = $term->special_decode $text 1796=item $string = $term->special_decode $text
1628 1797
1629Converts rxvt-unicodes text reprsentation into a perl string. See 1798Converts rxvt-unicodes text representation into a perl string. See
1630C<< $term->ROW_t >> for details. 1799C<< $term->ROW_t >> for details.
1631 1800
1632=item $success = $term->grab_button ($button, $modifiermask) 1801=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1633 1802
1803=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1804
1634Registers a synchronous button grab. See the XGrabButton manpage. 1805Register/unregister a synchronous button grab. See the XGrabButton
1806manpage.
1635 1807
1636=item $success = $term->grab ($eventtime[, $sync]) 1808=item $success = $term->grab ($eventtime[, $sync])
1637 1809
1638Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1810Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1639synchronous (C<$sync> is true). Also remembers the grab timestampe. 1811synchronous (C<$sync> is true). Also remembers the grab timestamp.
1640 1812
1641=item $term->allow_events_async 1813=item $term->allow_events_async
1642 1814
1643Calls XAllowEvents with AsyncBoth for the most recent grab. 1815Calls XAllowEvents with AsyncBoth for the most recent grab.
1644 1816
1757 my ($self, $text, $cb) = @_; 1929 my ($self, $text, $cb) = @_;
1758 1930
1759 $self->add_item ({ type => "button", text => $text, activate => $cb}); 1931 $self->add_item ({ type => "button", text => $text, activate => $cb});
1760} 1932}
1761 1933
1762=item $popup->add_toggle ($text, $cb, $initial_value) 1934=item $popup->add_toggle ($text, $initial_value, $cb)
1763 1935
1764Adds a toggle/checkbox item to the popup. Teh callback gets called 1936Adds a toggle/checkbox item to the popup. The callback gets called
1765whenever it gets toggled, with a boolean indicating its value as its first 1937whenever it gets toggled, with a boolean indicating its new value as its
1766argument. 1938first argument.
1767 1939
1768=cut 1940=cut
1769 1941
1770sub add_toggle { 1942sub add_toggle {
1771 my ($self, $text, $cb, $value) = @_; 1943 my ($self, $text, $value, $cb) = @_;
1772 1944
1773 my $item; $item = { 1945 my $item; $item = {
1774 type => "button", 1946 type => "button",
1775 text => " $text", 1947 text => " $text",
1776 value => $value, 1948 value => $value,
1817=back 1989=back
1818 1990
1819=cut 1991=cut
1820 1992
1821package urxvt::watcher; 1993package urxvt::watcher;
1822
1823@urxvt::timer::ISA = __PACKAGE__;
1824@urxvt::iow::ISA = __PACKAGE__;
1825@urxvt::pw::ISA = __PACKAGE__;
1826@urxvt::iw::ISA = __PACKAGE__;
1827 1994
1828=head2 The C<urxvt::timer> Class 1995=head2 The C<urxvt::timer> Class
1829 1996
1830This class implements timer watchers/events. Time is represented as a 1997This class implements timer watchers/events. Time is represented as a
1831fractional number of seconds since the epoch. Example: 1998fractional number of seconds since the epoch. Example:
1911Set the callback to be called when io events are triggered. C<$reventmask> 2078Set the callback to be called when io events are triggered. C<$reventmask>
1912is a bitset as described in the C<events> method. 2079is a bitset as described in the C<events> method.
1913 2080
1914=item $iow = $iow->fd ($fd) 2081=item $iow = $iow->fd ($fd)
1915 2082
1916Set the filedescriptor (not handle) to watch. 2083Set the file descriptor (not handle) to watch.
1917 2084
1918=item $iow = $iow->events ($eventmask) 2085=item $iow = $iow->events ($eventmask)
1919 2086
1920Set the event mask to watch. The only allowed values are 2087Set the event mask to watch. The only allowed values are
1921C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed 2088C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed
1925 2092
1926Start watching for requested events on the given handle. 2093Start watching for requested events on the given handle.
1927 2094
1928=item $iow = $iow->stop 2095=item $iow = $iow->stop
1929 2096
1930Stop watching for events on the given filehandle. 2097Stop watching for events on the given file handle.
1931 2098
1932=back 2099=back
1933 2100
1934=head2 The C<urxvt::iw> Class 2101=head2 The C<urxvt::iw> Class
1935 2102
1982 2149
1983Set the callback to be called when the timer triggers. 2150Set the callback to be called when the timer triggers.
1984 2151
1985=item $pw = $timer->start ($pid) 2152=item $pw = $timer->start ($pid)
1986 2153
1987Tells the wqtcher to start watching for process C<$pid>. 2154Tells the watcher to start watching for process C<$pid>.
1988 2155
1989=item $pw = $pw->stop 2156=item $pw = $pw->stop
1990 2157
1991Stop the watcher. 2158Stop the watcher.
1992 2159
2005 2172
2006=item >= 3 - script loading and management 2173=item >= 3 - script loading and management
2007 2174
2008=item >=10 - all called hooks 2175=item >=10 - all called hooks
2009 2176
2010=item >=11 - hook reutrn values 2177=item >=11 - hook return values
2011 2178
2012=back 2179=back
2013 2180
2014=head1 AUTHOR 2181=head1 AUTHOR
2015 2182
2017 http://software.schmorp.de/pkg/rxvt-unicode 2184 http://software.schmorp.de/pkg/rxvt-unicode
2018 2185
2019=cut 2186=cut
2020 2187
20211 21881
2189
2190# vim: sw=3:

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines