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.111 by root, Thu Jan 19 19:52:54 2006 UTC vs.
Revision 1.133 by root, Mon Feb 6 06:14:08 2006 UTC

67the match. For example, the followign adds a regex that matches everything 67the match. For example, the followign adds a regex that matches everything
68between two vertical bars: 68between two vertical bars:
69 69
70 URxvt.selection.pattern-0: \\|([^|]+)\\| 70 URxvt.selection.pattern-0: \\|([^|]+)\\|
71 71
72Another example: Programs I use often output "absolute path: " at the
73beginning of a line when they process multiple files. The following
74pattern matches the filename (note, there is a single space at the very
75end):
76
77 URxvt.selection.pattern-0: ^(/[^:]+):\
78
72You can look at the source of the selection extension to see more 79You can look at the source of the selection extension to see more
73interesting uses, such as parsing a line from beginning to end. 80interesting uses, such as parsing a line from beginning to end.
74 81
75This extension also offers following bindable keyboard commands: 82This extension also offers following bindable keyboard commands:
76 83
87=item option-popup (enabled by default) 94=item option-popup (enabled by default)
88 95
89Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at 96Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at
90runtime. 97runtime.
91 98
99Other extensions can extend this popup menu by pushing a code reference
100onto C<@{ $term->{option_popup_hook} }>, which gets called whenever the
101popup is being displayed.
102
103It's sole argument is the popup menu, which can be modified. It should
104either return nothing or a string, the initial boolean value and a code
105reference. The string will be used as button text and the code reference
106will be called when the toggle changes, with the new boolean value as
107first argument.
108
109The following will add an entry C<myoption> that changes
110C<$self->{myoption}>:
111
112 push @{ $self->{term}{option_popup_hook} }, sub {
113 ("my option" => $myoption, sub { $self->{myoption} = $_[0] })
114 };
115
92=item selection-popup (enabled by default) 116=item selection-popup (enabled by default)
93 117
94Binds a popup menu to Ctrl-Button3 that lets you convert the selection 118Binds a popup menu to Ctrl-Button3 that lets you convert the selection
95text into various other formats/action (such as uri unescaping, perl 119text into various other formats/action (such as uri unescaping, perl
96evalution, web-browser starting etc.), depending on content. 120evaluation, web-browser starting etc.), depending on content.
97 121
98Other extensions can extend this popup menu by pushing a code reference 122Other extensions can extend this popup menu by pushing a code reference
99onto C<@{ $term->{selection_popup_hook} }>, that is called whenever the 123onto C<@{ $term->{selection_popup_hook} }>, which gets called whenever the
100popup is displayed. 124popup is being displayed.
101 125
102It's sole argument is the popup menu, which can be modified. The selection 126It's sole argument is the popup menu, which can be modified. The selection
103is in C<$_>, which can be used to decide wether to add something or not. 127is in C<$_>, which can be used to decide wether to add something or not.
104It should either return nothing or a string and a code reference. The 128It should either return nothing or a string and a code reference. The
105string will be used as button text and the code reference will be called 129string will be used as button text and the code reference will be called
127bottom. C<Escape> leaves search mode and returns to the point where search 151bottom. C<Escape> leaves search mode and returns to the point where search
128was started, while C<Enter> or C<Return> stay at the current position and 152was started, while C<Enter> or C<Return> stay at the current position and
129additionally stores the first match in the current line into the primary 153additionally stores the first match in the current line into the primary
130selection. 154selection.
131 155
156=item readline (enabled by default)
157
158A support package that tries to make editing with readline easier. At the
159moment, it reacts to clicking with the left mouse button by trying to
160move 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
162for programs that correctly support wide characters).
163
164To avoid too many false positives, this is only done when:
165
166=over 4
167
168=item - the tty is in ICANON state.
169
170=item - the text cursor is visible.
171
172=item - the primary screen is currently being displayed.
173
174=item - the mouse is on the same (multi-row-) line as the text cursor.
175
176=back
177
178The normal selection mechanism isn't disabled, so quick successive clicks
179might interfere with selection creation in harmless ways.
180
132=item selection-autotransform 181=item selection-autotransform
133 182
134This selection allows you to do automatic transforms on a selection 183This selection allows you to do automatic transforms on a selection
135whenever a selection is made. 184whenever a selection is made.
136 185
161 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/ 210 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/
162 211
163The first line tells the selection code to treat the unchanging part of 212The first line tells the selection code to treat the unchanging part of
164every error message as a selection pattern, and the second line transforms 213every error message as a selection pattern, and the second line transforms
165the message into vi commands to load the file. 214the message into vi commands to load the file.
215
216=item tabbed
217
218This transforms the terminal into a tabbar with additional terminals, that
219is, it implements what is commonly refered to as "tabbed terminal". The topmost line
220displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one
221button per tab.
222
223Clicking 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,
225while B<Shift-Down> creates a new tab.
226
227The tabbar itself can be configured similarly to a normal terminal, but
228with a resource class of C<URxvt.tabbed>. In addition, it supports the
229following four resources (shown with defaults):
230
231 URxvt.tabbed.tabbar-fg: <colour-index, default 3>
232 URxvt.tabbed.tabbar-bg: <colour-index, default 0>
233 URxvt.tabbed.tab-fg: <colour-index, default 0>
234 URxvt.tabbed.tab-bg: <colour-index, default 1>
235
236See I<COLOR AND GRAPHICS> in the @@RXVT_NAME@@(1) manpage for valid
237indices.
166 238
167=item mark-urls 239=item mark-urls
168 240
169Uses per-line display filtering (C<on_line_update>) to underline urls and 241Uses per-line display filtering (C<on_line_update>) to underline urls and
170make them clickable. When middle-clicked, the program specified in the 242make them clickable. When middle-clicked, the program specified in the
171resource C<urlLauncher> (default C<x-www-browser>) will be started with 243resource C<urlLauncher> (default C<x-www-browser>) will be started with
172the URL as first argument. 244the URL as first argument.
173 245
246=item xim-onthespot
247
248This (experimental) perl extension implements OnTheSpot editing. It does
249not 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
251kinput2.
252
253You enable it by specifying this extension and a preedit style of
254C<OnTheSpot>, i.e.:
255
256 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot
257
174=item automove-background 258=item automove-background
175 259
176This is basically a one-line extension that dynamically changes the background pixmap offset 260This is basically a one-line extension that dynamically changes the background pixmap offset
177to the window position, in effect creating the same effect as pseudo transparency with 261to the window position, in effect creating the same effect as pseudo transparency with
178a custom pixmap. No scaling is supported in this mode. Exmaple: 262a custom pixmap. No scaling is supported in this mode. Exmaple:
187 271
188=item digital-clock 272=item digital-clock
189 273
190Displays a digital clock using the built-in overlay. 274Displays a digital clock using the built-in overlay.
191 275
192=item example-refresh-hooks 276=item remote-clipboard
193 277
194Displays a very simple digital clock in the upper right corner of the 278Somewhat of a misnomer, this extension adds two menu entries to the
195window. Illustrates overwriting the refresh callbacks to create your own 279selection popup that allows one ti run external commands to store the
196overlays or changes. 280selection somewhere and fetch it again.
281
282We use it to implement a "distributed selection mechanism", which just
283means that one command uploads the file to a remote server, and another
284reads it.
285
286The commands can be set using the C<URxvt.remote-selection.store> and
287C<URxvt.remote-selection.fetch> resources. The first should read the
288selection to store from STDIN (always in UTF-8), the second should provide
289the selection data on STDOUT (also in UTF-8).
290
291The defaults (which are likely useless to you) use rsh and cat:
292
293 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
294 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
197 295
198=item selection-pastebin 296=item selection-pastebin
199 297
200This is a little rarely useful extension that Uploads the selection as 298This is a little rarely useful extension that Uploads the selection as
201textfile to a remote site (or does other things). (The implementation is 299textfile to a remote site (or does other things). (The implementation is
221After a successful upload the selection will be replaced by the text given 319After a successful upload the selection will be replaced by the text given
222in the C<selection-pastebin-url> resource (again, the % is the placeholder 320in the C<selection-pastebin-url> resource (again, the % is the placeholder
223for the filename): 321for the filename):
224 322
225 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/% 323 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
324
325=item example-refresh-hooks
326
327Displays a very simple digital clock in the upper right corner of the
328window. Illustrates overwriting the refresh callbacks to create your own
329overlays or changes.
226 330
227=back 331=back
228 332
229=head1 API DOCUMENTATION 333=head1 API DOCUMENTATION
230 334
303called whenever the relevant event happens. 407called whenever the relevant event happens.
304 408
305The first argument passed to them is an extension oject as described in 409The first argument passed to them is an extension oject as described in
306the in the C<Extension Objects> section. 410the in the C<Extension Objects> section.
307 411
308B<All> of these hooks must return a boolean value. If it is true, then the 412B<All> of these hooks must return a boolean value. If any of the called
309event counts as being I<consumed>, and the invocation of other hooks is 413hooks returns true, then the event counts as being I<consumed>, and the
310skipped, and the relevant action might not be carried out by the C++ code. 414relevant action might not be carried out by the C++ code.
311 415
312I<< When in doubt, return a false value (preferably C<()>). >> 416I<< When in doubt, return a false value (preferably C<()>). >>
313 417
314=over 4 418=over 4
315 419
316=item on_init $term 420=item on_init $term
317 421
318Called after a new terminal object has been initialized, but before 422Called after a new terminal object has been initialized, but before
319windows are created or the command gets run. Most methods are unsafe to 423windows are created or the command gets run. Most methods are unsafe to
320call or deliver senseless data, as terminal size and other characteristics 424call or deliver senseless data, as terminal size and other characteristics
321have not yet been determined. You can safely query and change resources, 425have not yet been determined. You can safely query and change resources
322though. 426and options, though. For many purposes the C<on_start> hook is a better
427place.
428
429=item on_start $term
430
431Called at the very end of initialisation of a new terminal, just before
432trying to map (display) the toplevel and returning to the mainloop.
433
434=item on_destroy $term
435
436Called whenever something tries to destroy terminal, when the terminal is
437still fully functional (not for long, though).
323 438
324=item on_reset $term 439=item on_reset $term
325 440
326Called after the screen is "reset" for any reason, such as resizing or 441Called after the screen is "reset" for any reason, such as resizing or
327control sequences. Here is where you can react on changes to size-related 442control sequences. Here is where you can react on changes to size-related
328variables. 443variables.
329
330=item on_start $term
331
332Called at the very end of initialisation of a new terminal, just before
333returning to the mainloop.
334 444
335=item on_child_start $term, $pid 445=item on_child_start $term, $pid
336 446
337Called just after the child process has been C<fork>ed. 447Called just after the child process has been C<fork>ed.
338 448
434 544
435=item on_refresh_end $term 545=item on_refresh_end $term
436 546
437Called just after the screen gets redrawn. See C<on_refresh_begin>. 547Called just after the screen gets redrawn. See C<on_refresh_begin>.
438 548
439=item on_keyboard_command $term, $string 549=item on_user_command $term, $string
440 550
441Called whenever the user presses a key combination that has a 551Called whenever the a user-configured event is being activated (e.g. via
442C<perl:string> action bound to it (see description of the B<keysym> 552a C<perl:string> action bound to a key, see description of the B<keysym>
443resource in the @@RXVT_NAME@@(1) manpage). 553resource in the @@RXVT_NAME@@(1) manpage).
554
555The event is simply the action string. This interface is assumed to change
556slightly in the future.
444 557
445=item on_x_event $term, $event 558=item on_x_event $term, $event
446 559
447Called on every X event received on the vt window (and possibly other 560Called on every X event received on the vt window (and possibly other
448windows). Should only be used as a last resort. Most event structure 561windows). Should only be used as a last resort. Most event structure
458Called wheneever the window loses keyboard focus, before rxvt-unicode does 571Called wheneever the window loses keyboard focus, before rxvt-unicode does
459focus out processing. 572focus out processing.
460 573
461=item on_configure_notify $term, $event 574=item on_configure_notify $term, $event
462 575
576=item on_property_notify $term, $event
577
463=item on_key_press $term, $event, $keysym, $octets 578=item on_key_press $term, $event, $keysym, $octets
464 579
465=item on_key_release $term, $event, $keysym 580=item on_key_release $term, $event, $keysym
466 581
467=item on_button_press $term, $event 582=item on_button_press $term, $event
476 591
477Called whenever the corresponding X event is received for the terminal If 592Called whenever the corresponding X event is received for the terminal If
478the hook returns true, then the even will be ignored by rxvt-unicode. 593the hook returns true, then the even will be ignored by rxvt-unicode.
479 594
480The event is a hash with most values as named by Xlib (see the XEvent 595The event is a hash with most values as named by Xlib (see the XEvent
481manpage), with the additional members C<row> and C<col>, which are the row 596manpage), with the additional members C<row> and C<col>, which are the
482and column under the mouse cursor. 597(real, not screen-based) row and column under the mouse cursor.
483 598
484C<on_key_press> additionally receives the string rxvt-unicode would 599C<on_key_press> additionally receives the string rxvt-unicode would
485output, if any, in locale-specific encoding. 600output, if any, in locale-specific encoding.
486 601
487subwindow. 602subwindow.
603
604=item on_client_message $term, $event
605
606=item on_wm_protocols $term, $event
607
608=item on_wm_delete_window $term, $event
609
610Called when various types of ClientMessage events are received (all with
611format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
488 612
489=back 613=back
490 614
491=cut 615=cut
492 616
498use Scalar::Util (); 622use Scalar::Util ();
499use List::Util (); 623use List::Util ();
500 624
501our $VERSION = 1; 625our $VERSION = 1;
502our $TERM; 626our $TERM;
627our @TERM_INIT;
628our @TERM_EXT;
503our @HOOKNAME; 629our @HOOKNAME;
504our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME; 630our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
505our %OPTION; 631our %OPTION;
506 632
507our $LIBDIR; 633our $LIBDIR;
508our $RESNAME; 634our $RESNAME;
509our $RESCLASS; 635our $RESCLASS;
510our $RXVTNAME; 636our $RXVTNAME;
511 637
638our $NOCHAR = chr 0xffff;
639
512=head2 Variables in the C<urxvt> Package 640=head2 Variables in the C<urxvt> Package
513 641
514=over 4 642=over 4
515 643
516=item $urxvt::LIBDIR 644=item $urxvt::LIBDIR
528 656
529=item $urxvt::TERM 657=item $urxvt::TERM
530 658
531The current terminal. This variable stores the current C<urxvt::term> 659The current terminal. This variable stores the current C<urxvt::term>
532object, whenever a callback/hook is executing. 660object, whenever a callback/hook is executing.
661
662=item @urxvt::TERM_INIT
663
664All coderefs in this array will be called as methods of the next newly
665created C<urxvt::term> object (during the C<on_init> phase). The array
666gets cleared before the codereferences that were in it are being executed,
667so coderefs can push themselves onto it again if they so desire.
668
669This complements to the perl-eval commandline option, but gets executed
670first.
671
672=item @urxvt::TERM_EXT
673
674Works similar to C<@TERM_INIT>, but contains perl package/class names, which
675get registered as normal extensions after calling the hooks in C<@TERM_INIT>
676but before other extensions. Gets cleared just like C<@TERM_INIT>.
533 677
534=back 678=back
535 679
536=head2 Functions in the C<urxvt> Package 680=head2 Functions in the C<urxvt> Package
537 681
551 695
552Using this function has the advantage that its output ends up in the 696Using this function has the advantage that its output ends up in the
553correct place, e.g. on stderr of the connecting urxvtc client. 697correct place, e.g. on stderr of the connecting urxvtc client.
554 698
555Messages have a size limit of 1023 bytes currently. 699Messages have a size limit of 1023 bytes currently.
700
701=item @terms = urxvt::termlist
702
703Returns all urxvt::term objects that exist in this process, regardless of
704wether they are started, being destroyed etc., so be careful. Only term
705objects that have perl extensions attached will be returned (because there
706is no urxvt::term objet associated with others).
556 707
557=item $time = urxvt::NOW 708=item $time = urxvt::NOW
558 709
559Returns the "current time" (as per the event loop). 710Returns the "current time" (as per the event loop).
560 711
618Return the foreground/background colour index, respectively. 769Return the foreground/background colour index, respectively.
619 770
620=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour 771=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
621 772
622=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour 773=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
774
775=item $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
623 776
624Replace the foreground/background colour in the rendition mask with the 777Replace the foreground/background colour in the rendition mask with the
625specified one. 778specified one.
626 779
627=item $value = urxvt::GET_CUSTOM $rend 780=item $value = urxvt::GET_CUSTOM $rend
646 unless $msg =~ /\n$/; 799 unless $msg =~ /\n$/;
647 urxvt::warn ($msg); 800 urxvt::warn ($msg);
648 }; 801 };
649} 802}
650 803
804no warnings 'utf8';
805
651my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 806my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
652 807
653sub verbose { 808sub verbose {
654 my ($level, $msg) = @_; 809 my ($level, $msg) = @_;
655 warn "$msg\n" if $level <= $verbosity; 810 warn "$msg\n" if $level <= $verbosity;
658my %extension_pkg; 813my %extension_pkg;
659 814
660# load a single script into its own package, once only 815# load a single script into its own package, once only
661sub extension_package($) { 816sub extension_package($) {
662 my ($path) = @_; 817 my ($path) = @_;
663
664 no strict 'refs';
665 818
666 $extension_pkg{$path} ||= do { 819 $extension_pkg{$path} ||= do {
667 $path =~ /([^\/\\]+)$/; 820 $path =~ /([^\/\\]+)$/;
668 my $pkg = $1; 821 my $pkg = $1;
669 $pkg =~ s/[^[:word:]]/_/g; 822 $pkg =~ s/[^[:word:]]/_/g;
672 verbose 3, "loading extension '$path' into package '$pkg'"; 825 verbose 3, "loading extension '$path' into package '$pkg'";
673 826
674 open my $fh, "<:raw", $path 827 open my $fh, "<:raw", $path
675 or die "$path: $!"; 828 or die "$path: $!";
676 829
677 @{"$pkg\::ISA"} = urxvt::term::extension::;
678
679 my $source = 830 my $source =
680 "package $pkg; use strict; use utf8;\n" 831 "package $pkg; use strict; use utf8; no warnings 'utf8';\n"
681 . "#line 1 \"$path\"\n{\n" 832 . "#line 1 \"$path\"\n{\n"
682 . (do { local $/; <$fh> }) 833 . (do { local $/; <$fh> })
683 . "\n};\n1"; 834 . "\n};\n1";
684 835
685 eval $source 836 eval $source
699 if ($htype == 0) { # INIT 850 if ($htype == 0) { # INIT
700 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 851 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
701 852
702 my %ext_arg; 853 my %ext_arg;
703 854
855 {
856 my @init = @TERM_INIT;
857 @TERM_INIT = ();
858 $_->($TERM) for @init;
859 my @pkg = @TERM_EXT;
860 @TERM_EXT = ();
861 $TERM->register_package ($_) for @pkg;
862 }
863
704 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) { 864 for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
705 if ($_ eq "default") { 865 if ($_ eq "default") {
706 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback); 866 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback readline);
707 } elsif (/^-(.*)$/) { 867 } elsif (/^-(.*)$/) {
708 delete $ext_arg{$1}; 868 delete $ext_arg{$1};
709 } elsif (/^([^<]+)<(.*)>$/) { 869 } elsif (/^([^<]+)<(.*)>$/) {
710 push @{ $ext_arg{$1} }, $2; 870 push @{ $ext_arg{$1} }, $2;
711 } else { 871 } else {
712 $ext_arg{$_} ||= []; 872 $ext_arg{$_} ||= [];
713 } 873 }
714 } 874 }
715 875
716 while (my ($ext, $argv) = each %ext_arg) { 876 for my $ext (sort keys %ext_arg) {
717 my @files = grep -f $_, map "$_/$ext", @dirs; 877 my @files = grep -f $_, map "$_/$ext", @dirs;
718 878
719 if (@files) { 879 if (@files) {
720 $TERM->register_package (extension_package $files[0], $argv); 880 $TERM->register_package (extension_package $files[0], $ext_arg{$ext});
721 } else { 881 } else {
722 warn "perl extension '$ext' not found in perl library search path\n"; 882 warn "perl extension '$ext' not found in perl library search path\n";
723 } 883 }
724 } 884 }
725 885
734 if $verbosity >= 10; 894 if $verbosity >= 10;
735 895
736 keys %$cb; 896 keys %$cb;
737 897
738 while (my ($pkg, $cb) = each %$cb) { 898 while (my ($pkg, $cb) = each %$cb) {
739 $retval = eval { $cb->($TERM->{_pkg}{$pkg}, @_) } 899 my $retval_ = eval { $cb->($TERM->{_pkg}{$pkg}, @_) };
740 and last; 900 $retval ||= $retval_;
741 901
742 if ($@) { 902 if ($@) {
743 $TERM->ungrab; # better to lose the grab than the session 903 $TERM->ungrab; # better to lose the grab than the session
744 warn $@; 904 warn $@;
745 } 905 }
756 # clear package 916 # clear package
757 %$TERM = (); 917 %$TERM = ();
758 } 918 }
759 919
760 $retval 920 $retval
921}
922
923sub SET_COLOR($$$) {
924 SET_BGCOLOR (SET_FGCOLOR ($_[0], $_[1]), $_[2])
761} 925}
762 926
763# urxvt::term::extension 927# urxvt::term::extension
764 928
765package urxvt::term::extension; 929package urxvt::term::extension;
904# find on_xxx subs in the package and register them 1068# find on_xxx subs in the package and register them
905# as hooks 1069# as hooks
906sub register_package { 1070sub register_package {
907 my ($self, $pkg, $argv) = @_; 1071 my ($self, $pkg, $argv) = @_;
908 1072
1073 no strict 'refs';
1074
1075 urxvt::verbose 6, "register package $pkg to $self";
1076
1077 @{"$pkg\::ISA"} = urxvt::term::extension::;
1078
909 my $proxy = bless { 1079 my $proxy = bless {
910 _pkg => $pkg, 1080 _pkg => $pkg,
911 argv => $argv, 1081 argv => $argv,
912 }, $pkg; 1082 }, $pkg;
913 Scalar::Util::weaken ($proxy->{term} = $self); 1083 Scalar::Util::weaken ($proxy->{term} = $self);
928hash which defines the environment of the new terminal. 1098hash which defines the environment of the new terminal.
929 1099
930Croaks (and probably outputs an error message) if the new instance 1100Croaks (and probably outputs an error message) if the new instance
931couldn't be created. Returns C<undef> if the new instance didn't 1101couldn't be created. Returns C<undef> if the new instance didn't
932initialise perl, and the terminal object otherwise. The C<init> and 1102initialise perl, and the terminal object otherwise. The C<init> and
933C<start> hooks will be called during this call. 1103C<start> hooks will be called before this call returns, and are free to
1104refer to global data (which is race free).
934 1105
935=cut 1106=cut
936 1107
937sub new { 1108sub new {
938 my ($class, $env, @args) = @_; 1109 my ($class, $env, @args) = @_;
939 1110
1111 $env or Carp::croak "environment hash missing in call to urxvt::term->new";
1112 @args or Carp::croak "name argument missing in call to urxvt::term->new";
1113
940 _new ([ map "$_=$env->{$_}", keys %$env ], @args); 1114 _new ([ map "$_=$env->{$_}", keys %$env ], \@args);
941} 1115}
942 1116
943=item $term->destroy 1117=item $term->destroy
944 1118
945Destroy the terminal object (close the window, free resources 1119Destroy the terminal object (close the window, free resources
1202 1376
1203Normally its not a good idea to use this function, as programs might be 1377Normally its not a good idea to use this function, as programs might be
1204confused by changes in cursor position or scrolling. Its useful inside a 1378confused by changes in cursor position or scrolling. Its useful inside a
1205C<on_add_lines> hook, though. 1379C<on_add_lines> hook, though.
1206 1380
1381=item $term->scr_change_screen ($screen)
1382
1383Switch to given screen - 0 primary, 1 secondary.
1384
1207=item $term->cmd_parse ($octets) 1385=item $term->cmd_parse ($octets)
1208 1386
1209Similar to C<scr_add_lines>, but the argument must be in the 1387Similar to C<scr_add_lines>, but the argument must be in the
1210locale-specific encoding of the terminal and can contain command sequences 1388locale-specific encoding of the terminal and can contain command sequences
1211(escape codes) that will be interpreted. 1389(escape codes) that will be interpreted.
1221Replaces the event mask of the pty watcher by the given event mask. Can 1399Replaces the event mask of the pty watcher by the given event mask. Can
1222be used to suppress input and output handling to the pty/tty. See the 1400be used to suppress input and output handling to the pty/tty. See the
1223description of C<< urxvt::timer->events >>. Make sure to always restore 1401description of C<< urxvt::timer->events >>. Make sure to always restore
1224the previous value. 1402the previous value.
1225 1403
1404=item $fd = $term->pty_fd
1405
1406Returns the master file descriptor for the pty in use, or C<-1> if no pty
1407is used.
1408
1226=item $windowid = $term->parent 1409=item $windowid = $term->parent
1227 1410
1228Return the window id of the toplevel window. 1411Return the window id of the toplevel window.
1229 1412
1230=item $windowid = $term->vt 1413=item $windowid = $term->vt
1235 1418
1236Adds the specified events to the vt event mask. Useful e.g. when you want 1419Adds the specified events to the vt event mask. Useful e.g. when you want
1237to receive pointer events all the times: 1420to receive pointer events all the times:
1238 1421
1239 $term->vt_emask_add (urxvt::PointerMotionMask); 1422 $term->vt_emask_add (urxvt::PointerMotionMask);
1423
1424=item $term->focus_in
1425
1426=item $term->focus_out
1427
1428=item $term->key_press ($state, $keycode[, $time])
1429
1430=item $term->key_release ($state, $keycode[, $time])
1431
1432Deliver various fake events to to terminal.
1240 1433
1241=item $window_width = $term->width 1434=item $window_width = $term->width
1242 1435
1243=item $window_height = $term->height 1436=item $window_height = $term->height
1244 1437
1294=item $modifiermask = $term->ModNumLockMask 1487=item $modifiermask = $term->ModNumLockMask
1295 1488
1296Return the modifier masks corresponding to the "ISO Level 3 Shift" (often 1489Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
1297AltGr), the meta key (often Alt) and the num lock key, if applicable. 1490AltGr), the meta key (often Alt) and the num lock key, if applicable.
1298 1491
1492=item $screen = $term->current_screen
1493
1494Returns the currently displayed screen (0 primary, 1 secondary).
1495
1496=item $cursor_is_hidden = $term->hidden_cursor
1497
1498Returns wether the cursor is currently hidden or not.
1499
1299=item $view_start = $term->view_start ([$newvalue]) 1500=item $view_start = $term->view_start ([$newvalue])
1300 1501
1301Returns the row number of the topmost displayed line. Maximum value is 1502Returns the row number of the topmost displayed line. Maximum value is
1302C<0>, which displays the normal terminal contents. Lower values scroll 1503C<0>, which displays the normal terminal contents. Lower values scroll
1303this many lines into the scrollback buffer. 1504this many lines into the scrollback buffer.
1322line, starting at column C<$start_col> (default C<0>), which is useful 1523line, starting at column C<$start_col> (default C<0>), which is useful
1323to replace only parts of a line. The font index in the rendition will 1524to replace only parts of a line. The font index in the rendition will
1324automatically be updated. 1525automatically be updated.
1325 1526
1326C<$text> is in a special encoding: tabs and wide characters that use more 1527C<$text> is in a special encoding: tabs and wide characters that use more
1327than one cell when displayed are padded with urxvt::NOCHAR characters 1528than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535)
1328(C<chr 65535>). Characters with combining characters and other characters 1529characters. Characters with combining characters and other characters that
1329that do not fit into the normal tetx encoding will be replaced with 1530do not fit into the normal tetx encoding will be replaced with characters
1330characters in the private use area. 1531in the private use area.
1331 1532
1332You have to obey this encoding when changing text. The advantage is 1533You have to obey this encoding when changing text. The advantage is
1333that C<substr> and similar functions work on screen cells and not on 1534that C<substr> and similar functions work on screen cells and not on
1334characters. 1535characters.
1335 1536
1482=item $string = $term->special_decode $text 1683=item $string = $term->special_decode $text
1483 1684
1484Converts rxvt-unicodes text reprsentation into a perl string. See 1685Converts rxvt-unicodes text reprsentation into a perl string. See
1485C<< $term->ROW_t >> for details. 1686C<< $term->ROW_t >> for details.
1486 1687
1487=item $success = $term->grab_button ($button, $modifiermask) 1688=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1488 1689
1690=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1691
1489Registers a synchronous button grab. See the XGrabButton manpage. 1692Register/unregister a synchronous button grab. See the XGrabButton
1693manpage.
1490 1694
1491=item $success = $term->grab ($eventtime[, $sync]) 1695=item $success = $term->grab ($eventtime[, $sync])
1492 1696
1493Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1697Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1494synchronous (C<$sync> is true). Also remembers the grab timestampe. 1698synchronous (C<$sync> is true). Also remembers the grab timestampe.
1509=item $term->ungrab 1713=item $term->ungrab
1510 1714
1511Calls XUngrab for the most recent grab. Is called automatically on 1715Calls XUngrab for the most recent grab. Is called automatically on
1512evaluation errors, as it is better to lose the grab in the error case as 1716evaluation errors, as it is better to lose the grab in the error case as
1513the session. 1717the session.
1718
1719=item $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
1720
1721=item $atom_name = $term->XGetAtomName ($atom)
1722
1723=item @atoms = $term->XListProperties ($window)
1724
1725=item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
1726
1727=item $term->XChangeWindowProperty ($window, $property, $type, $format, $octets)
1728
1729=item $term->XDeleteProperty ($window, $property)
1730
1731=item $window = $term->DefaultRootWindow
1732
1733=item $term->XReparentWindow ($window, $parent, [$x, $y])
1734
1735=item $term->XMapWindow ($window)
1736
1737=item $term->XUnmapWindow ($window)
1738
1739=item $term->XMoveResizeWindow ($window, $x, $y, $width, $height)
1740
1741=item ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x, $y)
1742
1743=item $term->XChangeInput ($window, $add_events[, $del_events])
1744
1745Various X or X-related functions. The C<$term> object only serves as
1746the source of the display, otherwise those functions map more-or-less
1747directory onto the X functions of the same name.
1514 1748
1515=back 1749=back
1516 1750
1517=cut 1751=cut
1518 1752
1582 my ($self, $text, $cb) = @_; 1816 my ($self, $text, $cb) = @_;
1583 1817
1584 $self->add_item ({ type => "button", text => $text, activate => $cb}); 1818 $self->add_item ({ type => "button", text => $text, activate => $cb});
1585} 1819}
1586 1820
1587=item $popup->add_toggle ($text, $cb, $initial_value) 1821=item $popup->add_toggle ($text, $initial_value, $cb)
1588 1822
1589Adds a toggle/checkbox item to the popup. Teh callback gets called 1823Adds a toggle/checkbox item to the popup. The callback gets called
1590whenever it gets toggled, with a boolean indicating its value as its first 1824whenever it gets toggled, with a boolean indicating its new value as its
1591argument. 1825first argument.
1592 1826
1593=cut 1827=cut
1594 1828
1595sub add_toggle { 1829sub add_toggle {
1596 my ($self, $text, $cb, $value) = @_; 1830 my ($self, $text, $value, $cb) = @_;
1597 1831
1598 my $item; $item = { 1832 my $item; $item = {
1599 type => "button", 1833 type => "button",
1600 text => " $text", 1834 text => " $text",
1601 value => $value, 1835 value => $value,
1638 delete $self->{term}{_destroy}{$self}; 1872 delete $self->{term}{_destroy}{$self};
1639 $self->{term}->ungrab; 1873 $self->{term}->ungrab;
1640} 1874}
1641 1875
1642=back 1876=back
1877
1878=cut
1879
1880package urxvt::watcher;
1881
1882@urxvt::timer::ISA = __PACKAGE__;
1883@urxvt::iow::ISA = __PACKAGE__;
1884@urxvt::pw::ISA = __PACKAGE__;
1885@urxvt::iw::ISA = __PACKAGE__;
1643 1886
1644=head2 The C<urxvt::timer> Class 1887=head2 The C<urxvt::timer> Class
1645 1888
1646This class implements timer watchers/events. Time is represented as a 1889This class implements timer watchers/events. Time is represented as a
1647fractional number of seconds since the epoch. Example: 1890fractional number of seconds since the epoch. Example:
1745 1988
1746Stop watching for events on the given filehandle. 1989Stop watching for events on the given filehandle.
1747 1990
1748=back 1991=back
1749 1992
1993=head2 The C<urxvt::iw> Class
1994
1995This class implements idle watchers, that get called automatically when
1996the process is idle. They should return as fast as possible, after doing
1997some useful work.
1998
1999=over 4
2000
2001=item $iw = new urxvt::iw
2002
2003Create a new idle watcher object in stopped state.
2004
2005=item $iw = $iw->cb (sub { my ($iw) = @_; ... })
2006
2007Set the callback to be called when the watcher triggers.
2008
2009=item $timer = $timer->start
2010
2011Start the watcher.
2012
2013=item $timer = $timer->stop
2014
2015Stop the watcher.
2016
2017=back
2018
2019=head2 The C<urxvt::pw> Class
2020
2021This class implements process watchers. They create an event whenever a
2022process exits, after which they stop automatically.
2023
2024 my $pid = fork;
2025 ...
2026 $term->{pw} = urxvt::pw
2027 ->new
2028 ->start ($pid)
2029 ->cb (sub {
2030 my ($pw, $exit_status) = @_;
2031 ...
2032 });
2033
2034=over 4
2035
2036=item $pw = new urxvt::pw
2037
2038Create a new process watcher in stopped state.
2039
2040=item $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
2041
2042Set the callback to be called when the timer triggers.
2043
2044=item $pw = $timer->start ($pid)
2045
2046Tells the wqtcher to start watching for process C<$pid>.
2047
2048=item $pw = $pw->stop
2049
2050Stop the watcher.
2051
2052=back
2053
1750=head1 ENVIRONMENT 2054=head1 ENVIRONMENT
1751 2055
1752=head2 URXVT_PERL_VERBOSITY 2056=head2 URXVT_PERL_VERBOSITY
1753 2057
1754This variable controls the verbosity level of the perl extension. Higher 2058This variable controls the verbosity level of the perl extension. Higher

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines