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.139 by root, Sat Jul 1 19:04:43 2006 UTC vs.
Revision 1.168 by root, Sun Jun 15 14:07:58 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.
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.
155 164
156=item readline (enabled by default) 165=item readline (enabled by default)
157 166
158A support package that tries to make editing with readline easier. At 167A support package that tries to make editing with readline easier. At
159the 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
160move 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
161cursor-left or cursor-right keypresses as required (the this only works 170cursor-left or cursor-right keypresses as required (this only works
162for programs that correctly support wide characters). 171for programs that correctly support wide characters).
163 172
164To avoid too many false positives, this is only done when: 173To avoid too many false positives, this is only done when:
165 174
166=over 4 175=over 4
214the message into vi commands to load the file. 223the message into vi commands to load the file.
215 224
216=item tabbed 225=item tabbed
217 226
218This transforms the terminal into a tabbar with additional terminals, that 227This transforms the terminal into a tabbar with additional terminals, that
219is, 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
220displays 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
221button per tab. 230button per tab.
222 231
223Clicking a button will activate that tab. Pressing B<Shift-Left> and 232Clicking a button will activate that tab. Pressing B<Shift-Left> and
224B<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,
234 URxvt.tabbed.tab-bg: <colour-index, default 1> 243 URxvt.tabbed.tab-bg: <colour-index, default 1>
235 244
236See 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
237indices. 246indices.
238 247
239=item mark-urls 248=item matcher
240 249
241Uses per-line display filtering (C<on_line_update>) to underline urls and 250Uses per-line display filtering (C<on_line_update>) to underline text
242make them clickable. When middle-clicked, the program specified in the 251matching a certain pattern and make it clickable. When clicked with the
243resource C<urlLauncher> (default C<x-www-browser>) will be started with 252mouse button specified in the C<matcher.button> resource (default 2, or
244the 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
245 276
246=item xim-onthespot 277=item xim-onthespot
247 278
248This (experimental) perl extension implements OnTheSpot editing. It does 279This (experimental) perl extension implements OnTheSpot editing. It does
249not 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
250OnTheSpot 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
251kinput2. 282kinput2.
252 283
253You enable it by specifying this extension and a preedit style of 284You enable it by specifying this extension and a preedit style of
254C<OnTheSpot>, i.e.: 285C<OnTheSpot>, i.e.:
255 286
256 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot 287 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot
257 288
258=item automove-background 289=item kuake<hotkey>
259 290
260This is basically a one-line extension that dynamically changes the background pixmap offset 291A very primitive quake-console-like extension. It was inspired by a
261to the window position, in effect creating the same effect as pseudo transparency with 292description of how the programs C<kuake> and C<yakuake> work: Whenever the
262a custom pixmap. No scaling is supported in this mode. Exmaple: 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.
263 296
264 @@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).
265 307
266=item block-graphics-to-ascii 308=item block-graphics-to-ascii
267 309
268A 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
269by replacing all line-drawing characters (U+2500 .. U+259F) by a 311by replacing all line-drawing characters (U+2500 .. U+259F) by a
270similar-looking ascii character. 312similar-looking ascii character.
271 313
272=item digital-clock 314=item digital-clock
273 315
274Displays a digital clock using the built-in overlay. 316Displays a digital clock using the built-in overlay.
275 317
276=item remote-clipboard 318=item remote-clipboard
277 319
278Somewhat of a misnomer, this extension adds two menu entries to the 320Somewhat of a misnomer, this extension adds two menu entries to the
279selection popup that allows one ti run external commands to store the 321selection popup that allows one to run external commands to store the
280selection somewhere and fetch it again. 322selection somewhere and fetch it again.
281 323
282We use it to implement a "distributed selection mechanism", which just 324We use it to implement a "distributed selection mechanism", which just
283means 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
284reads it. 326reads it.
319After 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
320in the C<selection-pastebin-url> resource (again, the % is the placeholder 362in the C<selection-pastebin-url> resource (again, the % is the placeholder
321for the filename): 363for the filename):
322 364
323 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.
324 371
325=item example-refresh-hooks 372=item example-refresh-hooks
326 373
327Displays 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
328window. Illustrates overwriting the refresh callbacks to create your own 375window. Illustrates overwriting the refresh callbacks to create your own
369=back 416=back
370 417
371=head2 Extension Objects 418=head2 Extension Objects
372 419
373Every 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
374for 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,
375hooks. 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
376about 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
377begin with an underscore character C<_>: these are reserved for internal 425that begin with an underscore character C<_>: these are reserved for
378use. 426internal use.
379 427
380Although 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
381C<urxvt::term> class on this object. 429C<urxvt::term> class on this object.
382 430
383It has the following methods and data members: 431It has the following methods and data members:
404=head2 Hooks 452=head2 Hooks
405 453
406The following subroutines can be declared in extension files, and will be 454The following subroutines can be declared in extension files, and will be
407called whenever the relevant event happens. 455called whenever the relevant event happens.
408 456
409The 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
410the in the C<Extension Objects> section. 458the in the C<Extension Objects> section.
411 459
412B<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
413hooks 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
414relevant action might not be carried out by the C++ code. 462relevant action might not be carried out by the C++ code.
427place. 475place.
428 476
429=item on_start $term 477=item on_start $term
430 478
431Called 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
432trying to map (display) the toplevel and returning to the mainloop. 480trying to map (display) the toplevel and returning to the main loop.
433 481
434=item on_destroy $term 482=item on_destroy $term
435 483
436Called whenever something tries to destroy terminal, when the terminal is 484Called whenever something tries to destroy terminal, when the terminal is
437still fully functional (not for long, though). 485still fully functional (not for long, though).
464 512
465Called whenever a selection has been copied, but before the selection is 513Called whenever a selection has been copied, but before the selection is
466requested from the server. The selection text can be queried and changed 514requested from the server. The selection text can be queried and changed
467by calling C<< $term->selection >>. 515by calling C<< $term->selection >>.
468 516
469Returning a true value aborts selection grabbing. It will still be hilighted. 517Returning a true value aborts selection grabbing. It will still be highlighted.
470 518
471=item on_sel_extend $term 519=item on_sel_extend $term
472 520
473Called 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
474click) and is either supposed to return false (normal operation), or 522click) and is either supposed to return false (normal operation), or
475should 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
476processing. This can happen multiple times, as long as the callback 524processing. This can happen multiple times, as long as the callback
477returns 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
478supposed to enlarge the selection more and more, if possible. 526supposed to enlarge the selection more and more, if possible.
479 527
480See the F<selection> example extension. 528See the F<selection> example extension.
481 529
482=item on_view_change $term, $offset 530=item on_view_change $term, $offset
483 531
484Called whenever the view offset changes, i..e the user or program 532Called whenever the view offset changes, i.e. the user or program
485scrolls. Offset C<0> means display the normal terminal, positive values 533scrolls. Offset C<0> means display the normal terminal, positive values
486show this many lines of scrollback. 534show this many lines of scrollback.
487 535
488=item on_scroll_back $term, $lines, $saved 536=item on_scroll_back $term, $lines, $saved
489 537
513string should start with the extension name and a colon, to distinguish 561string should start with the extension name and a colon, to distinguish
514it 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
515future. 563future.
516 564
517Be 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,
518as 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
519other users on the same system etc.). 567other users on the same system etc.).
520 568
521=item on_add_lines $term, $string 569=item on_add_lines $term, $string
522 570
523Called 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
556 604
557Called just after the screen gets redrawn. See C<on_refresh_begin>. 605Called just after the screen gets redrawn. See C<on_refresh_begin>.
558 606
559=item on_user_command $term, $string 607=item on_user_command $term, $string
560 608
561Called whenever the a user-configured event is being activated (e.g. via 609Called whenever a user-configured event is being activated (e.g. via
562a 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>
563resource in the @@RXVT_NAME@@(1) manpage). 611resource in the @@RXVT_NAME@@(1) manpage).
564 612
565The 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
566slightly in the future. 614slightly in the future.
567 615
568=item on_resize_all_windows $tern, $new_width, $new_height 616=item on_resize_all_windows $tern, $new_width, $new_height
569 617
570Called just after the new window size has been calculcated, but before 618Called just after the new window size has been calculated, but before
571windows 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
572returns TRUE, setting of the window hints is being skipped. 620returns TRUE, setting of the window hints is being skipped.
573 621
574=item on_x_event $term, $event 622=item on_x_event $term, $event
575 623
576Called 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
577windows). Should only be used as a last resort. Most event structure 625windows). Should only be used as a last resort. Most event structure
578members are not passed. 626members are not passed.
579 627
628=item on_root_event $term, $event
629
630Like C<on_x_event>, but is called for events on the root window.
631
580=item on_focus_in $term 632=item on_focus_in $term
581 633
582Called whenever the window gets the keyboard focus, before rxvt-unicode 634Called whenever the window gets the keyboard focus, before rxvt-unicode
583does focus in processing. 635does focus in processing.
584 636
585=item on_focus_out $term 637=item on_focus_out $term
586 638
587Called wheneever the window loses keyboard focus, before rxvt-unicode does 639Called whenever the window loses keyboard focus, before rxvt-unicode does
588focus out processing. 640focus out processing.
589 641
590=item on_configure_notify $term, $event 642=item on_configure_notify $term, $event
591 643
592=item on_property_notify $term, $event 644=item on_property_notify $term, $event
675The current terminal. This variable stores the current C<urxvt::term> 727The current terminal. This variable stores the current C<urxvt::term>
676object, whenever a callback/hook is executing. 728object, whenever a callback/hook is executing.
677 729
678=item @urxvt::TERM_INIT 730=item @urxvt::TERM_INIT
679 731
680All 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
681created 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
682gets cleared before the codereferences that were in it are being executed, 734gets cleared before the code references that were in it are being executed,
683so coderefs can push themselves onto it again if they so desire. 735so references can push themselves onto it again if they so desire.
684 736
685This complements to the perl-eval commandline option, but gets executed 737This complements to the perl-eval command line option, but gets executed
686first. 738first.
687 739
688=item @urxvt::TERM_EXT 740=item @urxvt::TERM_EXT
689 741
690Works 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
715Messages have a size limit of 1023 bytes currently. 767Messages have a size limit of 1023 bytes currently.
716 768
717=item @terms = urxvt::termlist 769=item @terms = urxvt::termlist
718 770
719Returns all urxvt::term objects that exist in this process, regardless of 771Returns all urxvt::term objects that exist in this process, regardless of
720wether they are started, being destroyed etc., so be careful. Only term 772whether they are started, being destroyed etc., so be careful. Only term
721objects that have perl extensions attached will be returned (because there 773objects that have perl extensions attached will be returned (because there
722is no urxvt::term objet associated with others). 774is no urxvt::term objet associated with others).
723 775
724=item $time = urxvt::NOW 776=item $time = urxvt::NOW
725 777
863 local $TERM = shift; 915 local $TERM = shift;
864 my $htype = shift; 916 my $htype = shift;
865 917
866 if ($htype == 0) { # INIT 918 if ($htype == 0) { # INIT
867 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 919 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
868 920
869 my %ext_arg; 921 my %ext_arg;
870 922
871 { 923 {
872 my @init = @TERM_INIT; 924 my @init = @TERM_INIT;
873 @TERM_INIT = (); 925 @TERM_INIT = ();
936 988
937sub SET_COLOR($$$) { 989sub SET_COLOR($$$) {
938 SET_BGCOLOR (SET_FGCOLOR ($_[0], $_[1]), $_[2]) 990 SET_BGCOLOR (SET_FGCOLOR ($_[0], $_[1]), $_[2])
939} 991}
940 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
941# urxvt::term::extension 1018# urxvt::term::extension
942 1019
943package urxvt::term::extension; 1020package urxvt::term::extension;
944 1021
945sub enable { 1022sub enable {
1014is 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
1015work. 1092work.
1016 1093
1017=cut 1094=cut
1018 1095
1019our $VERSION = 1; 1096our $VERSION = '3.4';
1020 1097
1021$INC{"urxvt/anyevent.pm"} = 1; # mark us as there 1098$INC{"urxvt/anyevent.pm"} = 1; # mark us as there
1022push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::]; 1099push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
1023 1100
1024sub timer { 1101sub timer {
1055 1132
1056sub DESTROY { 1133sub DESTROY {
1057 $_[0][1]->stop; 1134 $_[0][1]->stop;
1058} 1135}
1059 1136
1060sub condvar { 1137sub one_event {
1061 bless \my $flag, urxvt::anyevent::condvar::
1062}
1063
1064sub urxvt::anyevent::condvar::broadcast {
1065 ${$_[0]}++;
1066}
1067
1068sub urxvt::anyevent::condvar::wait {
1069 unless (${$_[0]}) {
1070 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";
1071 }
1072} 1139}
1073 1140
1074package urxvt::term; 1141package urxvt::term;
1075 1142
1076=head2 The C<urxvt::term> Class 1143=head2 The C<urxvt::term> Class
1163 1230
1164Returns true if the option specified by C<$optval> is enabled, and 1231Returns true if the option specified by C<$optval> is enabled, and
1165optionally 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
1166C<%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.
1167 1234
1168Here 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
1169source file F</src/optinc.h> to see the actual list: 1236source file F</src/optinc.h> to see the actual list:
1170 1237
1171 borderLess console cursorBlink cursorUnderline hold iconic insecure 1238 borderLess console cursorBlink cursorUnderline hold iconic insecure
1172 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 1239 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
1173 override-redirect pastableTabs pointerBlank reverseVideo scrollBar 1240 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
1190likely change). 1257likely change).
1191 1258
1192Please note that resource strings will currently only be freed when the 1259Please note that resource strings will currently only be freed when the
1193terminal is destroyed, so changing options frequently will eat memory. 1260terminal is destroyed, so changing options frequently will eat memory.
1194 1261
1195Here 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
1196are 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>
1197to see the actual list: 1264to see the actual list:
1198 1265
1199 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1266 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
1200 borderLess color cursorBlink cursorUnderline cutchars delete_key 1267 borderLess chdir color cursorBlink cursorUnderline cutchars delete_key
1201 display_name embed ext_bwidth fade font geometry hold iconName 1268 display_name embed ext_bwidth fade font geometry hold iconName
1202 imFont imLocale inputMethod insecure int_bwidth intensityStyles 1269 imFont imLocale inputMethod insecure int_bwidth intensityStyles
1203 italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier 1270 italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier
1204 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval 1271 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
1205 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay 1272 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
1206 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar 1273 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
1207 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness 1274 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
1208 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle 1275 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
1209 secondaryScreen secondaryScroll selectstyle shade term_name title 1276 secondaryScreen secondaryScroll shade term_name title
1210 transient_for transparent transparent_all tripleclickwords utmpInhibit 1277 transient_for transparent transparent_all tripleclickwords utmpInhibit
1211 visualBell 1278 visualBell
1212 1279
1213=cut 1280=cut
1214 1281
1512 1579
1513Returns the currently displayed screen (0 primary, 1 secondary). 1580Returns the currently displayed screen (0 primary, 1 secondary).
1514 1581
1515=item $cursor_is_hidden = $term->hidden_cursor 1582=item $cursor_is_hidden = $term->hidden_cursor
1516 1583
1517Returns wether the cursor is currently hidden or not. 1584Returns whether the cursor is currently hidden or not.
1518 1585
1519=item $view_start = $term->view_start ([$newvalue]) 1586=item $view_start = $term->view_start ([$newvalue])
1520 1587
1521Returns the row number of the topmost displayed line. Maximum value is 1588Returns the row number of the topmost displayed line. Maximum value is
1522C<0>, which displays the normal terminal contents. Lower values scroll 1589C<0>, which displays the normal terminal contents. Lower values scroll
1530 1597
1531Used after changing terminal contents to display them. 1598Used after changing terminal contents to display them.
1532 1599
1533=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]]) 1600=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
1534 1601
1535Returns 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 >>
1536is 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
1537terminal line. The scrollback buffer starts at line C<-1> and extends to
1538line C<< -$term->nsaved >>. Nothing will be returned if a nonexistent line 1604terminal line. Nothing will be returned if a nonexistent line
1539is requested. 1605is requested.
1540 1606
1541If 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
1542line, 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
1543to 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
1544automatically be updated. 1610automatically be updated.
1545 1611
1546C<$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
1547than 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)
1548characters. Characters with combining characters and other characters that 1614characters. Characters with combining characters and other characters that
1549do 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
1550in the private use area. 1616in the private use area.
1551 1617
1552You have to obey this encoding when changing text. The advantage is 1618You have to obey this encoding when changing text. The advantage is
1553that 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
1554characters. 1620characters.
1699where one character corresponds to one screen cell. See 1765where one character corresponds to one screen cell. See
1700C<< $term->ROW_t >> for details. 1766C<< $term->ROW_t >> for details.
1701 1767
1702=item $string = $term->special_decode $text 1768=item $string = $term->special_decode $text
1703 1769
1704Converts rxvt-unicodes text reprsentation into a perl string. See 1770Converts rxvt-unicodes text representation into a perl string. See
1705C<< $term->ROW_t >> for details. 1771C<< $term->ROW_t >> for details.
1706 1772
1707=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt]) 1773=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1708 1774
1709=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt]) 1775=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1712manpage. 1778manpage.
1713 1779
1714=item $success = $term->grab ($eventtime[, $sync]) 1780=item $success = $term->grab ($eventtime[, $sync])
1715 1781
1716Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1782Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1717synchronous (C<$sync> is true). Also remembers the grab timestampe. 1783synchronous (C<$sync> is true). Also remembers the grab timestamp.
1718 1784
1719=item $term->allow_events_async 1785=item $term->allow_events_async
1720 1786
1721Calls XAllowEvents with AsyncBoth for the most recent grab. 1787Calls XAllowEvents with AsyncBoth for the most recent grab.
1722 1788
1741 1807
1742=item @atoms = $term->XListProperties ($window) 1808=item @atoms = $term->XListProperties ($window)
1743 1809
1744=item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property) 1810=item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
1745 1811
1746=item $term->XChangeWindowProperty ($window, $property, $type, $format, $octets) 1812=item $term->XChangeProperty ($window, $property, $type, $format, $octets)
1747 1813
1748=item $term->XDeleteProperty ($window, $property) 1814=item $term->XDeleteProperty ($window, $property)
1749 1815
1750=item $window = $term->DefaultRootWindow 1816=item $window = $term->DefaultRootWindow
1751 1817
1873 my $env = $self->{term}->env; 1939 my $env = $self->{term}->env;
1874 # 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.
1875 delete $env->{LC_ALL}; 1941 delete $env->{LC_ALL};
1876 $env->{LC_CTYPE} = $self->{term}->locale; 1942 $env->{LC_CTYPE} = $self->{term}->locale;
1877 1943
1878 urxvt::term->new ($env, "popup", 1944 my $term = urxvt::term->new (
1945 $env, "popup",
1879 "--perl-lib" => "", "--perl-ext-common" => "", 1946 "--perl-lib" => "", "--perl-ext-common" => "",
1880 "-pty-fd" => -1, "-sl" => 0, 1947 "-pty-fd" => -1, "-sl" => 0,
1881 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect", 1948 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect",
1882 "--transient-for" => $self->{term}->parent, 1949 "--transient-for" => $self->{term}->parent,
1883 "-display" => $self->{term}->display_id, 1950 "-display" => $self->{term}->display_id,
1884 "-pe" => "urxvt-popup") 1951 "-pe" => "urxvt-popup",
1885 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 }
1886} 1959}
1887 1960
1888sub DESTROY { 1961sub DESTROY {
1889 my ($self) = @_; 1962 my ($self) = @_;
1890 1963
1895=back 1968=back
1896 1969
1897=cut 1970=cut
1898 1971
1899package urxvt::watcher; 1972package urxvt::watcher;
1900
1901@urxvt::timer::ISA = __PACKAGE__;
1902@urxvt::iow::ISA = __PACKAGE__;
1903@urxvt::pw::ISA = __PACKAGE__;
1904@urxvt::iw::ISA = __PACKAGE__;
1905 1973
1906=head2 The C<urxvt::timer> Class 1974=head2 The C<urxvt::timer> Class
1907 1975
1908This class implements timer watchers/events. Time is represented as a 1976This class implements timer watchers/events. Time is represented as a
1909fractional number of seconds since the epoch. Example: 1977fractional number of seconds since the epoch. Example:
1913 ->new 1981 ->new
1914 ->interval (1) 1982 ->interval (1)
1915 ->cb (sub { 1983 ->cb (sub {
1916 $term->{overlay}->set (0, 0, 1984 $term->{overlay}->set (0, 0,
1917 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]); 1985 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
1918 }); 1986 });
1919 1987
1920=over 4 1988=over 4
1921 1989
1922=item $timer = new urxvt::timer 1990=item $timer = new urxvt::timer
1923 1991
1966 2034
1967 $term->{socket} = ... 2035 $term->{socket} = ...
1968 $term->{iow} = urxvt::iow 2036 $term->{iow} = urxvt::iow
1969 ->new 2037 ->new
1970 ->fd (fileno $term->{socket}) 2038 ->fd (fileno $term->{socket})
1971 ->events (urxvt::EVENT_READ) 2039 ->events (urxvt::EV_READ)
1972 ->start 2040 ->start
1973 ->cb (sub { 2041 ->cb (sub {
1974 my ($iow, $revents) = @_; 2042 my ($iow, $revents) = @_;
1975 # $revents must be 1 here, no need to check 2043 # $revents must be 1 here, no need to check
1976 sysread $term->{socket}, my $buf, 8192 2044 sysread $term->{socket}, my $buf, 8192
1989Set 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>
1990is a bitset as described in the C<events> method. 2058is a bitset as described in the C<events> method.
1991 2059
1992=item $iow = $iow->fd ($fd) 2060=item $iow = $iow->fd ($fd)
1993 2061
1994Set the filedescriptor (not handle) to watch. 2062Set the file descriptor (not handle) to watch.
1995 2063
1996=item $iow = $iow->events ($eventmask) 2064=item $iow = $iow->events ($eventmask)
1997 2065
1998Set the event mask to watch. The only allowed values are 2066Set the event mask to watch. The only allowed values are
1999C<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
2000together, or C<urxvt::EVENT_NONE>. 2068together, or C<urxvt::EV_NONE>.
2001 2069
2002=item $iow = $iow->start 2070=item $iow = $iow->start
2003 2071
2004Start watching for requested events on the given handle. 2072Start watching for requested events on the given handle.
2005 2073
2006=item $iow = $iow->stop 2074=item $iow = $iow->stop
2007 2075
2008Stop watching for events on the given filehandle. 2076Stop watching for events on the given file handle.
2009 2077
2010=back 2078=back
2011 2079
2012=head2 The C<urxvt::iw> Class 2080=head2 The C<urxvt::iw> Class
2013 2081
2046 ->new 2114 ->new
2047 ->start ($pid) 2115 ->start ($pid)
2048 ->cb (sub { 2116 ->cb (sub {
2049 my ($pw, $exit_status) = @_; 2117 my ($pw, $exit_status) = @_;
2050 ... 2118 ...
2051 }); 2119 });
2052 2120
2053=over 4 2121=over 4
2054 2122
2055=item $pw = new urxvt::pw 2123=item $pw = new urxvt::pw
2056 2124
2060 2128
2061Set the callback to be called when the timer triggers. 2129Set the callback to be called when the timer triggers.
2062 2130
2063=item $pw = $timer->start ($pid) 2131=item $pw = $timer->start ($pid)
2064 2132
2065Tells the wqtcher to start watching for process C<$pid>. 2133Tells the watcher to start watching for process C<$pid>.
2066 2134
2067=item $pw = $pw->stop 2135=item $pw = $pw->stop
2068 2136
2069Stop the watcher. 2137Stop the watcher.
2070 2138
2083 2151
2084=item >= 3 - script loading and management 2152=item >= 3 - script loading and management
2085 2153
2086=item >=10 - all called hooks 2154=item >=10 - all called hooks
2087 2155
2088=item >=11 - hook reutrn values 2156=item >=11 - hook return values
2089 2157
2090=back 2158=back
2091 2159
2092=head1 AUTHOR 2160=head1 AUTHOR
2093 2161
2095 http://software.schmorp.de/pkg/rxvt-unicode 2163 http://software.schmorp.de/pkg/rxvt-unicode
2096 2164
2097=cut 2165=cut
2098 2166
20991 21671
2168
2169# vim: sw=3:

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines