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.156 by ayin, Wed Aug 1 17:55:37 2007 UTC vs.
Revision 1.197 by sf-tpope, Fri Aug 19 23:08:35 2011 UTC

40 40
41 @@RXVT_NAME@@ -pe <extensionname> 41 @@RXVT_NAME@@ -pe <extensionname>
42 42
43Or by adding them to the resource for extensions loaded by default: 43Or by adding them to the resource for extensions loaded by default:
44 44
45 URxvt.perl-ext-common: default,automove-background,selection-autotransform 45 URxvt.perl-ext-common: default,selection-autotransform
46 46
47=over 4 47=over 4
48 48
49=item selection (enabled by default) 49=item selection (enabled by default)
50 50
101 101
102Other extensions can extend this popup menu by pushing a code reference 102Other extensions can extend this popup menu by pushing a code reference
103onto C<@{ $term->{option_popup_hook} }>, which gets called whenever the 103onto C<@{ $term->{option_popup_hook} }>, which gets called whenever the
104popup is being displayed. 104popup is being displayed.
105 105
106It'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
107either 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
108reference. 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
109will 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
110first argument. 110first argument.
111 111
112The following will add an entry C<myoption> that changes 112The following will add an entry C<myoption> that changes
113C<$self->{myoption}>: 113C<< $self->{myoption} >>:
114 114
115 push @{ $self->{term}{option_popup_hook} }, sub { 115 push @{ $self->{term}{option_popup_hook} }, sub {
116 ("my option" => $myoption, sub { $self->{myoption} = $_[0] }) 116 ("my option" => $myoption, sub { $self->{myoption} = $_[0] })
117 }; 117 };
118 118
124 124
125Other extensions can extend this popup menu by pushing a code reference 125Other extensions can extend this popup menu by pushing a code reference
126onto C<@{ $term->{selection_popup_hook} }>, which gets called whenever the 126onto C<@{ $term->{selection_popup_hook} }>, which gets called whenever the
127popup is being displayed. 127popup is being displayed.
128 128
129It'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
130is in C<$_>, which can be used to decide whether to add something or not. 130is in C<$_>, which can be used to decide whether to add something or not.
131It 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
132string 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
133when the button gets activated and should transform C<$_>. 133when the button gets activated and should transform C<$_>.
134 134
135The 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
136the 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
137C<a>s: 137C<a>s:
138 138
139 push @{ $self->{term}{selection_popup_hook} }, sub { 139 push @{ $self->{term}{selection_popup_hook} }, sub {
140 /a/ ? ("a to be" => sub { s/a/b/g } 140 /a/ ? ("a to b" => sub { s/a/b/g }
141 : () 141 : ()
142 }; 142 };
143 143
144=item searchable-scrollback<hotkey> (enabled by default) 144=item searchable-scrollback<hotkey> (enabled by default)
145 145
165=item readline (enabled by default) 165=item readline (enabled by default)
166 166
167A support package that tries to make editing with readline easier. At 167A support package that tries to make editing with readline easier. At
168the 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
169move 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
170cursor-left or cursor-right keypresses as required (the this only works 170cursor-left or cursor-right keypresses as required (this only works
171for programs that correctly support wide characters). 171for programs that correctly support wide characters).
172 172
173To avoid too many false positives, this is only done when: 173To avoid too many false positives, this is only done when:
174 174
175=over 4 175=over 4
259The default pattern to match URLs can be overridden with the 259The default pattern to match URLs can be overridden with the
260C<matcher.pattern.0> resource, and additional patterns can be specified 260C<matcher.pattern.0> resource, and additional patterns can be specified
261with numbered patterns, in a manner similar to the "selection" extension. 261with numbered patterns, in a manner similar to the "selection" extension.
262The launcher can also be overridden on a per-pattern basis. 262The launcher can also be overridden on a per-pattern basis.
263 263
264It is possible to activate the most recently seen match from the keyboard. 264It is possible to activate the most recently seen match or a list of matches
265from the keyboard. Simply bind a keysym to "perl:matcher:last" or
265Simply bind a keysym to "perl:matcher" as seen in the example below. 266"perl:matcher:list" as seen in the example below.
266 267
267Example configuration: 268Example configuration:
268 269
269 URxvt.perl-ext: default,matcher 270 URxvt.perl-ext: default,matcher
270 URxvt.urlLauncher: sensible-browser 271 URxvt.urlLauncher: sensible-browser
271 URxvt.keysym.C-Delete: perl:matcher 272 URxvt.keysym.C-Delete: perl:matcher:last
273 URxvt.keysym.M-Delete: perl:matcher:list
272 URxvt.matcher.button: 1 274 URxvt.matcher.button: 1
273 URxvt.matcher.pattern.1: \\bwww\\.[\\w-]+\\.[\\w./?&@#-]*[\\w/-] 275 URxvt.matcher.pattern.1: \\bwww\\.[\\w-]+\\.[\\w./?&@#-]*[\\w/-]
274 URxvt.matcher.pattern.2: \\B(/\\S+?):(\\d+)(?=:|$) 276 URxvt.matcher.pattern.2: \\B(/\\S+?):(\\d+)(?=:|$)
275 URxvt.matcher.launcher.2: gvim +$2 $1 277 URxvt.matcher.launcher.2: gvim +$2 $1
276 278
277=item xim-onthespot 279=item xim-onthespot
278 280
279This (experimental) perl extension implements OnTheSpot editing. It does 281This (experimental) perl extension implements OnTheSpot editing. It does
280not work perfectly, and some input methods don't seem to work well with 282not work perfectly, and some input methods don't seem to work well with
281OnTheSpot editing in general, but it seems to work at leats for SCIM and 283OnTheSpot editing in general, but it seems to work at least for SCIM and
282kinput2. 284kinput2.
283 285
284You enable it by specifying this extension and a preedit style of 286You enable it by specifying this extension and a preedit style of
285C<OnTheSpot>, i.e.: 287C<OnTheSpot>, i.e.:
286 288
294will show or hide itself. Another press of the accelerator key will hide 296will show or hide itself. Another press of the accelerator key will hide
295or show it again. 297or show it again.
296 298
297Initially, the window will not be shown when using this extension. 299Initially, the window will not be shown when using this extension.
298 300
299This is useful if you need a single terminal thats not using any desktop 301This 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. 302space most of the time but is quickly available at the press of a key.
301 303
302The accelerator key is grabbed regardless of any modifiers, so this 304The accelerator key is grabbed regardless of any modifiers, so this
303extension will actually grab a physical key just for this function. 305extension will actually grab a physical key just for this function.
304 306
305If you want a quake-like animation, tell your window manager to do so 307If you want a quake-like animation, tell your window manager to do so
306(fvwm can do it). 308(fvwm can do it).
307 309
308=item automove-background 310=item overlay-osc
309 311
310This is basically a very small extension that dynamically changes the 312This extension implements some OSC commands to display timed popups on the
311background pixmap offset to the window position, in effect creating the 313screen - useful for status displays from within scripts. You have to read
312same effect as pseudo transparency with a custom pixmap. No scaling is 314the sources for more info.
313supported in this mode. Example:
314
315 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background
316
317L<http://wiki.archlinux.org/index.php/Perl_Background_Rotation/Extensions>
318shows how this extension can be used to implement an automatically blurred
319transparent background.
320 315
321=item block-graphics-to-ascii 316=item block-graphics-to-ascii
322 317
323A not very useful example of filtering all text output to the terminal 318A not very useful example of filtering all text output to the terminal
324by replacing all line-drawing characters (U+2500 .. U+259F) by a 319by replacing all line-drawing characters (U+2500 .. U+259F) by a
329Displays a digital clock using the built-in overlay. 324Displays a digital clock using the built-in overlay.
330 325
331=item remote-clipboard 326=item remote-clipboard
332 327
333Somewhat of a misnomer, this extension adds two menu entries to the 328Somewhat of a misnomer, this extension adds two menu entries to the
334selection popup that allows one ti run external commands to store the 329selection popup that allows one to run external commands to store the
335selection somewhere and fetch it again. 330selection somewhere and fetch it again.
336 331
337We use it to implement a "distributed selection mechanism", which just 332We use it to implement a "distributed selection mechanism", which just
338means that one command uploads the file to a remote server, and another 333means that one command uploads the file to a remote server, and another
339reads it. 334reads it.
348 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection' 343 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
349 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection' 344 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
350 345
351=item selection-pastebin 346=item selection-pastebin
352 347
353This is a little rarely useful extension that Uploads the selection as 348This is a little rarely useful extension that uploads the selection as
354textfile to a remote site (or does other things). (The implementation is 349textfile to a remote site (or does other things). (The implementation is
355not currently secure for use in a multiuser environment as it writes to 350not currently secure for use in a multiuser environment as it writes to
356F</tmp> directly.). 351F</tmp> directly.).
357 352
358It listens to the C<selection-pastebin:remote-pastebin> keyboard command, 353It listens to the C<selection-pastebin:remote-pastebin> keyboard command,
377 372
378 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/% 373 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
379 374
380I<Note to xrdb users:> xrdb uses the C preprocessor, which might interpret 375I<Note to xrdb users:> xrdb uses the C preprocessor, which might interpret
381the double C</> characters as comment start. Use C<\057\057> instead, 376the double C</> characters as comment start. Use C<\057\057> instead,
382which works regardless of wether xrdb is used to parse the resource file 377which works regardless of whether xrdb is used to parse the resource file
383or not. 378or not.
379
380=item macosx-clipboard and macosx-clipboard-native
381
382These two modules implement an extended clipboard for Mac OS X. They are
383used like this:
384
385 URxvt.perl-ext-common: default,macosx-clipboard
386 URxvt.keysym.M-c: perl:macosx-clipboard:copy
387 URxvt.keysym.M-v: perl:macosx-clipboard:paste
388
389The difference between them is that the native variant requires a
390perl from apple's devkit or so, and C<macosx-clipboard> requires the
391C<Mac::Pasteboard> module, works with other perls, has fewer bugs, is
392simpler etc. etc.
384 393
385=item example-refresh-hooks 394=item example-refresh-hooks
386 395
387Displays a very simple digital clock in the upper right corner of the 396Displays a very simple digital clock in the upper right corner of the
388window. Illustrates overwriting the refresh callbacks to create your own 397window. Illustrates overwriting the refresh callbacks to create your own
389overlays or changes. 398overlays or changes.
399
400=item confirm-paste
401
402Displays a confirmation dialog when a paste containing at least a full
403line is detected.
390 404
391=back 405=back
392 406
393=head1 API DOCUMENTATION 407=head1 API DOCUMENTATION
394 408
410 424
411=over 4 425=over 4
412 426
413=item $text 427=item $text
414 428
415Rxvt-unicodes special way of encoding text, where one "unicode" character 429Rxvt-unicode's special way of encoding text, where one "unicode" character
416always represents one screen cell. See L<ROW_t> for a discussion of this format. 430always represents one screen cell. See L<ROW_t> for a discussion of this format.
417 431
418=item $string 432=item $string
419 433
420A perl text string, with an emphasis on I<text>. It can store all unicode 434A perl text string, with an emphasis on I<text>. It can store all unicode
429=back 443=back
430 444
431=head2 Extension Objects 445=head2 Extension Objects
432 446
433Every perl extension is a perl class. A separate perl object is created 447Every perl extension is a perl class. A separate perl object is created
434for each terminal, and each terminal has its own set of extenion objects, 448for each terminal, and each terminal has its own set of extension objects,
435which are passed as the first parameter to hooks. So extensions can use 449which are passed as the first parameter to hooks. So extensions can use
436their C<$self> object without having to think about clashes with other 450their C<$self> object without having to think about clashes with other
437extensions or other terminals, with the exception of methods and members 451extensions or other terminals, with the exception of methods and members
438that begin with an underscore character C<_>: these are reserved for 452that begin with an underscore character C<_>: these are reserved for
439internal use. 453internal use.
554 568
555It is called before lines are scrolled out (so rows 0 .. min ($lines - 1, 569It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
556$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total 570$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
557number of lines that will be in the scrollback buffer. 571number of lines that will be in the scrollback buffer.
558 572
559=item on_osc_seq $term, $op, $args 573=item on_osc_seq $term, $op, $args, $resp
560 574
561Called on every OSC sequence and can be used to suppress it or modify its 575Called on every OSC sequence and can be used to suppress it or modify its
562behaviour. The default should be to return an empty list. A true value 576behaviour. The default should be to return an empty list. A true value
563suppresses execution of the request completely. Make sure you don't get 577suppresses execution of the request completely. Make sure you don't get
564confused by recursive invocations when you output an osc sequence within 578confused by recursive invocations when you output an OSC sequence within
565this callback. 579this callback.
566 580
567C<on_osc_seq_perl> should be used for new behaviour. 581C<on_osc_seq_perl> should be used for new behaviour.
568 582
569=item on_osc_seq_perl $term, $string 583=item on_osc_seq_perl $term, $args, $resp
570 584
571Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 585Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
572operating system command) is processed. Cursor position and other state 586operating system command) is processed. Cursor position and other state
573information is up-to-date when this happens. For interoperability, the 587information is up-to-date when this happens. For interoperability, the
574string should start with the extension name and a colon, to distinguish 588string should start with the extension name (sans -osc) and a semicolon,
575it from commands for other extensions, and this might be enforced in the 589to distinguish it from commands for other extensions, and this might be
576future. 590enforced in the future.
591
592For example, C<overlay-osc> uses this:
593
594 sub on_osc_seq_perl {
595 my ($self, $osc, $resp) = @_;
596
597 return unless $osc =~ s/^overlay;//;
598
599 ... process remaining $osc string
600 }
577 601
578Be careful not ever to trust (in a security sense) the data you receive, 602Be careful not ever to trust (in a security sense) the data you receive,
579as its source can not easily be controlled (e-mail content, messages from 603as its source can not easily be controlled (e-mail content, messages from
580other users on the same system etc.). 604other users on the same system etc.).
605
606For responses, C<$resp> contains the end-of-args separator used by the
607sender.
581 608
582=item on_add_lines $term, $string 609=item on_add_lines $term, $string
583 610
584Called whenever text is about to be output, with the text as argument. You 611Called whenever text is about to be output, with the text as argument. You
585can filter/change and output the text yourself by returning a true value 612can filter/change and output the text yourself by returning a true value
590=item on_tt_write $term, $octets 617=item on_tt_write $term, $octets
591 618
592Called whenever some data is written to the tty/pty and can be used to 619Called whenever some data is written to the tty/pty and can be used to
593suppress or filter tty input. 620suppress or filter tty input.
594 621
622=item on_tt_paste $term, $octets
623
624Called whenever text is about to be pasted, with the text as argument. You
625can filter/change and paste the text yourself by returning a true value
626and calling C<< $term->tt_paste >> yourself. C<$octets> is
627locale-encoded.
628
595=item on_line_update $term, $row 629=item on_line_update $term, $row
596 630
597Called whenever a line was updated or changed. Can be used to filter 631Called whenever a line was updated or changed. Can be used to filter
598screen output (e.g. underline urls or other useless stuff). Only lines 632screen output (e.g. underline urls or other useless stuff). Only lines
599that are being shown will be filtered, and, due to performance reasons, 633that are being shown will be filtered, and, due to performance reasons,
606later with the already-modified line (e.g. if unrelated parts change), so 640later with the already-modified line (e.g. if unrelated parts change), so
607you cannot just toggle rendition bits, but only set them. 641you cannot just toggle rendition bits, but only set them.
608 642
609=item on_refresh_begin $term 643=item on_refresh_begin $term
610 644
611Called just before the screen gets redrawn. Can be used for overlay 645Called just before the screen gets redrawn. Can be used for overlay or
612or similar effects by modify terminal contents in refresh_begin, and 646similar effects by modifying the terminal contents in refresh_begin, and
613restoring them in refresh_end. The built-in overlay and selection display 647restoring them in refresh_end. The built-in overlay and selection display
614code is run after this hook, and takes precedence. 648code is run after this hook, and takes precedence.
615 649
616=item on_refresh_end $term 650=item on_refresh_end $term
617 651
624resource in the @@RXVT_NAME@@(1) manpage). 658resource in the @@RXVT_NAME@@(1) manpage).
625 659
626The event is simply the action string. This interface is assumed to change 660The event is simply the action string. This interface is assumed to change
627slightly in the future. 661slightly in the future.
628 662
629=item on_resize_all_windows $tern, $new_width, $new_height 663=item on_resize_all_windows $term, $new_width, $new_height
630 664
631Called just after the new window size has been calculated, but before 665Called just after the new window size has been calculated, but before
632windows are actually being resized or hints are being set. If this hook 666windows are actually being resized or hints are being set. If this hook
633returns TRUE, setting of the window hints is being skipped. 667returns TRUE, setting of the window hints is being skipped.
634 668
668 702
669=item on_map_notify $term, $event 703=item on_map_notify $term, $event
670 704
671=item on_unmap_notify $term, $event 705=item on_unmap_notify $term, $event
672 706
673Called whenever the corresponding X event is received for the terminal If 707Called whenever the corresponding X event is received for the terminal. If
674the hook returns true, then the even will be ignored by rxvt-unicode. 708the hook returns true, then the event will be ignored by rxvt-unicode.
675 709
676The event is a hash with most values as named by Xlib (see the XEvent 710The event is a hash with most values as named by Xlib (see the XEvent
677manpage), with the additional members C<row> and C<col>, which are the 711manpage), with the additional members C<row> and C<col>, which are the
678(real, not screen-based) row and column under the mouse cursor. 712(real, not screen-based) row and column under the mouse cursor.
679 713
688 722
689=item on_wm_delete_window $term, $event 723=item on_wm_delete_window $term, $event
690 724
691Called when various types of ClientMessage events are received (all with 725Called when various types of ClientMessage events are received (all with
692format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW). 726format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
727
728=item on_bell $term
729
730Called on receipt of a bell character.
693 731
694=back 732=back
695 733
696=cut 734=cut
697 735
762 800
763=over 4 801=over 4
764 802
765=item urxvt::fatal $errormessage 803=item urxvt::fatal $errormessage
766 804
767Fatally aborts execution with the given error message. Avoid at all 805Fatally aborts execution with the given error message (which should
768costs! The only time this is acceptable is when the terminal process 806include a trailing newline). Avoid at all costs! The only time this
769starts up. 807is acceptable (and useful) is in the init hook, where it prevents the
808terminal from starting up.
770 809
771=item urxvt::warn $string 810=item urxvt::warn $string
772 811
773Calls C<rxvt_warn> with the given string which should not include a 812Calls C<rxvt_warn> with the given string which should include a trailing
774newline. The module also overwrites the C<warn> builtin with a function 813newline. The module also overwrites the C<warn> builtin with a function
775that calls this function. 814that calls this function.
776 815
777Using this function has the advantage that its output ends up in the 816Using this function has the advantage that its output ends up in the
778correct place, e.g. on stderr of the connecting urxvtc client. 817correct place, e.g. on stderr of the connecting urxvtc client.
782=item @terms = urxvt::termlist 821=item @terms = urxvt::termlist
783 822
784Returns all urxvt::term objects that exist in this process, regardless of 823Returns all urxvt::term objects that exist in this process, regardless of
785whether they are started, being destroyed etc., so be careful. Only term 824whether they are started, being destroyed etc., so be careful. Only term
786objects that have perl extensions attached will be returned (because there 825objects that have perl extensions attached will be returned (because there
787is no urxvt::term objet associated with others). 826is no urxvt::term object associated with others).
788 827
789=item $time = urxvt::NOW 828=item $time = urxvt::NOW
790 829
791Returns the "current time" (as per the event loop). 830Returns the "current time" (as per the event loop).
792 831
835 874
836=item $rend = urxvt::OVERLAY_RSTYLE 875=item $rend = urxvt::OVERLAY_RSTYLE
837 876
838Return the rendition mask used for overlays by default. 877Return the rendition mask used for overlays by default.
839 878
840=item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline 879=item $rendbit = urxvt::RS_Bold, urxvt::RS_Italic, urxvt::RS_Blink,
880urxvt::RS_RVid, urxvt::RS_Uline
841 881
842Return the bit that enabled bold, italic, blink, reverse-video and 882Return the bit that enabled bold, italic, blink, reverse-video and
843underline, respectively. To enable such a style, just logically OR it into 883underline, respectively. To enable such a style, just logically OR it into
844the bitset. 884the bitset.
845 885
928 local $TERM = shift; 968 local $TERM = shift;
929 my $htype = shift; 969 my $htype = shift;
930 970
931 if ($htype == 0) { # INIT 971 if ($htype == 0) { # INIT
932 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 972 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
933 973
934 my %ext_arg; 974 my %ext_arg;
935 975
936 { 976 {
937 my @init = @TERM_INIT; 977 my @init = @TERM_INIT;
938 @TERM_INIT = (); 978 @TERM_INIT = ();
1104is that you cannot use blocking APIs, but the non-blocking variant should 1144is that you cannot use blocking APIs, but the non-blocking variant should
1105work. 1145work.
1106 1146
1107=cut 1147=cut
1108 1148
1109our $VERSION = 1; 1149our $VERSION = '5.23';
1110 1150
1111$INC{"urxvt/anyevent.pm"} = 1; # mark us as there 1151$INC{"urxvt/anyevent.pm"} = 1; # mark us as there
1112push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::]; 1152push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
1113 1153
1114sub timer { 1154sub timer {
1116 1156
1117 my $cb = $arg{cb}; 1157 my $cb = $arg{cb};
1118 1158
1119 urxvt::timer 1159 urxvt::timer
1120 ->new 1160 ->new
1121 ->start (urxvt::NOW + $arg{after}) 1161 ->after ($arg{after}, $arg{interval})
1122 ->cb (sub { 1162 ->cb ($arg{interval} ? $cb : sub {
1123 $_[0]->stop; # need to cancel manually 1163 $_[0]->stop; # need to cancel manually
1124 $cb->(); 1164 $cb->();
1125 }) 1165 })
1126} 1166}
1127 1167
1128sub io { 1168sub io {
1129 my ($class, %arg) = @_; 1169 my ($class, %arg) = @_;
1130 1170
1131 my $cb = $arg{cb}; 1171 my $cb = $arg{cb};
1172 my $fd = fileno $arg{fh};
1173 defined $fd or $fd = $arg{fh};
1132 1174
1133 bless [$arg{fh}, urxvt::iow 1175 bless [$arg{fh}, urxvt::iow
1134 ->new 1176 ->new
1135 ->fd (fileno $arg{fh}) 1177 ->fd ($fd)
1136 ->events (($arg{poll} =~ /r/ ? 1 : 0) 1178 ->events (($arg{poll} =~ /r/ ? 1 : 0)
1137 | ($arg{poll} =~ /w/ ? 2 : 0)) 1179 | ($arg{poll} =~ /w/ ? 2 : 0))
1138 ->start 1180 ->start
1139 ->cb (sub { 1181 ->cb ($cb)
1140 $cb->(($_[1] & 1 ? 'r' : '')
1141 . ($_[1] & 2 ? 'w' : ''));
1142 })],
1143 urxvt::anyevent:: 1182 ], urxvt::anyevent::
1183}
1184
1185sub idle {
1186 my ($class, %arg) = @_;
1187
1188 my $cb = $arg{cb};
1189
1190 urxvt::iw
1191 ->new
1192 ->start
1193 ->cb ($cb)
1194}
1195
1196sub child {
1197 my ($class, %arg) = @_;
1198
1199 my $cb = $arg{cb};
1200
1201 urxvt::pw
1202 ->new
1203 ->start ($arg{pid})
1204 ->cb (sub {
1205 $_[0]->stop; # need to cancel manually
1206 $cb->($_[0]->rpid, $_[0]->rstatus);
1207 })
1144} 1208}
1145 1209
1146sub DESTROY { 1210sub DESTROY {
1147 $_[0][1]->stop; 1211 $_[0][1]->stop;
1148}
1149
1150sub condvar {
1151 bless \my $flag, urxvt::anyevent::
1152}
1153
1154sub broadcast {
1155 ${$_[0]}++;
1156}
1157
1158sub wait {
1159 unless (${$_[0]}) {
1160 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API";
1161 }
1162} 1212}
1163 1213
1164sub one_event { 1214sub one_event {
1165 Carp::croak "AnyEvent->one_event blocking wait unsupported in urxvt, use a non-blocking API"; 1215 Carp::croak "AnyEvent->one_event blocking wait unsupported in urxvt, use a non-blocking API";
1166} 1216}
1260C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash. 1310C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
1261 1311
1262Here is a likely non-exhaustive list of option names, please see the 1312Here is a likely non-exhaustive list of option names, please see the
1263source file F</src/optinc.h> to see the actual list: 1313source file F</src/optinc.h> to see the actual list:
1264 1314
1265 borderLess console cursorBlink cursorUnderline hold iconic insecure 1315 borderLess buffered console cursorBlink cursorUnderline hold iconic
1266 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 1316 insecure intensityStyles iso14755 iso14755_52 jumpScroll loginShell
1267 override-redirect pastableTabs pointerBlank reverseVideo scrollBar 1317 mapAlert meta8 mouseWheelScrollPage override_redirect pastableTabs
1268 scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput 1318 pointerBlank reverseVideo scrollBar scrollBar_floating scrollBar_right
1269 scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs 1319 scrollTtyKeypress scrollTtyOutput scrollWithBuffer secondaryScreen
1270 transparent tripleclickwords utmpInhibit visualBell 1320 secondaryScroll skipBuiltinGlyphs skipScroll transparent tripleclickwords
1321 urgentOnBell utmpInhibit visualBell
1271 1322
1272=item $value = $term->resource ($name[, $newval]) 1323=item $value = $term->resource ($name[, $newval])
1273 1324
1274Returns the current resource value associated with a given name and 1325Returns the current resource value associated with a given name and
1275optionally sets a new value. Setting values is most useful in the C<init> 1326optionally sets a new value. Setting values is most useful in the C<init>
1288 1339
1289Here is a likely non-exhaustive list of resource names, not all of which 1340Here is a likely non-exhaustive list of resource names, not all of which
1290are supported in every build, please see the source file F</src/rsinc.h> 1341are supported in every build, please see the source file F</src/rsinc.h>
1291to see the actual list: 1342to see the actual list:
1292 1343
1293 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1344 answerbackstring backgroundPixmap backspace_key blendtype blurradius
1294 borderLess color cursorBlink cursorUnderline cutchars delete_key 1345 boldFont boldItalicFont borderLess buffered chdir color cursorBlink
1295 display_name embed ext_bwidth fade font geometry hold iconName 1346 cursorUnderline cutchars delete_key depth display_name embed ext_bwidth
1296 imFont imLocale inputMethod insecure int_bwidth intensityStyles 1347 fade font geometry hold iconName iconfile imFont imLocale inputMethod
1348 insecure int_bwidth intensityStyles iso14755 iso14755_52 italicFont
1297 italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier 1349 jumpScroll letterSpace lineSpace loginShell mapAlert meta8 modifier
1298 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval 1350 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
1299 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay 1351 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
1300 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar 1352 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
1301 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness 1353 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
1302 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle 1354 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
1303 secondaryScreen secondaryScroll selectstyle shade term_name title 1355 secondaryScreen secondaryScroll shade skipBuiltinGlyphs skipScroll
1304 transient_for transparent transparent_all tripleclickwords utmpInhibit 1356 term_name title transient_for transparent tripleclickwords urgentOnBell
1305 visualBell 1357 utmpInhibit visualBell
1306 1358
1307=cut 1359=cut
1308 1360
1309sub resource($$;$) { 1361sub resource($$;$) {
1310 my ($self, $name) = (shift, shift); 1362 my ($self, $name) = (shift, shift);
1311 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 1363 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
1312 &urxvt::term::_resource 1364 goto &urxvt::term::_resource
1313} 1365}
1314 1366
1315=item $value = $term->x_resource ($pattern) 1367=item $value = $term->x_resource ($pattern)
1316 1368
1317Returns the X-Resource for the given pattern, excluding the program or 1369Returns the X-Resource for the given pattern, excluding the program or
1342 1394
1343=item ($row, $col) = $term->selection_beg ([$row, $col]) 1395=item ($row, $col) = $term->selection_beg ([$row, $col])
1344 1396
1345=item ($row, $col) = $term->selection_end ([$row, $col]) 1397=item ($row, $col) = $term->selection_end ([$row, $col])
1346 1398
1347Return the current values of the selection mark, begin or end positions, 1399Return the current values of the selection mark, begin or end positions.
1348and optionally set them to new values. 1400
1401When arguments are given, then the selection coordinates are set to
1402C<$row> and C<$col>, and the selection screen is set to the current
1403screen.
1404
1405=item $screen = $term->selection_screen ([$screen])
1406
1407Returns the current selection screen, and then optionally sets it.
1349 1408
1350=item $term->selection_make ($eventtime[, $rectangular]) 1409=item $term->selection_make ($eventtime[, $rectangular])
1351 1410
1352Tries to make a selection as set by C<selection_beg> and 1411Tries to make a selection as set by C<selection_beg> and
1353C<selection_end>. If C<$rectangular> is true (default: false), a 1412C<selection_end>. If C<$rectangular> is true (default: false), a
1354rectangular selection will be made. This is the prefered function to make 1413rectangular selection will be made. This is the preferred function to make
1355a selection. 1414a selection.
1356 1415
1357=item $success = $term->selection_grab ($eventtime) 1416=item $success = $term->selection_grab ($eventtime[, $clipboard])
1358 1417
1359Try to request the primary selection text from the server (for example, as 1418Try to acquire ownership of the primary (clipboard if C<$clipboard> is
1419true) selection from the server. The corresponding text can be set
1360set by the next method). No visual feedback will be given. This function 1420with the next method. No visual feedback will be given. This function
1361is mostly useful from within C<on_sel_grab> hooks. 1421is mostly useful from within C<on_sel_grab> hooks.
1362 1422
1363=item $oldtext = $term->selection ([$newtext]) 1423=item $oldtext = $term->selection ([$newtext, $clipboard])
1364 1424
1365Return the current selection text and optionally replace it by C<$newtext>. 1425Return the current selection (clipboard if C<$clipboard> is true) text
1426and optionally replace it by C<$newtext>.
1427
1428=item $term->selection_clear ([$clipboard])
1429
1430Revoke ownership of the primary (clipboard if C<$clipboard> is true) selection.
1366 1431
1367=item $term->overlay_simple ($x, $y, $text) 1432=item $term->overlay_simple ($x, $y, $text)
1368 1433
1369Create a simple multi-line overlay box. See the next method for details. 1434Create a simple multi-line overlay box. See the next method for details.
1370 1435
1400 1465
1401The methods currently supported on C<urxvt::overlay> objects are: 1466The methods currently supported on C<urxvt::overlay> objects are:
1402 1467
1403=over 4 1468=over 4
1404 1469
1405=item $overlay->set ($x, $y, $text, $rend) 1470=item $overlay->set ($x, $y, $text[, $rend])
1406 1471
1407Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts 1472Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts
1408text in rxvt-unicode's special encoding and an array of rendition values 1473text in rxvt-unicode's special encoding and an array of rendition values
1409at a specific position inside the overlay. 1474at a specific position inside the overlay.
1475
1476If C<$rend> is missing, then the rendition will not be changed.
1410 1477
1411=item $overlay->hide 1478=item $overlay->hide
1412 1479
1413If visible, hide the overlay, but do not destroy it. 1480If visible, hide the overlay, but do not destroy it.
1414 1481
1496locale-specific encoding of the terminal and can contain command sequences 1563locale-specific encoding of the terminal and can contain command sequences
1497(escape codes) that will be interpreted. 1564(escape codes) that will be interpreted.
1498 1565
1499=item $term->tt_write ($octets) 1566=item $term->tt_write ($octets)
1500 1567
1501Write the octets given in C<$data> to the tty (i.e. as program input). To 1568Write the octets given in C<$octets> to the tty (i.e. as program input). To
1502pass characters instead of octets, you should convert your strings first 1569pass characters instead of octets, you should convert your strings first
1503to the locale-specific encoding using C<< $term->locale_encode >>. 1570to the locale-specific encoding using C<< $term->locale_encode >>.
1571
1572=item $term->tt_paste ($octets)
1573
1574Write the octets given in C<$octets> to the tty as a paste, converting NL to
1575CR and bracketing the data with control sequences if bracketed paste mode
1576is set.
1504 1577
1505=item $old_events = $term->pty_ev_events ([$new_events]) 1578=item $old_events = $term->pty_ev_events ([$new_events])
1506 1579
1507Replaces the event mask of the pty watcher by the given event mask. Can 1580Replaces the event mask of the pty watcher by the given event mask. Can
1508be used to suppress input and output handling to the pty/tty. See the 1581be used to suppress input and output handling to the pty/tty. See the
1624 1697
1625Used after changing terminal contents to display them. 1698Used after changing terminal contents to display them.
1626 1699
1627=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]]) 1700=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
1628 1701
1629Returns the text of the entire row with number C<$row_number>. Row C<0> 1702Returns the text of the entire row with number C<$row_number>. Row C<< $term->top_row >>
1630is the topmost terminal line, row C<< $term->$ncol-1 >> is the bottommost 1703is the topmost terminal line, row C<< $term->nrow-1 >> is the bottommost
1631terminal line. The scrollback buffer starts at line C<-1> and extends to
1632line C<< -$term->nsaved >>. Nothing will be returned if a nonexistent line 1704terminal line. Nothing will be returned if a nonexistent line
1633is requested. 1705is requested.
1634 1706
1635If C<$new_text> is specified, it will replace characters in the current 1707If C<$new_text> is specified, it will replace characters in the current
1636line, starting at column C<$start_col> (default C<0>), which is useful 1708line, starting at column C<$start_col> (default C<0>), which is useful
1637to replace only parts of a line. The font index in the rendition will 1709to replace only parts of a line. The font index in the rendition will
1638automatically be updated. 1710automatically be updated.
1639 1711
1640C<$text> is in a special encoding: tabs and wide characters that use more 1712C<$text> is in a special encoding: tabs and wide characters that use more
1641than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535) 1713than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535)
1642characters. Characters with combining characters and other characters that 1714characters. Characters with combining characters and other characters that
1643do not fit into the normal tetx encoding will be replaced with characters 1715do not fit into the normal text encoding will be replaced with characters
1644in the private use area. 1716in the private use area.
1645 1717
1646You have to obey this encoding when changing text. The advantage is 1718You have to obey this encoding when changing text. The advantage is
1647that C<substr> and similar functions work on screen cells and not on 1719that C<substr> and similar functions work on screen cells and not on
1648characters. 1720characters.
1823Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most 1895Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most
1824recent grab. 1896recent grab.
1825 1897
1826=item $term->ungrab 1898=item $term->ungrab
1827 1899
1828Calls XUngrab for the most recent grab. Is called automatically on 1900Calls XUngrabPointer and XUngrabKeyboard for the most recent grab. Is called automatically on
1829evaluation errors, as it is better to lose the grab in the error case as 1901evaluation errors, as it is better to lose the grab in the error case as
1830the session. 1902the session.
1831 1903
1832=item $atom = $term->XInternAtom ($atom_name[, $only_if_exists]) 1904=item $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
1833 1905
1835 1907
1836=item @atoms = $term->XListProperties ($window) 1908=item @atoms = $term->XListProperties ($window)
1837 1909
1838=item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property) 1910=item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
1839 1911
1840=item $term->XChangeWindowProperty ($window, $property, $type, $format, $octets) 1912=item $term->XChangeProperty ($window, $property, $type, $format, $octets)
1841 1913
1842=item $term->XDeleteProperty ($window, $property) 1914=item $term->XDeleteProperty ($window, $property)
1843 1915
1844=item $window = $term->DefaultRootWindow 1916=item $window = $term->DefaultRootWindow
1845 1917
1855 1927
1856=item $term->XChangeInput ($window, $add_events[, $del_events]) 1928=item $term->XChangeInput ($window, $add_events[, $del_events])
1857 1929
1858Various X or X-related functions. The C<$term> object only serves as 1930Various X or X-related functions. The C<$term> object only serves as
1859the source of the display, otherwise those functions map more-or-less 1931the source of the display, otherwise those functions map more-or-less
1860directory onto the X functions of the same name. 1932directly onto the X functions of the same name.
1861 1933
1862=back 1934=back
1863 1935
1864=cut 1936=cut
1865 1937
1967 my $env = $self->{term}->env; 2039 my $env = $self->{term}->env;
1968 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE. 2040 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
1969 delete $env->{LC_ALL}; 2041 delete $env->{LC_ALL};
1970 $env->{LC_CTYPE} = $self->{term}->locale; 2042 $env->{LC_CTYPE} = $self->{term}->locale;
1971 2043
1972 urxvt::term->new ($env, "popup", 2044 my $term = urxvt::term->new (
2045 $env, "popup",
1973 "--perl-lib" => "", "--perl-ext-common" => "", 2046 "--perl-lib" => "", "--perl-ext-common" => "",
1974 "-pty-fd" => -1, "-sl" => 0, 2047 "-pty-fd" => -1, "-sl" => 0,
1975 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect", 2048 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect",
1976 "--transient-for" => $self->{term}->parent, 2049 "--transient-for" => $self->{term}->parent,
1977 "-display" => $self->{term}->display_id, 2050 "-display" => $self->{term}->display_id,
1978 "-pe" => "urxvt-popup") 2051 "-pe" => "urxvt-popup",
1979 or die "unable to create popup window\n"; 2052 ) or die "unable to create popup window\n";
2053
2054 unless (delete $term->{urxvt_popup_init_done}) {
2055 $term->ungrab;
2056 $term->destroy;
2057 die "unable to initialise popup window\n";
2058 }
1980} 2059}
1981 2060
1982sub DESTROY { 2061sub DESTROY {
1983 my ($self) = @_; 2062 my ($self) = @_;
1984 2063
2002 ->new 2081 ->new
2003 ->interval (1) 2082 ->interval (1)
2004 ->cb (sub { 2083 ->cb (sub {
2005 $term->{overlay}->set (0, 0, 2084 $term->{overlay}->set (0, 0,
2006 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]); 2085 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
2007 }); 2086 });
2008 2087
2009=over 4 2088=over 4
2010 2089
2011=item $timer = new urxvt::timer 2090=item $timer = new urxvt::timer
2012 2091
2015 2094
2016=item $timer = $timer->cb (sub { my ($timer) = @_; ... }) 2095=item $timer = $timer->cb (sub { my ($timer) = @_; ... })
2017 2096
2018Set the callback to be called when the timer triggers. 2097Set the callback to be called when the timer triggers.
2019 2098
2020=item $tstamp = $timer->at
2021
2022Return the time this watcher will fire next.
2023
2024=item $timer = $timer->set ($tstamp) 2099=item $timer = $timer->set ($tstamp[, $interval])
2025 2100
2026Set the time the event is generated to $tstamp. 2101Set the time the event is generated to $tstamp (and optionally specifies a
2102new $interval).
2027 2103
2028=item $timer = $timer->interval ($interval) 2104=item $timer = $timer->interval ($interval)
2029 2105
2030Normally (and when C<$interval> is C<0>), the timer will automatically 2106By default (and when C<$interval> is C<0>), the timer will automatically
2031stop after it has fired once. If C<$interval> is non-zero, then the timer 2107stop after it has fired once. If C<$interval> is non-zero, then the timer
2032is automatically rescheduled at the given intervals. 2108is automatically rescheduled at the given intervals.
2033 2109
2034=item $timer = $timer->start 2110=item $timer = $timer->start
2035 2111
2036Start the timer. 2112Start the timer.
2037 2113
2038=item $timer = $timer->start ($tstamp) 2114=item $timer = $timer->start ($tstamp[, $interval])
2039 2115
2040Set the event trigger time to C<$tstamp> and start the timer. 2116Set the event trigger time to C<$tstamp> and start the timer. Optionally
2117also replaces the interval.
2041 2118
2042=item $timer = $timer->after ($delay) 2119=item $timer = $timer->after ($delay[, $interval])
2043 2120
2044Like C<start>, but sets the expiry timer to c<urxvt::NOW + $delay>. 2121Like C<start>, but sets the expiry timer to c<urxvt::NOW + $delay>.
2045 2122
2046=item $timer = $timer->stop 2123=item $timer = $timer->stop
2047 2124
2055 2132
2056 $term->{socket} = ... 2133 $term->{socket} = ...
2057 $term->{iow} = urxvt::iow 2134 $term->{iow} = urxvt::iow
2058 ->new 2135 ->new
2059 ->fd (fileno $term->{socket}) 2136 ->fd (fileno $term->{socket})
2060 ->events (urxvt::EVENT_READ) 2137 ->events (urxvt::EV_READ)
2061 ->start 2138 ->start
2062 ->cb (sub { 2139 ->cb (sub {
2063 my ($iow, $revents) = @_; 2140 my ($iow, $revents) = @_;
2064 # $revents must be 1 here, no need to check 2141 # $revents must be 1 here, no need to check
2065 sysread $term->{socket}, my $buf, 8192 2142 sysread $term->{socket}, my $buf, 8192
2083Set the file descriptor (not handle) to watch. 2160Set the file descriptor (not handle) to watch.
2084 2161
2085=item $iow = $iow->events ($eventmask) 2162=item $iow = $iow->events ($eventmask)
2086 2163
2087Set the event mask to watch. The only allowed values are 2164Set the event mask to watch. The only allowed values are
2088C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed 2165C<urxvt::EV_READ> and C<urxvt::EV_WRITE>, which might be ORed
2089together, or C<urxvt::EVENT_NONE>. 2166together, or C<urxvt::EV_NONE>.
2090 2167
2091=item $iow = $iow->start 2168=item $iow = $iow->start
2092 2169
2093Start watching for requested events on the given handle. 2170Start watching for requested events on the given handle.
2094 2171
2135 ->new 2212 ->new
2136 ->start ($pid) 2213 ->start ($pid)
2137 ->cb (sub { 2214 ->cb (sub {
2138 my ($pw, $exit_status) = @_; 2215 my ($pw, $exit_status) = @_;
2139 ... 2216 ...
2140 }); 2217 });
2141 2218
2142=over 4 2219=over 4
2143 2220
2144=item $pw = new urxvt::pw 2221=item $pw = new urxvt::pw
2145 2222
2178 2255
2179=back 2256=back
2180 2257
2181=head1 AUTHOR 2258=head1 AUTHOR
2182 2259
2183 Marc Lehmann <pcg@goof.com> 2260 Marc Lehmann <schmorp@schmorp.de>
2184 http://software.schmorp.de/pkg/rxvt-unicode 2261 http://software.schmorp.de/pkg/rxvt-unicode
2185 2262
2186=cut 2263=cut
2187 2264
21881 22651

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines