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.142 by root, Thu Jul 6 18:56:10 2006 UTC vs.
Revision 1.169 by root, Sun Jun 15 14:54:44 2008 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 30
31You can disable the embedded perl interpreter by setting both "perl-ext"
32and "perl-ext-common" resources to the empty string.
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/>.
35 38
37 40
38 @@RXVT_NAME@@ -pe <extensionname> 41 @@RXVT_NAME@@ -pe <extensionname>
39 42
40Or by adding them to the resource for extensions loaded by default: 43Or by adding them to the resource for extensions loaded by default:
41 44
42 URxvt.perl-ext-common: default,automove-background,selection-autotransform 45 URxvt.perl-ext-common: default,selection-autotransform
43 46
44=over 4 47=over 4
45 48
46=item selection (enabled by default) 49=item selection (enabled by default)
47 50
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
98 101
99Other extensions can extend this popup menu by pushing a code reference 102Other extensions can extend this popup menu by pushing a code reference
100onto C<@{ $term->{option_popup_hook} }>, which gets called whenever the 103onto C<@{ $term->{option_popup_hook} }>, which gets called whenever the
101popup is being displayed. 104popup is being displayed.
102 105
103It's sole argument is the popup menu, which can be modified. It should 106Its 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 107either 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 108reference. 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 109will be called when the toggle changes, with the new boolean value as
107first argument. 110first argument.
108 111
121 124
122Other extensions can extend this popup menu by pushing a code reference 125Other extensions can extend this popup menu by pushing a code reference
123onto C<@{ $term->{selection_popup_hook} }>, which gets called whenever the 126onto C<@{ $term->{selection_popup_hook} }>, which gets called whenever the
124popup is being displayed. 127popup is being displayed.
125 128
126It's sole argument is the popup menu, which can be modified. The selection 129Its sole argument is the popup menu, which can be modified. The selection
127is 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.
128It 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
129string 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
130when the button gets activated and should transform C<$_>. 133when the button gets activated and should transform C<$_>.
131 134
132The 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
133the selection to C<b>s, but only if the selection currently contains any 136the selection to C<b>s, but only if the selection currently contains any
134C<a>s: 137C<a>s:
135 138
136 push @{ $self->{term}{selection_popup_hook} }, sub { 139 push @{ $self->{term}{selection_popup_hook} }, sub {
137 /a/ ? ("a to be" => sub { s/a/b/g } 140 /a/ ? ("a to b" => sub { s/a/b/g }
138 : () 141 : ()
139 }; 142 };
140 143
141=item searchable-scrollback<hotkey> (enabled by default) 144=item searchable-scrollback<hotkey> (enabled by default)
142 145
149search. 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>
150search upwards/downwards in the scrollback buffer, C<End> jumps to the 153search upwards/downwards in the scrollback buffer, C<End> jumps to the
151bottom. 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
152was 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
153additionally stores the first match in the current line into the primary 156additionally stores the first match in the current line into the primary
154selection. 157selection if the C<Shift> modifier is active.
155 158
156The regex defaults to "(?i)", resulting in a case-insensitive search. To 159The regex defaults to "(?i)", resulting in a case-insensitive search. To
157get a case-sensitive search you can delete this prefix using C<BackSpace> 160get a case-sensitive search you can delete this prefix using C<BackSpace>
158or simply use an uppercase character which removes the "(?i)" prefix. 161or simply use an uppercase character which removes the "(?i)" prefix.
159 162
162=item readline (enabled by default) 165=item readline (enabled by default)
163 166
164A support package that tries to make editing with readline easier. At 167A support package that tries to make editing with readline easier. At
165the moment, it reacts to clicking shift-left mouse button by trying to 168the moment, it reacts to clicking shift-left mouse button by trying to
166move 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
167cursor-left or cursor-right keypresses as required (the this only works 170cursor-left or cursor-right keypresses as required (this only works
168for programs that correctly support wide characters). 171for programs that correctly support wide characters).
169 172
170To avoid too many false positives, this is only done when: 173To avoid too many false positives, this is only done when:
171 174
172=over 4 175=over 4
220the message into vi commands to load the file. 223the message into vi commands to load the file.
221 224
222=item tabbed 225=item tabbed
223 226
224This transforms the terminal into a tabbar with additional terminals, that 227This transforms the terminal into a tabbar with additional terminals, that
225is, 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
226displays 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
227button per tab. 230button per tab.
228 231
229Clicking a button will activate that tab. Pressing B<Shift-Left> and 232Clicking a button will activate that tab. Pressing B<Shift-Left> and
230B<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,
240 URxvt.tabbed.tab-bg: <colour-index, default 1> 243 URxvt.tabbed.tab-bg: <colour-index, default 1>
241 244
242See I<COLOR AND GRAPHICS> in the @@RXVT_NAME@@(1) manpage for valid 245See I<COLOR AND GRAPHICS> in the @@RXVT_NAME@@(1) manpage for valid
243indices. 246indices.
244 247
245=item mark-urls 248=item matcher
246 249
247Uses per-line display filtering (C<on_line_update>) to underline urls and 250Uses per-line display filtering (C<on_line_update>) to underline text
248make them clickable. When middle-clicked, the program specified in the 251matching a certain pattern and make it clickable. When clicked with the
249resource C<urlLauncher> (default C<x-www-browser>) will be started with 252mouse button specified in the C<matcher.button> resource (default 2, or
250the 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
251 276
252=item xim-onthespot 277=item xim-onthespot
253 278
254This (experimental) perl extension implements OnTheSpot editing. It does 279This (experimental) perl extension implements OnTheSpot editing. It does
255not 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
256OnTheSpot editing in general, but it seems to work at leats for SCIM and 281OnTheSpot editing in general, but it seems to work at least for SCIM and
257kinput2. 282kinput2.
258 283
259You enable it by specifying this extension and a preedit style of 284You enable it by specifying this extension and a preedit style of
260C<OnTheSpot>, i.e.: 285C<OnTheSpot>, i.e.:
261 286
262 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot 287 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot
263 288
264=item automove-background 289=item kuake<hotkey>
265 290
266This is basically a very small extension that dynamically changes the 291A very primitive quake-console-like extension. It was inspired by a
267background pixmap offset to the window position, in effect creating the 292description of how the programs C<kuake> and C<yakuake> work: Whenever the
268same effect as pseudo transparency with a custom pixmap. No scaling is 293user presses a global accelerator key (by default C<F10>), the terminal
269supported in this mode. Exmaple: 294will show or hide itself. Another press of the accelerator key will hide
295or show it again.
270 296
271 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background 297Initially, the window will not be shown when using this extension.
298
299This is useful if you need a single terminal that is 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).
272 307
273=item block-graphics-to-ascii 308=item block-graphics-to-ascii
274 309
275A not very useful example of filtering all text output to the terminal 310A not very useful example of filtering all text output to the terminal
276by replacing all line-drawing characters (U+2500 .. U+259F) by a 311by replacing all line-drawing characters (U+2500 .. U+259F) by a
281Displays a digital clock using the built-in overlay. 316Displays a digital clock using the built-in overlay.
282 317
283=item remote-clipboard 318=item remote-clipboard
284 319
285Somewhat of a misnomer, this extension adds two menu entries to the 320Somewhat of a misnomer, this extension adds two menu entries to the
286selection popup that allows one ti run external commands to store the 321selection popup that allows one to run external commands to store the
287selection somewhere and fetch it again. 322selection somewhere and fetch it again.
288 323
289We use it to implement a "distributed selection mechanism", which just 324We use it to implement a "distributed selection mechanism", which just
290means that one command uploads the file to a remote server, and another 325means that one command uploads the file to a remote server, and another
291reads it. 326reads it.
326After a successful upload the selection will be replaced by the text given 361After a successful upload the selection will be replaced by the text given
327in the C<selection-pastebin-url> resource (again, the % is the placeholder 362in the C<selection-pastebin-url> resource (again, the % is the placeholder
328for the filename): 363for the filename):
329 364
330 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/% 365 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
366
367I<Note to xrdb users:> xrdb uses the C preprocessor, which might interpret
368the double C</> characters as comment start. Use C<\057\057> instead,
369which works regardless of wether xrdb is used to parse the resource file
370or not.
331 371
332=item example-refresh-hooks 372=item example-refresh-hooks
333 373
334Displays a very simple digital clock in the upper right corner of the 374Displays a very simple digital clock in the upper right corner of the
335window. Illustrates overwriting the refresh callbacks to create your own 375window. Illustrates overwriting the refresh callbacks to create your own
376=back 416=back
377 417
378=head2 Extension Objects 418=head2 Extension Objects
379 419
380Every perl extension is a perl class. A separate perl object is created 420Every perl extension is a perl class. A separate perl object is created
381for each terminal and each extension and passed as the first parameter to 421for each terminal, and each terminal has its own set of extenion objects,
382hooks. So extensions can use their C<$self> object without having to think 422which are passed as the first parameter to hooks. So extensions can use
383about other extensions, with the exception of methods and members that 423their C<$self> object without having to think about clashes with other
424extensions or other terminals, with the exception of methods and members
384begin with an underscore character C<_>: these are reserved for internal 425that begin with an underscore character C<_>: these are reserved for
385use. 426internal use.
386 427
387Although it isn't a C<urxvt::term> object, you can call all methods of the 428Although it isn't a C<urxvt::term> object, you can call all methods of the
388C<urxvt::term> class on this object. 429C<urxvt::term> class on this object.
389 430
390It has the following methods and data members: 431It has the following methods and data members:
411=head2 Hooks 452=head2 Hooks
412 453
413The following subroutines can be declared in extension files, and will be 454The following subroutines can be declared in extension files, and will be
414called whenever the relevant event happens. 455called whenever the relevant event happens.
415 456
416The first argument passed to them is an extension oject as described in 457The first argument passed to them is an extension object as described in
417the in the C<Extension Objects> section. 458the in the C<Extension Objects> section.
418 459
419B<All> of these hooks must return a boolean value. If any of the called 460B<All> of these hooks must return a boolean value. If any of the called
420hooks returns true, then the event counts as being I<consumed>, and the 461hooks returns true, then the event counts as being I<consumed>, and the
421relevant action might not be carried out by the C++ code. 462relevant action might not be carried out by the C++ code.
434place. 475place.
435 476
436=item on_start $term 477=item on_start $term
437 478
438Called at the very end of initialisation of a new terminal, just before 479Called at the very end of initialisation of a new terminal, just before
439trying to map (display) the toplevel and returning to the mainloop. 480trying to map (display) the toplevel and returning to the main loop.
440 481
441=item on_destroy $term 482=item on_destroy $term
442 483
443Called whenever something tries to destroy terminal, when the terminal is 484Called whenever something tries to destroy terminal, when the terminal is
444still fully functional (not for long, though). 485still fully functional (not for long, though).
471 512
472Called whenever a selection has been copied, but before the selection is 513Called whenever a selection has been copied, but before the selection is
473requested from the server. The selection text can be queried and changed 514requested from the server. The selection text can be queried and changed
474by calling C<< $term->selection >>. 515by calling C<< $term->selection >>.
475 516
476Returning a true value aborts selection grabbing. It will still be hilighted. 517Returning a true value aborts selection grabbing. It will still be highlighted.
477 518
478=item on_sel_extend $term 519=item on_sel_extend $term
479 520
480Called whenever the user tries to extend the selection (e.g. with a double 521Called whenever the user tries to extend the selection (e.g. with a double
481click) and is either supposed to return false (normal operation), or 522click) and is either supposed to return false (normal operation), or
482should extend the selection itelf and return true to suppress the built-in 523should extend the selection itself and return true to suppress the built-in
483processing. This can happen multiple times, as long as the callback 524processing. This can happen multiple times, as long as the callback
484returns true, it will be called on every further click by the user and is 525returns true, it will be called on every further click by the user and is
485supposed to enlarge the selection more and more, if possible. 526supposed to enlarge the selection more and more, if possible.
486 527
487See the F<selection> example extension. 528See the F<selection> example extension.
488 529
489=item on_view_change $term, $offset 530=item on_view_change $term, $offset
490 531
491Called whenever the view offset changes, i..e the user or program 532Called whenever the view offset changes, i.e. the user or program
492scrolls. Offset C<0> means display the normal terminal, positive values 533scrolls. Offset C<0> means display the normal terminal, positive values
493show this many lines of scrollback. 534show this many lines of scrollback.
494 535
495=item on_scroll_back $term, $lines, $saved 536=item on_scroll_back $term, $lines, $saved
496 537
520string should start with the extension name and a colon, to distinguish 561string should start with the extension name and a colon, to distinguish
521it from commands for other extensions, and this might be enforced in the 562it from commands for other extensions, and this might be enforced in the
522future. 563future.
523 564
524Be careful not ever to trust (in a security sense) the data you receive, 565Be careful not ever to trust (in a security sense) the data you receive,
525as its source can not easily be controleld (e-mail content, messages from 566as its source can not easily be controlled (e-mail content, messages from
526other users on the same system etc.). 567other users on the same system etc.).
527 568
528=item on_add_lines $term, $string 569=item on_add_lines $term, $string
529 570
530Called whenever text is about to be output, with the text as argument. You 571Called whenever text is about to be output, with the text as argument. You
563 604
564Called just after the screen gets redrawn. See C<on_refresh_begin>. 605Called just after the screen gets redrawn. See C<on_refresh_begin>.
565 606
566=item on_user_command $term, $string 607=item on_user_command $term, $string
567 608
568Called whenever the a user-configured event is being activated (e.g. via 609Called whenever a user-configured event is being activated (e.g. via
569a C<perl:string> action bound to a key, see description of the B<keysym> 610a C<perl:string> action bound to a key, see description of the B<keysym>
570resource in the @@RXVT_NAME@@(1) manpage). 611resource in the @@RXVT_NAME@@(1) manpage).
571 612
572The event is simply the action string. This interface is assumed to change 613The event is simply the action string. This interface is assumed to change
573slightly in the future. 614slightly in the future.
574 615
575=item on_resize_all_windows $tern, $new_width, $new_height 616=item on_resize_all_windows $tern, $new_width, $new_height
576 617
577Called just after the new window size has been calculcated, but before 618Called just after the new window size has been calculated, but before
578windows are actually being resized or hints are being set. If this hook 619windows are actually being resized or hints are being set. If this hook
579returns TRUE, setting of the window hints is being skipped. 620returns TRUE, setting of the window hints is being skipped.
580 621
581=item on_x_event $term, $event 622=item on_x_event $term, $event
582 623
583Called on every X event received on the vt window (and possibly other 624Called on every X event received on the vt window (and possibly other
584windows). Should only be used as a last resort. Most event structure 625windows). Should only be used as a last resort. Most event structure
585members are not passed. 626members are not passed.
586 627
628=item on_root_event $term, $event
629
630Like C<on_x_event>, but is called for events on the root window.
631
587=item on_focus_in $term 632=item on_focus_in $term
588 633
589Called whenever the window gets the keyboard focus, before rxvt-unicode 634Called whenever the window gets the keyboard focus, before rxvt-unicode
590does focus in processing. 635does focus in processing.
591 636
592=item on_focus_out $term 637=item on_focus_out $term
593 638
594Called wheneever the window loses keyboard focus, before rxvt-unicode does 639Called whenever the window loses keyboard focus, before rxvt-unicode does
595focus out processing. 640focus out processing.
596 641
597=item on_configure_notify $term, $event 642=item on_configure_notify $term, $event
598 643
599=item on_property_notify $term, $event 644=item on_property_notify $term, $event
682The current terminal. This variable stores the current C<urxvt::term> 727The current terminal. This variable stores the current C<urxvt::term>
683object, whenever a callback/hook is executing. 728object, whenever a callback/hook is executing.
684 729
685=item @urxvt::TERM_INIT 730=item @urxvt::TERM_INIT
686 731
687All coderefs in this array will be called as methods of the next newly 732All code references in this array will be called as methods of the next newly
688created C<urxvt::term> object (during the C<on_init> phase). The array 733created C<urxvt::term> object (during the C<on_init> phase). The array
689gets cleared before the codereferences that were in it are being executed, 734gets cleared before the code references that were in it are being executed,
690so coderefs can push themselves onto it again if they so desire. 735so references can push themselves onto it again if they so desire.
691 736
692This complements to the perl-eval commandline option, but gets executed 737This complements to the perl-eval command line option, but gets executed
693first. 738first.
694 739
695=item @urxvt::TERM_EXT 740=item @urxvt::TERM_EXT
696 741
697Works similar to C<@TERM_INIT>, but contains perl package/class names, which 742Works similar to C<@TERM_INIT>, but contains perl package/class names, which
722Messages have a size limit of 1023 bytes currently. 767Messages have a size limit of 1023 bytes currently.
723 768
724=item @terms = urxvt::termlist 769=item @terms = urxvt::termlist
725 770
726Returns all urxvt::term objects that exist in this process, regardless of 771Returns all urxvt::term objects that exist in this process, regardless of
727wether they are started, being destroyed etc., so be careful. Only term 772whether they are started, being destroyed etc., so be careful. Only term
728objects that have perl extensions attached will be returned (because there 773objects that have perl extensions attached will be returned (because there
729is no urxvt::term objet associated with others). 774is no urxvt::term objet associated with others).
730 775
731=item $time = urxvt::NOW 776=item $time = urxvt::NOW
732 777
870 local $TERM = shift; 915 local $TERM = shift;
871 my $htype = shift; 916 my $htype = shift;
872 917
873 if ($htype == 0) { # INIT 918 if ($htype == 0) { # INIT
874 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 919 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
875 920
876 my %ext_arg; 921 my %ext_arg;
877 922
878 { 923 {
879 my @init = @TERM_INIT; 924 my @init = @TERM_INIT;
880 @TERM_INIT = (); 925 @TERM_INIT = ();
943 988
944sub SET_COLOR($$$) { 989sub SET_COLOR($$$) {
945 SET_BGCOLOR (SET_FGCOLOR ($_[0], $_[1]), $_[2]) 990 SET_BGCOLOR (SET_FGCOLOR ($_[0], $_[1]), $_[2])
946} 991}
947 992
993sub rend2mask {
994 no strict 'refs';
995 my ($str, $mask) = (@_, 0);
996 my %color = ( fg => undef, bg => undef );
997 my @failed;
998 for my $spec ( split /\s+/, $str ) {
999 if ( $spec =~ /^([fb]g)[_:-]?(\d+)/i ) {
1000 $color{lc($1)} = $2;
1001 } else {
1002 my $neg = $spec =~ s/^[-^]//;
1003 unless ( exists &{"RS_$spec"} ) {
1004 push @failed, $spec;
1005 next;
1006 }
1007 my $cur = &{"RS_$spec"};
1008 if ( $neg ) {
1009 $mask &= ~$cur;
1010 } else {
1011 $mask |= $cur;
1012 }
1013 }
1014 }
1015 ($mask, @color{qw(fg bg)}, \@failed)
1016}
1017
948# urxvt::term::extension 1018# urxvt::term::extension
949 1019
950package urxvt::term::extension; 1020package urxvt::term::extension;
951 1021
952sub enable { 1022sub enable {
1021is that you cannot use blocking APIs, but the non-blocking variant should 1091is that you cannot use blocking APIs, but the non-blocking variant should
1022work. 1092work.
1023 1093
1024=cut 1094=cut
1025 1095
1026our $VERSION = 1; 1096our $VERSION = '3.4';
1027 1097
1028$INC{"urxvt/anyevent.pm"} = 1; # mark us as there 1098$INC{"urxvt/anyevent.pm"} = 1; # mark us as there
1029push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::]; 1099push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
1030 1100
1031sub timer { 1101sub timer {
1062 1132
1063sub DESTROY { 1133sub DESTROY {
1064 $_[0][1]->stop; 1134 $_[0][1]->stop;
1065} 1135}
1066 1136
1067sub condvar { 1137sub one_event {
1068 bless \my $flag, urxvt::anyevent::condvar::
1069}
1070
1071sub urxvt::anyevent::condvar::broadcast {
1072 ${$_[0]}++;
1073}
1074
1075sub urxvt::anyevent::condvar::wait {
1076 unless (${$_[0]}) {
1077 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API"; 1138 Carp::croak "AnyEvent->one_event blocking wait unsupported in urxvt, use a non-blocking API";
1078 }
1079} 1139}
1080 1140
1081package urxvt::term; 1141package urxvt::term;
1082 1142
1083=head2 The C<urxvt::term> Class 1143=head2 The C<urxvt::term> Class
1170 1230
1171Returns true if the option specified by C<$optval> is enabled, and 1231Returns true if the option specified by C<$optval> is enabled, and
1172optionally change it. All option values are stored by name in the hash 1232optionally change it. All option values are stored by name in the hash
1173C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash. 1233C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
1174 1234
1175Here is a a likely non-exhaustive list of option names, please see the 1235Here is a likely non-exhaustive list of option names, please see the
1176source file F</src/optinc.h> to see the actual list: 1236source file F</src/optinc.h> to see the actual list:
1177 1237
1178 borderLess console cursorBlink cursorUnderline hold iconic insecure 1238 borderLess console cursorBlink cursorUnderline hold iconic insecure
1179 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 1239 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
1180 override-redirect pastableTabs pointerBlank reverseVideo scrollBar 1240 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
1197likely change). 1257likely change).
1198 1258
1199Please note that resource strings will currently only be freed when the 1259Please note that resource strings will currently only be freed when the
1200terminal is destroyed, so changing options frequently will eat memory. 1260terminal is destroyed, so changing options frequently will eat memory.
1201 1261
1202Here is a a likely non-exhaustive list of resource names, not all of which 1262Here is a likely non-exhaustive list of resource names, not all of which
1203are supported in every build, please see the source file F</src/rsinc.h> 1263are supported in every build, please see the source file F</src/rsinc.h>
1204to see the actual list: 1264to see the actual list:
1205 1265
1206 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1266 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
1207 borderLess color cursorBlink cursorUnderline cutchars delete_key 1267 borderLess chdir color cursorBlink cursorUnderline cutchars delete_key
1208 display_name embed ext_bwidth fade font geometry hold iconName 1268 display_name embed ext_bwidth fade font geometry hold iconName
1209 imFont imLocale inputMethod insecure int_bwidth intensityStyles 1269 imFont imLocale inputMethod insecure int_bwidth intensityStyles
1210 italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier 1270 italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier
1211 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval 1271 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
1212 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay 1272 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
1213 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar 1273 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
1214 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness 1274 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
1215 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle 1275 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
1216 secondaryScreen secondaryScroll selectstyle shade term_name title 1276 secondaryScreen secondaryScroll shade term_name title
1217 transient_for transparent transparent_all tripleclickwords utmpInhibit 1277 transient_for transparent transparent_all tripleclickwords utmpInhibit
1218 visualBell 1278 visualBell
1219 1279
1220=cut 1280=cut
1221 1281
1222sub resource($$;$) { 1282sub resource($$;$) {
1223 my ($self, $name) = (shift, shift); 1283 my ($self, $name) = (shift, shift);
1224 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 1284 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
1225 &urxvt::term::_resource 1285 goto &urxvt::term::_resource
1226} 1286}
1227 1287
1228=item $value = $term->x_resource ($pattern) 1288=item $value = $term->x_resource ($pattern)
1229 1289
1230Returns the X-Resource for the given pattern, excluding the program or 1290Returns the X-Resource for the given pattern, excluding the program or
1519 1579
1520Returns the currently displayed screen (0 primary, 1 secondary). 1580Returns the currently displayed screen (0 primary, 1 secondary).
1521 1581
1522=item $cursor_is_hidden = $term->hidden_cursor 1582=item $cursor_is_hidden = $term->hidden_cursor
1523 1583
1524Returns wether the cursor is currently hidden or not. 1584Returns whether the cursor is currently hidden or not.
1525 1585
1526=item $view_start = $term->view_start ([$newvalue]) 1586=item $view_start = $term->view_start ([$newvalue])
1527 1587
1528Returns the row number of the topmost displayed line. Maximum value is 1588Returns the row number of the topmost displayed line. Maximum value is
1529C<0>, which displays the normal terminal contents. Lower values scroll 1589C<0>, which displays the normal terminal contents. Lower values scroll
1537 1597
1538Used after changing terminal contents to display them. 1598Used after changing terminal contents to display them.
1539 1599
1540=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]]) 1600=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
1541 1601
1542Returns the text of the entire row with number C<$row_number>. Row C<0> 1602Returns the text of the entire row with number C<$row_number>. Row C<< $term->top_row >>
1543is the topmost terminal line, row C<< $term->$ncol-1 >> is the bottommost 1603is the topmost terminal line, row C<< $term->nrow-1 >> is the bottommost
1544terminal line. The scrollback buffer starts at line C<-1> and extends to
1545line C<< -$term->nsaved >>. Nothing will be returned if a nonexistent line 1604terminal line. Nothing will be returned if a nonexistent line
1546is requested. 1605is requested.
1547 1606
1548If C<$new_text> is specified, it will replace characters in the current 1607If C<$new_text> is specified, it will replace characters in the current
1549line, starting at column C<$start_col> (default C<0>), which is useful 1608line, starting at column C<$start_col> (default C<0>), which is useful
1550to replace only parts of a line. The font index in the rendition will 1609to replace only parts of a line. The font index in the rendition will
1551automatically be updated. 1610automatically be updated.
1552 1611
1553C<$text> is in a special encoding: tabs and wide characters that use more 1612C<$text> is in a special encoding: tabs and wide characters that use more
1554than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535) 1613than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535)
1555characters. Characters with combining characters and other characters that 1614characters. Characters with combining characters and other characters that
1556do not fit into the normal tetx encoding will be replaced with characters 1615do not fit into the normal text encoding will be replaced with characters
1557in the private use area. 1616in the private use area.
1558 1617
1559You have to obey this encoding when changing text. The advantage is 1618You have to obey this encoding when changing text. The advantage is
1560that C<substr> and similar functions work on screen cells and not on 1619that C<substr> and similar functions work on screen cells and not on
1561characters. 1620characters.
1706where one character corresponds to one screen cell. See 1765where one character corresponds to one screen cell. See
1707C<< $term->ROW_t >> for details. 1766C<< $term->ROW_t >> for details.
1708 1767
1709=item $string = $term->special_decode $text 1768=item $string = $term->special_decode $text
1710 1769
1711Converts rxvt-unicodes text reprsentation into a perl string. See 1770Converts rxvt-unicodes text representation into a perl string. See
1712C<< $term->ROW_t >> for details. 1771C<< $term->ROW_t >> for details.
1713 1772
1714=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt]) 1773=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1715 1774
1716=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt]) 1775=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1719manpage. 1778manpage.
1720 1779
1721=item $success = $term->grab ($eventtime[, $sync]) 1780=item $success = $term->grab ($eventtime[, $sync])
1722 1781
1723Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1782Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1724synchronous (C<$sync> is true). Also remembers the grab timestampe. 1783synchronous (C<$sync> is true). Also remembers the grab timestamp.
1725 1784
1726=item $term->allow_events_async 1785=item $term->allow_events_async
1727 1786
1728Calls XAllowEvents with AsyncBoth for the most recent grab. 1787Calls XAllowEvents with AsyncBoth for the most recent grab.
1729 1788
1748 1807
1749=item @atoms = $term->XListProperties ($window) 1808=item @atoms = $term->XListProperties ($window)
1750 1809
1751=item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property) 1810=item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
1752 1811
1753=item $term->XChangeWindowProperty ($window, $property, $type, $format, $octets) 1812=item $term->XChangeProperty ($window, $property, $type, $format, $octets)
1754 1813
1755=item $term->XDeleteProperty ($window, $property) 1814=item $term->XDeleteProperty ($window, $property)
1756 1815
1757=item $window = $term->DefaultRootWindow 1816=item $window = $term->DefaultRootWindow
1758 1817
1880 my $env = $self->{term}->env; 1939 my $env = $self->{term}->env;
1881 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE. 1940 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
1882 delete $env->{LC_ALL}; 1941 delete $env->{LC_ALL};
1883 $env->{LC_CTYPE} = $self->{term}->locale; 1942 $env->{LC_CTYPE} = $self->{term}->locale;
1884 1943
1885 urxvt::term->new ($env, "popup", 1944 my $term = urxvt::term->new (
1945 $env, "popup",
1886 "--perl-lib" => "", "--perl-ext-common" => "", 1946 "--perl-lib" => "", "--perl-ext-common" => "",
1887 "-pty-fd" => -1, "-sl" => 0, 1947 "-pty-fd" => -1, "-sl" => 0,
1888 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect", 1948 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect",
1889 "--transient-for" => $self->{term}->parent, 1949 "--transient-for" => $self->{term}->parent,
1890 "-display" => $self->{term}->display_id, 1950 "-display" => $self->{term}->display_id,
1891 "-pe" => "urxvt-popup") 1951 "-pe" => "urxvt-popup",
1892 or die "unable to create popup window\n"; 1952 ) or die "unable to create popup window\n";
1953
1954 unless (delete $term->{urxvt_popup_init_done}) {
1955 $term->ungrab;
1956 $term->destroy;
1957 die "unable to initialise popup window\n";
1958 }
1893} 1959}
1894 1960
1895sub DESTROY { 1961sub DESTROY {
1896 my ($self) = @_; 1962 my ($self) = @_;
1897 1963
1902=back 1968=back
1903 1969
1904=cut 1970=cut
1905 1971
1906package urxvt::watcher; 1972package urxvt::watcher;
1907
1908@urxvt::timer::ISA = __PACKAGE__;
1909@urxvt::iow::ISA = __PACKAGE__;
1910@urxvt::pw::ISA = __PACKAGE__;
1911@urxvt::iw::ISA = __PACKAGE__;
1912 1973
1913=head2 The C<urxvt::timer> Class 1974=head2 The C<urxvt::timer> Class
1914 1975
1915This class implements timer watchers/events. Time is represented as a 1976This class implements timer watchers/events. Time is represented as a
1916fractional number of seconds since the epoch. Example: 1977fractional number of seconds since the epoch. Example:
1920 ->new 1981 ->new
1921 ->interval (1) 1982 ->interval (1)
1922 ->cb (sub { 1983 ->cb (sub {
1923 $term->{overlay}->set (0, 0, 1984 $term->{overlay}->set (0, 0,
1924 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]); 1985 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
1925 }); 1986 });
1926 1987
1927=over 4 1988=over 4
1928 1989
1929=item $timer = new urxvt::timer 1990=item $timer = new urxvt::timer
1930 1991
1973 2034
1974 $term->{socket} = ... 2035 $term->{socket} = ...
1975 $term->{iow} = urxvt::iow 2036 $term->{iow} = urxvt::iow
1976 ->new 2037 ->new
1977 ->fd (fileno $term->{socket}) 2038 ->fd (fileno $term->{socket})
1978 ->events (urxvt::EVENT_READ) 2039 ->events (urxvt::EV_READ)
1979 ->start 2040 ->start
1980 ->cb (sub { 2041 ->cb (sub {
1981 my ($iow, $revents) = @_; 2042 my ($iow, $revents) = @_;
1982 # $revents must be 1 here, no need to check 2043 # $revents must be 1 here, no need to check
1983 sysread $term->{socket}, my $buf, 8192 2044 sysread $term->{socket}, my $buf, 8192
1996Set the callback to be called when io events are triggered. C<$reventmask> 2057Set the callback to be called when io events are triggered. C<$reventmask>
1997is a bitset as described in the C<events> method. 2058is a bitset as described in the C<events> method.
1998 2059
1999=item $iow = $iow->fd ($fd) 2060=item $iow = $iow->fd ($fd)
2000 2061
2001Set the filedescriptor (not handle) to watch. 2062Set the file descriptor (not handle) to watch.
2002 2063
2003=item $iow = $iow->events ($eventmask) 2064=item $iow = $iow->events ($eventmask)
2004 2065
2005Set the event mask to watch. The only allowed values are 2066Set the event mask to watch. The only allowed values are
2006C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed 2067C<urxvt::EV_READ> and C<urxvt::EV_WRITE>, which might be ORed
2007together, or C<urxvt::EVENT_NONE>. 2068together, or C<urxvt::EV_NONE>.
2008 2069
2009=item $iow = $iow->start 2070=item $iow = $iow->start
2010 2071
2011Start watching for requested events on the given handle. 2072Start watching for requested events on the given handle.
2012 2073
2013=item $iow = $iow->stop 2074=item $iow = $iow->stop
2014 2075
2015Stop watching for events on the given filehandle. 2076Stop watching for events on the given file handle.
2016 2077
2017=back 2078=back
2018 2079
2019=head2 The C<urxvt::iw> Class 2080=head2 The C<urxvt::iw> Class
2020 2081
2053 ->new 2114 ->new
2054 ->start ($pid) 2115 ->start ($pid)
2055 ->cb (sub { 2116 ->cb (sub {
2056 my ($pw, $exit_status) = @_; 2117 my ($pw, $exit_status) = @_;
2057 ... 2118 ...
2058 }); 2119 });
2059 2120
2060=over 4 2121=over 4
2061 2122
2062=item $pw = new urxvt::pw 2123=item $pw = new urxvt::pw
2063 2124
2067 2128
2068Set the callback to be called when the timer triggers. 2129Set the callback to be called when the timer triggers.
2069 2130
2070=item $pw = $timer->start ($pid) 2131=item $pw = $timer->start ($pid)
2071 2132
2072Tells the wqtcher to start watching for process C<$pid>. 2133Tells the watcher to start watching for process C<$pid>.
2073 2134
2074=item $pw = $pw->stop 2135=item $pw = $pw->stop
2075 2136
2076Stop the watcher. 2137Stop the watcher.
2077 2138
2090 2151
2091=item >= 3 - script loading and management 2152=item >= 3 - script loading and management
2092 2153
2093=item >=10 - all called hooks 2154=item >=10 - all called hooks
2094 2155
2095=item >=11 - hook reutrn values 2156=item >=11 - hook return values
2096 2157
2097=back 2158=back
2098 2159
2099=head1 AUTHOR 2160=head1 AUTHOR
2100 2161
2102 http://software.schmorp.de/pkg/rxvt-unicode 2163 http://software.schmorp.de/pkg/rxvt-unicode
2103 2164
2104=cut 2165=cut
2105 2166
21061 21671
2168
2169# vim: sw=3:

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines