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.129 by root, Wed Jan 25 15:11:31 2006 UTC vs.
Revision 1.152 by tpope, Tue Jan 9 16:18:56 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
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.keysym.C-Delete: perl:matcher
266 URxvt.matcher.button: 1
267 URxvt.matcher.pattern.1: \\bwww\\.[\\w-]+\\.[\\w./?&@#-]*[\\w/-]
268 URxvt.matcher.pattern.2: \\B(/\\S+?):(\\d+)(?=:|$)
269 URxvt.matcher.launcher.2: gvim +$2 $1
216 270
217=item xim-onthespot 271=item xim-onthespot
218 272
219This (experimental) perl extension implements OnTheSpot editing. It does 273This (experimental) perl extension implements OnTheSpot editing. It does
220not work perfectly, and some input methods don't seem to work well with 274not 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 278You enable it by specifying this extension and a preedit style of
225C<OnTheSpot>, i.e.: 279C<OnTheSpot>, i.e.:
226 280
227 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot 281 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot
228 282
283=item kuake<hotkey>
284
285A very primitive quake-console-like extension. It was inspired by a
286description of how the programs C<kuake> and C<yakuake> work: Whenever the
287user presses a global accelerator key (by default C<F10>), the terminal
288will show or hide itself. Another press of the accelerator key will hide
289or show it again.
290
291Initially, the window will not be shown when using this extension.
292
293This is useful if you need a single terminal thats not using any desktop
294space most of the time but is quickly available at the press of a key.
295
296The accelerator key is grabbed regardless of any modifiers, so this
297extension will actually grab a physical key just for this function.
298
299If you want a quake-like animation, tell your window manager to do so
300(fvwm can do it).
301
229=item automove-background 302=item automove-background
230 303
231This is basically a one-line extension that dynamically changes the background pixmap offset 304This is basically a very small extension that dynamically changes the
232to the window position, in effect creating the same effect as pseudo transparency with 305background pixmap offset to the window position, in effect creating the
233a custom pixmap. No scaling is supported in this mode. Exmaple: 306same effect as pseudo transparency with a custom pixmap. No scaling is
307supported in this mode. Example:
234 308
235 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background 309 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background
236 310
237=item block-graphics-to-ascii 311=item block-graphics-to-ascii
238 312
239A not very useful example of filtering all text output to the terminal, 313A not very useful example of filtering all text output to the terminal
240by replacing all line-drawing characters (U+2500 .. U+259F) by a 314by replacing all line-drawing characters (U+2500 .. U+259F) by a
241similar-looking ascii character. 315similar-looking ascii character.
242 316
243=item digital-clock 317=item digital-clock
244 318
245Displays a digital clock using the built-in overlay. 319Displays a digital clock using the built-in overlay.
246 320
247=item remote-selection 321=item remote-clipboard
248 322
249Somewhat of a misnomer, this extension adds two menu entries to the 323Somewhat of a misnomer, this extension adds two menu entries to the
250selection popup that allows one ti run external commands to store the 324selection popup that allows one ti run external commands to store the
251selection somewhere and fetch it again. 325selection somewhere and fetch it again.
252 326
290After a successful upload the selection will be replaced by the text given 364After a successful upload the selection will be replaced by the text given
291in the C<selection-pastebin-url> resource (again, the % is the placeholder 365in the C<selection-pastebin-url> resource (again, the % is the placeholder
292for the filename): 366for the filename):
293 367
294 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/% 368 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
369
370I<Note to xrdb users:> xrdb uses the C preprocessor, which might interpret
371the double C</> characters as comment start. Use C<\057\057> instead,
372which works regardless of wether xrdb is used to parse the resource file
373or not.
295 374
296=item example-refresh-hooks 375=item example-refresh-hooks
297 376
298Displays a very simple digital clock in the upper right corner of the 377Displays a very simple digital clock in the upper right corner of the
299window. Illustrates overwriting the refresh callbacks to create your own 378window. Illustrates overwriting the refresh callbacks to create your own
339 418
340=back 419=back
341 420
342=head2 Extension Objects 421=head2 Extension Objects
343 422
344Very perl extension is a perl class. A separate perl object is created 423Every 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 424for 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 425which are passed as the first parameter to hooks. So extensions can use
347about other extensions, with the exception of methods and members that 426their C<$self> object without having to think about clashes with other
427extensions or other terminals, with the exception of methods and members
348begin with an underscore character C<_>: these are reserved for internal 428that begin with an underscore character C<_>: these are reserved for
349use. 429internal use.
350 430
351Although it isn't a C<urxvt::term> object, you can call all methods of the 431Although it isn't a C<urxvt::term> object, you can call all methods of the
352C<urxvt::term> class on this object. 432C<urxvt::term> class on this object.
353 433
354It has the following methods and data members: 434It has the following methods and data members:
375=head2 Hooks 455=head2 Hooks
376 456
377The following subroutines can be declared in extension files, and will be 457The following subroutines can be declared in extension files, and will be
378called whenever the relevant event happens. 458called whenever the relevant event happens.
379 459
380The first argument passed to them is an extension oject as described in 460The first argument passed to them is an extension object as described in
381the in the C<Extension Objects> section. 461the in the C<Extension Objects> section.
382 462
383B<All> of these hooks must return a boolean value. If any of the called 463B<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 464hooks returns true, then the event counts as being I<consumed>, and the
385relevant action might not be carried out by the C++ code. 465relevant action might not be carried out by the C++ code.
398place. 478place.
399 479
400=item on_start $term 480=item on_start $term
401 481
402Called at the very end of initialisation of a new terminal, just before 482Called at the very end of initialisation of a new terminal, just before
403trying to map (display) the toplevel and returning to the mainloop. 483trying to map (display) the toplevel and returning to the main loop.
404 484
405=item on_destroy $term 485=item on_destroy $term
406 486
407Called whenever something tries to destroy terminal, when the terminal is 487Called whenever something tries to destroy terminal, when the terminal is
408still fully functional (not for long, though). 488still fully functional (not for long, though).
435 515
436Called whenever a selection has been copied, but before the selection is 516Called whenever a selection has been copied, but before the selection is
437requested from the server. The selection text can be queried and changed 517requested from the server. The selection text can be queried and changed
438by calling C<< $term->selection >>. 518by calling C<< $term->selection >>.
439 519
440Returning a true value aborts selection grabbing. It will still be hilighted. 520Returning a true value aborts selection grabbing. It will still be highlighted.
441 521
442=item on_sel_extend $term 522=item on_sel_extend $term
443 523
444Called whenever the user tries to extend the selection (e.g. with a double 524Called whenever the user tries to extend the selection (e.g. with a double
445click) and is either supposed to return false (normal operation), or 525click) and is either supposed to return false (normal operation), or
446should extend the selection itelf and return true to suppress the built-in 526should extend the selection itself and return true to suppress the built-in
447processing. This can happen multiple times, as long as the callback 527processing. 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 528returns true, it will be called on every further click by the user and is
449supposed to enlarge the selection more and more, if possible. 529supposed to enlarge the selection more and more, if possible.
450 530
451See the F<selection> example extension. 531See the F<selection> example extension.
452 532
453=item on_view_change $term, $offset 533=item on_view_change $term, $offset
454 534
455Called whenever the view offset changes, i..e the user or program 535Called whenever the view offset changes, i.e. the user or program
456scrolls. Offset C<0> means display the normal terminal, positive values 536scrolls. Offset C<0> means display the normal terminal, positive values
457show this many lines of scrollback. 537show this many lines of scrollback.
458 538
459=item on_scroll_back $term, $lines, $saved 539=item on_scroll_back $term, $lines, $saved
460 540
464 544
465It is called before lines are scrolled out (so rows 0 .. min ($lines - 1, 545It 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 546$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
467number of lines that will be in the scrollback buffer. 547number of lines that will be in the scrollback buffer.
468 548
549=item on_osc_seq $term, $op, $args
550
551Called on every OSC sequence and can be used to suppress it or modify its
552behaviour. The default should be to return an empty list. A true value
553suppresses execution of the request completely. Make sure you don't get
554confused by recursive invocations when you output an osc sequence within
555this callback.
556
557C<on_osc_seq_perl> should be used for new behaviour.
558
469=item on_osc_seq $term, $string 559=item on_osc_seq_perl $term, $string
470 560
471Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 561Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
472operating system command) is processed. Cursor position and other state 562operating system command) is processed. Cursor position and other state
473information is up-to-date when this happens. For interoperability, the 563information is up-to-date when this happens. For interoperability, the
474string should start with the extension name and a colon, to distinguish 564string should start with the extension name and a colon, to distinguish
475it from commands for other extensions, and this might be enforced in the 565it from commands for other extensions, and this might be enforced in the
476future. 566future.
477 567
478Be careful not ever to trust (in a security sense) the data you receive, 568Be 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 569as its source can not easily be controlled (e-mail content, messages from
480other users on the same system etc.). 570other users on the same system etc.).
481 571
482=item on_add_lines $term, $string 572=item on_add_lines $term, $string
483 573
484Called whenever text is about to be output, with the text as argument. You 574Called whenever text is about to be output, with the text as argument. You
515 605
516=item on_refresh_end $term 606=item on_refresh_end $term
517 607
518Called just after the screen gets redrawn. See C<on_refresh_begin>. 608Called just after the screen gets redrawn. See C<on_refresh_begin>.
519 609
520=item on_keyboard_command $term, $string 610=item on_user_command $term, $string
521 611
522Called whenever the user presses a key combination that has a 612Called whenever a user-configured event is being activated (e.g. via
523C<perl:string> action bound to it (see description of the B<keysym> 613a C<perl:string> action bound to a key, see description of the B<keysym>
524resource in the @@RXVT_NAME@@(1) manpage). 614resource in the @@RXVT_NAME@@(1) manpage).
615
616The event is simply the action string. This interface is assumed to change
617slightly in the future.
618
619=item on_resize_all_windows $tern, $new_width, $new_height
620
621Called just after the new window size has been calculated, but before
622windows are actually being resized or hints are being set. If this hook
623returns TRUE, setting of the window hints is being skipped.
525 624
526=item on_x_event $term, $event 625=item on_x_event $term, $event
527 626
528Called on every X event received on the vt window (and possibly other 627Called on every X event received on the vt window (and possibly other
529windows). Should only be used as a last resort. Most event structure 628windows). Should only be used as a last resort. Most event structure
530members are not passed. 629members are not passed.
531 630
631=item on_root_event $term, $event
632
633Like C<on_x_event>, but is called for events on the root window.
634
532=item on_focus_in $term 635=item on_focus_in $term
533 636
534Called whenever the window gets the keyboard focus, before rxvt-unicode 637Called whenever the window gets the keyboard focus, before rxvt-unicode
535does focus in processing. 638does focus in processing.
536 639
537=item on_focus_out $term 640=item on_focus_out $term
538 641
539Called wheneever the window loses keyboard focus, before rxvt-unicode does 642Called whenever the window loses keyboard focus, before rxvt-unicode does
540focus out processing. 643focus out processing.
541 644
542=item on_configure_notify $term, $event 645=item on_configure_notify $term, $event
543 646
544=item on_property_notify $term, $event 647=item on_property_notify $term, $event
627The current terminal. This variable stores the current C<urxvt::term> 730The current terminal. This variable stores the current C<urxvt::term>
628object, whenever a callback/hook is executing. 731object, whenever a callback/hook is executing.
629 732
630=item @urxvt::TERM_INIT 733=item @urxvt::TERM_INIT
631 734
632All coderefs in this array will be called as methods of the next newly 735All code references in this array will be called as methods of the next newly
633created C<urxvt::term> object (during the C<on_init> phase). The array 736created C<urxvt::term> object (during the C<on_init> phase). The array
634gets cleared before the codereferences that were in it are being executed, 737gets cleared before the code references that were in it are being executed,
635so coderefs can push themselves onto it again if they so desire. 738so references can push themselves onto it again if they so desire.
636 739
637This complements to the perl-eval commandline option, but gets executed 740This complements to the perl-eval command line option, but gets executed
638first. 741first.
639 742
640=item @urxvt::TERM_EXT 743=item @urxvt::TERM_EXT
641 744
642Works similar to C<@TERM_INIT>, but contains perl package/class names, which 745Works similar to C<@TERM_INIT>, but contains perl package/class names, which
663 766
664Using this function has the advantage that its output ends up in the 767Using this function has the advantage that its output ends up in the
665correct place, e.g. on stderr of the connecting urxvtc client. 768correct place, e.g. on stderr of the connecting urxvtc client.
666 769
667Messages have a size limit of 1023 bytes currently. 770Messages have a size limit of 1023 bytes currently.
771
772=item @terms = urxvt::termlist
773
774Returns all urxvt::term objects that exist in this process, regardless of
775whether they are started, being destroyed etc., so be careful. Only term
776objects that have perl extensions attached will be returned (because there
777is no urxvt::term objet associated with others).
668 778
669=item $time = urxvt::NOW 779=item $time = urxvt::NOW
670 780
671Returns the "current time" (as per the event loop). 781Returns the "current time" (as per the event loop).
672 782
730Return the foreground/background colour index, respectively. 840Return the foreground/background colour index, respectively.
731 841
732=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour 842=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
733 843
734=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour 844=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
845
846=item $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
735 847
736Replace the foreground/background colour in the rendition mask with the 848Replace the foreground/background colour in the rendition mask with the
737specified one. 849specified one.
738 850
739=item $value = urxvt::GET_CUSTOM $rend 851=item $value = urxvt::GET_CUSTOM $rend
830 } else { 942 } else {
831 $ext_arg{$_} ||= []; 943 $ext_arg{$_} ||= [];
832 } 944 }
833 } 945 }
834 946
835 while (my ($ext, $argv) = each %ext_arg) { 947 for my $ext (sort keys %ext_arg) {
836 my @files = grep -f $_, map "$_/$ext", @dirs; 948 my @files = grep -f $_, map "$_/$ext", @dirs;
837 949
838 if (@files) { 950 if (@files) {
839 $TERM->register_package (extension_package $files[0], $argv); 951 $TERM->register_package (extension_package $files[0], $ext_arg{$ext});
840 } else { 952 } else {
841 warn "perl extension '$ext' not found in perl library search path\n"; 953 warn "perl extension '$ext' not found in perl library search path\n";
842 } 954 }
843 } 955 }
844 956
850 962
851 if (my $cb = $TERM->{_hook}[$htype]) { 963 if (my $cb = $TERM->{_hook}[$htype]) {
852 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")" 964 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
853 if $verbosity >= 10; 965 if $verbosity >= 10;
854 966
855 keys %$cb; 967 for my $pkg (keys %$cb) {
856
857 while (my ($pkg, $cb) = each %$cb) {
858 my $retval_ = eval { $cb->($TERM->{_pkg}{$pkg}, @_) }; 968 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg}, @_) };
859 $retval ||= $retval_; 969 $retval ||= $retval_;
860 970
861 if ($@) { 971 if ($@) {
862 $TERM->ungrab; # better to lose the grab than the session 972 $TERM->ungrab; # better to lose the grab than the session
863 warn $@; 973 warn $@;
875 # clear package 985 # clear package
876 %$TERM = (); 986 %$TERM = ();
877 } 987 }
878 988
879 $retval 989 $retval
990}
991
992sub SET_COLOR($$$) {
993 SET_BGCOLOR (SET_FGCOLOR ($_[0], $_[1]), $_[2])
994}
995
996sub rend2mask {
997 no strict 'refs';
998 my ($str, $mask) = (@_, 0);
999 my %color = ( fg => undef, bg => undef );
1000 my @failed;
1001 for my $spec ( split /\s+/, $str ) {
1002 if ( $spec =~ /^([fb]g)[_:-]?(\d+)/i ) {
1003 $color{lc($1)} = $2;
1004 } else {
1005 my $neg = $spec =~ s/^[-^]//;
1006 unless ( exists &{"RS_$spec"} ) {
1007 push @failed, $spec;
1008 next;
1009 }
1010 my $cur = &{"RS_$spec"};
1011 if ( $neg ) {
1012 $mask &= ~$cur;
1013 } else {
1014 $mask |= $cur;
1015 }
1016 }
1017 }
1018 ($mask, @color{qw(fg bg)}, \@failed)
880} 1019}
881 1020
882# urxvt::term::extension 1021# urxvt::term::extension
883 1022
884package urxvt::term::extension; 1023package urxvt::term::extension;
997sub DESTROY { 1136sub DESTROY {
998 $_[0][1]->stop; 1137 $_[0][1]->stop;
999} 1138}
1000 1139
1001sub condvar { 1140sub condvar {
1002 bless \my $flag, urxvt::anyevent::condvar:: 1141 bless \my $flag, urxvt::anyevent::
1003} 1142}
1004 1143
1005sub urxvt::anyevent::condvar::broadcast { 1144sub broadcast {
1006 ${$_[0]}++; 1145 ${$_[0]}++;
1007} 1146}
1008 1147
1009sub urxvt::anyevent::condvar::wait { 1148sub wait {
1010 unless (${$_[0]}) { 1149 unless (${$_[0]}) {
1011 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API"; 1150 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API";
1012 } 1151 }
1152}
1153
1154sub one_event {
1155 Carp::croak "AnyEvent->one_event blocking wait unsupported in urxvt, use a non-blocking API";
1013} 1156}
1014 1157
1015package urxvt::term; 1158package urxvt::term;
1016 1159
1017=head2 The C<urxvt::term> Class 1160=head2 The C<urxvt::term> Class
1053hash which defines the environment of the new terminal. 1196hash which defines the environment of the new terminal.
1054 1197
1055Croaks (and probably outputs an error message) if the new instance 1198Croaks (and probably outputs an error message) if the new instance
1056couldn't be created. Returns C<undef> if the new instance didn't 1199couldn't be created. Returns C<undef> if the new instance didn't
1057initialise perl, and the terminal object otherwise. The C<init> and 1200initialise perl, and the terminal object otherwise. The C<init> and
1058C<start> hooks will be called during this call. 1201C<start> hooks will be called before this call returns, and are free to
1202refer to global data (which is race free).
1059 1203
1060=cut 1204=cut
1061 1205
1062sub new { 1206sub new {
1063 my ($class, $env, @args) = @_; 1207 my ($class, $env, @args) = @_;
1064 1208
1209 $env or Carp::croak "environment hash missing in call to urxvt::term->new";
1210 @args or Carp::croak "name argument missing in call to urxvt::term->new";
1211
1065 _new ([ map "$_=$env->{$_}", keys %$env ], @args); 1212 _new ([ map "$_=$env->{$_}", keys %$env ], \@args);
1066} 1213}
1067 1214
1068=item $term->destroy 1215=item $term->destroy
1069 1216
1070Destroy the terminal object (close the window, free resources 1217Destroy the terminal object (close the window, free resources
1100 1247
1101Returns true if the option specified by C<$optval> is enabled, and 1248Returns true if the option specified by C<$optval> is enabled, and
1102optionally change it. All option values are stored by name in the hash 1249optionally change it. All option values are stored by name in the hash
1103C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash. 1250C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
1104 1251
1105Here is a a likely non-exhaustive list of option names, please see the 1252Here is a likely non-exhaustive list of option names, please see the
1106source file F</src/optinc.h> to see the actual list: 1253source file F</src/optinc.h> to see the actual list:
1107 1254
1108 borderLess console cursorBlink cursorUnderline hold iconic insecure 1255 borderLess console cursorBlink cursorUnderline hold iconic insecure
1109 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 1256 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
1110 override-redirect pastableTabs pointerBlank reverseVideo scrollBar 1257 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
1127likely change). 1274likely change).
1128 1275
1129Please note that resource strings will currently only be freed when the 1276Please note that resource strings will currently only be freed when the
1130terminal is destroyed, so changing options frequently will eat memory. 1277terminal is destroyed, so changing options frequently will eat memory.
1131 1278
1132Here is a a likely non-exhaustive list of resource names, not all of which 1279Here is a likely non-exhaustive list of resource names, not all of which
1133are supported in every build, please see the source file F</src/rsinc.h> 1280are supported in every build, please see the source file F</src/rsinc.h>
1134to see the actual list: 1281to see the actual list:
1135 1282
1136 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1283 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
1137 borderLess color cursorBlink cursorUnderline cutchars delete_key 1284 borderLess color cursorBlink cursorUnderline cutchars delete_key
1370Adds the specified events to the vt event mask. Useful e.g. when you want 1517Adds the specified events to the vt event mask. Useful e.g. when you want
1371to receive pointer events all the times: 1518to receive pointer events all the times:
1372 1519
1373 $term->vt_emask_add (urxvt::PointerMotionMask); 1520 $term->vt_emask_add (urxvt::PointerMotionMask);
1374 1521
1522=item $term->focus_in
1523
1524=item $term->focus_out
1525
1526=item $term->key_press ($state, $keycode[, $time])
1527
1528=item $term->key_release ($state, $keycode[, $time])
1529
1530Deliver various fake events to to terminal.
1531
1375=item $window_width = $term->width 1532=item $window_width = $term->width
1376 1533
1377=item $window_height = $term->height 1534=item $window_height = $term->height
1378 1535
1379=item $font_width = $term->fwidth 1536=item $font_width = $term->fwidth
1409=item $env = $term->env 1566=item $env = $term->env
1410 1567
1411Returns a copy of the environment in effect for the terminal as a hashref 1568Returns a copy of the environment in effect for the terminal as a hashref
1412similar to C<\%ENV>. 1569similar to C<\%ENV>.
1413 1570
1571=item @envv = $term->envv
1572
1573Returns the environment as array of strings of the form C<VAR=VALUE>.
1574
1575=item @argv = $term->argv
1576
1577Return the argument vector as this terminal, similar to @ARGV, but
1578includes the program name as first element.
1579
1414=cut 1580=cut
1415 1581
1416sub env { 1582sub env {
1417 if (my $env = $_[0]->_env) {
1418 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env } 1583 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), $_[0]->envv }
1419 } else {
1420 +{ %ENV }
1421 }
1422} 1584}
1423 1585
1424=item $modifiermask = $term->ModLevel3Mask 1586=item $modifiermask = $term->ModLevel3Mask
1425 1587
1426=item $modifiermask = $term->ModMetaMask 1588=item $modifiermask = $term->ModMetaMask
1434 1596
1435Returns the currently displayed screen (0 primary, 1 secondary). 1597Returns the currently displayed screen (0 primary, 1 secondary).
1436 1598
1437=item $cursor_is_hidden = $term->hidden_cursor 1599=item $cursor_is_hidden = $term->hidden_cursor
1438 1600
1439Returns wether the cursor is currently hidden or not. 1601Returns whether the cursor is currently hidden or not.
1440 1602
1441=item $view_start = $term->view_start ([$newvalue]) 1603=item $view_start = $term->view_start ([$newvalue])
1442 1604
1443Returns the row number of the topmost displayed line. Maximum value is 1605Returns the row number of the topmost displayed line. Maximum value is
1444C<0>, which displays the normal terminal contents. Lower values scroll 1606C<0>, which displays the normal terminal contents. Lower values scroll
1621where one character corresponds to one screen cell. See 1783where one character corresponds to one screen cell. See
1622C<< $term->ROW_t >> for details. 1784C<< $term->ROW_t >> for details.
1623 1785
1624=item $string = $term->special_decode $text 1786=item $string = $term->special_decode $text
1625 1787
1626Converts rxvt-unicodes text reprsentation into a perl string. See 1788Converts rxvt-unicodes text representation into a perl string. See
1627C<< $term->ROW_t >> for details. 1789C<< $term->ROW_t >> for details.
1628 1790
1629=item $success = $term->grab_button ($button, $modifiermask) 1791=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1630 1792
1793=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1794
1631Registers a synchronous button grab. See the XGrabButton manpage. 1795Register/unregister a synchronous button grab. See the XGrabButton
1796manpage.
1632 1797
1633=item $success = $term->grab ($eventtime[, $sync]) 1798=item $success = $term->grab ($eventtime[, $sync])
1634 1799
1635Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1800Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1636synchronous (C<$sync> is true). Also remembers the grab timestampe. 1801synchronous (C<$sync> is true). Also remembers the grab timestamp.
1637 1802
1638=item $term->allow_events_async 1803=item $term->allow_events_async
1639 1804
1640Calls XAllowEvents with AsyncBoth for the most recent grab. 1805Calls XAllowEvents with AsyncBoth for the most recent grab.
1641 1806
1754 my ($self, $text, $cb) = @_; 1919 my ($self, $text, $cb) = @_;
1755 1920
1756 $self->add_item ({ type => "button", text => $text, activate => $cb}); 1921 $self->add_item ({ type => "button", text => $text, activate => $cb});
1757} 1922}
1758 1923
1759=item $popup->add_toggle ($text, $cb, $initial_value) 1924=item $popup->add_toggle ($text, $initial_value, $cb)
1760 1925
1761Adds a toggle/checkbox item to the popup. Teh callback gets called 1926Adds a toggle/checkbox item to the popup. The callback gets called
1762whenever it gets toggled, with a boolean indicating its value as its first 1927whenever it gets toggled, with a boolean indicating its new value as its
1763argument. 1928first argument.
1764 1929
1765=cut 1930=cut
1766 1931
1767sub add_toggle { 1932sub add_toggle {
1768 my ($self, $text, $cb, $value) = @_; 1933 my ($self, $text, $value, $cb) = @_;
1769 1934
1770 my $item; $item = { 1935 my $item; $item = {
1771 type => "button", 1936 type => "button",
1772 text => " $text", 1937 text => " $text",
1773 value => $value, 1938 value => $value,
1814=back 1979=back
1815 1980
1816=cut 1981=cut
1817 1982
1818package urxvt::watcher; 1983package urxvt::watcher;
1819
1820@urxvt::timer::ISA = __PACKAGE__;
1821@urxvt::iow::ISA = __PACKAGE__;
1822@urxvt::pw::ISA = __PACKAGE__;
1823@urxvt::iw::ISA = __PACKAGE__;
1824 1984
1825=head2 The C<urxvt::timer> Class 1985=head2 The C<urxvt::timer> Class
1826 1986
1827This class implements timer watchers/events. Time is represented as a 1987This class implements timer watchers/events. Time is represented as a
1828fractional number of seconds since the epoch. Example: 1988fractional number of seconds since the epoch. Example:
1908Set the callback to be called when io events are triggered. C<$reventmask> 2068Set the callback to be called when io events are triggered. C<$reventmask>
1909is a bitset as described in the C<events> method. 2069is a bitset as described in the C<events> method.
1910 2070
1911=item $iow = $iow->fd ($fd) 2071=item $iow = $iow->fd ($fd)
1912 2072
1913Set the filedescriptor (not handle) to watch. 2073Set the file descriptor (not handle) to watch.
1914 2074
1915=item $iow = $iow->events ($eventmask) 2075=item $iow = $iow->events ($eventmask)
1916 2076
1917Set the event mask to watch. The only allowed values are 2077Set the event mask to watch. The only allowed values are
1918C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed 2078C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed
1922 2082
1923Start watching for requested events on the given handle. 2083Start watching for requested events on the given handle.
1924 2084
1925=item $iow = $iow->stop 2085=item $iow = $iow->stop
1926 2086
1927Stop watching for events on the given filehandle. 2087Stop watching for events on the given file handle.
1928 2088
1929=back 2089=back
1930 2090
1931=head2 The C<urxvt::iw> Class 2091=head2 The C<urxvt::iw> Class
1932 2092
1979 2139
1980Set the callback to be called when the timer triggers. 2140Set the callback to be called when the timer triggers.
1981 2141
1982=item $pw = $timer->start ($pid) 2142=item $pw = $timer->start ($pid)
1983 2143
1984Tells the wqtcher to start watching for process C<$pid>. 2144Tells the watcher to start watching for process C<$pid>.
1985 2145
1986=item $pw = $pw->stop 2146=item $pw = $pw->stop
1987 2147
1988Stop the watcher. 2148Stop the watcher.
1989 2149
2002 2162
2003=item >= 3 - script loading and management 2163=item >= 3 - script loading and management
2004 2164
2005=item >=10 - all called hooks 2165=item >=10 - all called hooks
2006 2166
2007=item >=11 - hook reutrn values 2167=item >=11 - hook return values
2008 2168
2009=back 2169=back
2010 2170
2011=head1 AUTHOR 2171=head1 AUTHOR
2012 2172
2014 http://software.schmorp.de/pkg/rxvt-unicode 2174 http://software.schmorp.de/pkg/rxvt-unicode
2015 2175
2016=cut 2176=cut
2017 2177
20181 21781
2179
2180# vim: sw=3:

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines