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.135 by root, Sun Feb 12 05:31:53 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
159the 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
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.
557
558=item on_resize_all_windows $tern, $new_width, $new_height
559
560Called just after the new window size has been calculcated, but before
561windows are actually being resized or hints are being set. If this hook
562returns TRUE, setting of the window hints is being skipped.
444 563
445=item on_x_event $term, $event 564=item on_x_event $term, $event
446 565
447Called on every X event received on the vt window (and possibly other 566Called on every X event received on the vt window (and possibly other
448windows). Should only be used as a last resort. Most event structure 567windows). Should only be used as a last resort. Most event structure
458Called wheneever the window loses keyboard focus, before rxvt-unicode does 577Called wheneever the window loses keyboard focus, before rxvt-unicode does
459focus out processing. 578focus out processing.
460 579
461=item on_configure_notify $term, $event 580=item on_configure_notify $term, $event
462 581
582=item on_property_notify $term, $event
583
463=item on_key_press $term, $event, $keysym, $octets 584=item on_key_press $term, $event, $keysym, $octets
464 585
465=item on_key_release $term, $event, $keysym 586=item on_key_release $term, $event, $keysym
466 587
467=item on_button_press $term, $event 588=item on_button_press $term, $event
476 597
477Called whenever the corresponding X event is received for the terminal If 598Called whenever the corresponding X event is received for the terminal If
478the hook returns true, then the even will be ignored by rxvt-unicode. 599the hook returns true, then the even will be ignored by rxvt-unicode.
479 600
480The event is a hash with most values as named by Xlib (see the XEvent 601The 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 602manpage), with the additional members C<row> and C<col>, which are the
482and column under the mouse cursor. 603(real, not screen-based) row and column under the mouse cursor.
483 604
484C<on_key_press> additionally receives the string rxvt-unicode would 605C<on_key_press> additionally receives the string rxvt-unicode would
485output, if any, in locale-specific encoding. 606output, if any, in locale-specific encoding.
486 607
487subwindow. 608subwindow.
609
610=item on_client_message $term, $event
611
612=item on_wm_protocols $term, $event
613
614=item on_wm_delete_window $term, $event
615
616Called when various types of ClientMessage events are received (all with
617format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
488 618
489=back 619=back
490 620
491=cut 621=cut
492 622
498use Scalar::Util (); 628use Scalar::Util ();
499use List::Util (); 629use List::Util ();
500 630
501our $VERSION = 1; 631our $VERSION = 1;
502our $TERM; 632our $TERM;
633our @TERM_INIT;
634our @TERM_EXT;
503our @HOOKNAME; 635our @HOOKNAME;
504our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME; 636our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
505our %OPTION; 637our %OPTION;
506 638
507our $LIBDIR; 639our $LIBDIR;
508our $RESNAME; 640our $RESNAME;
509our $RESCLASS; 641our $RESCLASS;
510our $RXVTNAME; 642our $RXVTNAME;
511 643
644our $NOCHAR = chr 0xffff;
645
512=head2 Variables in the C<urxvt> Package 646=head2 Variables in the C<urxvt> Package
513 647
514=over 4 648=over 4
515 649
516=item $urxvt::LIBDIR 650=item $urxvt::LIBDIR
528 662
529=item $urxvt::TERM 663=item $urxvt::TERM
530 664
531The current terminal. This variable stores the current C<urxvt::term> 665The current terminal. This variable stores the current C<urxvt::term>
532object, whenever a callback/hook is executing. 666object, whenever a callback/hook is executing.
667
668=item @urxvt::TERM_INIT
669
670All coderefs in this array will be called as methods of the next newly
671created C<urxvt::term> object (during the C<on_init> phase). The array
672gets cleared before the codereferences that were in it are being executed,
673so coderefs can push themselves onto it again if they so desire.
674
675This complements to the perl-eval commandline option, but gets executed
676first.
677
678=item @urxvt::TERM_EXT
679
680Works similar to C<@TERM_INIT>, but contains perl package/class names, which
681get registered as normal extensions after calling the hooks in C<@TERM_INIT>
682but before other extensions. Gets cleared just like C<@TERM_INIT>.
533 683
534=back 684=back
535 685
536=head2 Functions in the C<urxvt> Package 686=head2 Functions in the C<urxvt> Package
537 687
551 701
552Using this function has the advantage that its output ends up in the 702Using this function has the advantage that its output ends up in the
553correct place, e.g. on stderr of the connecting urxvtc client. 703correct place, e.g. on stderr of the connecting urxvtc client.
554 704
555Messages have a size limit of 1023 bytes currently. 705Messages have a size limit of 1023 bytes currently.
706
707=item @terms = urxvt::termlist
708
709Returns all urxvt::term objects that exist in this process, regardless of
710wether they are started, being destroyed etc., so be careful. Only term
711objects that have perl extensions attached will be returned (because there
712is no urxvt::term objet associated with others).
556 713
557=item $time = urxvt::NOW 714=item $time = urxvt::NOW
558 715
559Returns the "current time" (as per the event loop). 716Returns the "current time" (as per the event loop).
560 717
618Return the foreground/background colour index, respectively. 775Return the foreground/background colour index, respectively.
619 776
620=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour 777=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
621 778
622=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour 779=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
780
781=item $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
623 782
624Replace the foreground/background colour in the rendition mask with the 783Replace the foreground/background colour in the rendition mask with the
625specified one. 784specified one.
626 785
627=item $value = urxvt::GET_CUSTOM $rend 786=item $value = urxvt::GET_CUSTOM $rend
646 unless $msg =~ /\n$/; 805 unless $msg =~ /\n$/;
647 urxvt::warn ($msg); 806 urxvt::warn ($msg);
648 }; 807 };
649} 808}
650 809
810no warnings 'utf8';
811
651my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 812my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
652 813
653sub verbose { 814sub verbose {
654 my ($level, $msg) = @_; 815 my ($level, $msg) = @_;
655 warn "$msg\n" if $level <= $verbosity; 816 warn "$msg\n" if $level <= $verbosity;
658my %extension_pkg; 819my %extension_pkg;
659 820
660# load a single script into its own package, once only 821# load a single script into its own package, once only
661sub extension_package($) { 822sub extension_package($) {
662 my ($path) = @_; 823 my ($path) = @_;
663
664 no strict 'refs';
665 824
666 $extension_pkg{$path} ||= do { 825 $extension_pkg{$path} ||= do {
667 $path =~ /([^\/\\]+)$/; 826 $path =~ /([^\/\\]+)$/;
668 my $pkg = $1; 827 my $pkg = $1;
669 $pkg =~ s/[^[:word:]]/_/g; 828 $pkg =~ s/[^[:word:]]/_/g;
672 verbose 3, "loading extension '$path' into package '$pkg'"; 831 verbose 3, "loading extension '$path' into package '$pkg'";
673 832
674 open my $fh, "<:raw", $path 833 open my $fh, "<:raw", $path
675 or die "$path: $!"; 834 or die "$path: $!";
676 835
677 @{"$pkg\::ISA"} = urxvt::term::extension::;
678
679 my $source = 836 my $source =
680 "package $pkg; use strict; use utf8;\n" 837 "package $pkg; use strict; use utf8; no warnings 'utf8';\n"
681 . "#line 1 \"$path\"\n{\n" 838 . "#line 1 \"$path\"\n{\n"
682 . (do { local $/; <$fh> }) 839 . (do { local $/; <$fh> })
683 . "\n};\n1"; 840 . "\n};\n1";
684 841
685 eval $source 842 eval $source
699 if ($htype == 0) { # INIT 856 if ($htype == 0) { # INIT
700 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 857 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
701 858
702 my %ext_arg; 859 my %ext_arg;
703 860
861 {
862 my @init = @TERM_INIT;
863 @TERM_INIT = ();
864 $_->($TERM) for @init;
865 my @pkg = @TERM_EXT;
866 @TERM_EXT = ();
867 $TERM->register_package ($_) for @pkg;
868 }
869
704 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) { 870 for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
705 if ($_ eq "default") { 871 if ($_ eq "default") {
706 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback); 872 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback readline);
707 } elsif (/^-(.*)$/) { 873 } elsif (/^-(.*)$/) {
708 delete $ext_arg{$1}; 874 delete $ext_arg{$1};
709 } elsif (/^([^<]+)<(.*)>$/) { 875 } elsif (/^([^<]+)<(.*)>$/) {
710 push @{ $ext_arg{$1} }, $2; 876 push @{ $ext_arg{$1} }, $2;
711 } else { 877 } else {
712 $ext_arg{$_} ||= []; 878 $ext_arg{$_} ||= [];
713 } 879 }
714 } 880 }
715 881
716 while (my ($ext, $argv) = each %ext_arg) { 882 for my $ext (sort keys %ext_arg) {
717 my @files = grep -f $_, map "$_/$ext", @dirs; 883 my @files = grep -f $_, map "$_/$ext", @dirs;
718 884
719 if (@files) { 885 if (@files) {
720 $TERM->register_package (extension_package $files[0], $argv); 886 $TERM->register_package (extension_package $files[0], $ext_arg{$ext});
721 } else { 887 } else {
722 warn "perl extension '$ext' not found in perl library search path\n"; 888 warn "perl extension '$ext' not found in perl library search path\n";
723 } 889 }
724 } 890 }
725 891
734 if $verbosity >= 10; 900 if $verbosity >= 10;
735 901
736 keys %$cb; 902 keys %$cb;
737 903
738 while (my ($pkg, $cb) = each %$cb) { 904 while (my ($pkg, $cb) = each %$cb) {
739 $retval = eval { $cb->($TERM->{_pkg}{$pkg}, @_) } 905 my $retval_ = eval { $cb->($TERM->{_pkg}{$pkg}, @_) };
740 and last; 906 $retval ||= $retval_;
741 907
742 if ($@) { 908 if ($@) {
743 $TERM->ungrab; # better to lose the grab than the session 909 $TERM->ungrab; # better to lose the grab than the session
744 warn $@; 910 warn $@;
745 } 911 }
756 # clear package 922 # clear package
757 %$TERM = (); 923 %$TERM = ();
758 } 924 }
759 925
760 $retval 926 $retval
927}
928
929sub SET_COLOR($$$) {
930 SET_BGCOLOR (SET_FGCOLOR ($_[0], $_[1]), $_[2])
761} 931}
762 932
763# urxvt::term::extension 933# urxvt::term::extension
764 934
765package urxvt::term::extension; 935package urxvt::term::extension;
904# find on_xxx subs in the package and register them 1074# find on_xxx subs in the package and register them
905# as hooks 1075# as hooks
906sub register_package { 1076sub register_package {
907 my ($self, $pkg, $argv) = @_; 1077 my ($self, $pkg, $argv) = @_;
908 1078
1079 no strict 'refs';
1080
1081 urxvt::verbose 6, "register package $pkg to $self";
1082
1083 @{"$pkg\::ISA"} = urxvt::term::extension::;
1084
909 my $proxy = bless { 1085 my $proxy = bless {
910 _pkg => $pkg, 1086 _pkg => $pkg,
911 argv => $argv, 1087 argv => $argv,
912 }, $pkg; 1088 }, $pkg;
913 Scalar::Util::weaken ($proxy->{term} = $self); 1089 Scalar::Util::weaken ($proxy->{term} = $self);
928hash which defines the environment of the new terminal. 1104hash which defines the environment of the new terminal.
929 1105
930Croaks (and probably outputs an error message) if the new instance 1106Croaks (and probably outputs an error message) if the new instance
931couldn't be created. Returns C<undef> if the new instance didn't 1107couldn't be created. Returns C<undef> if the new instance didn't
932initialise perl, and the terminal object otherwise. The C<init> and 1108initialise perl, and the terminal object otherwise. The C<init> and
933C<start> hooks will be called during this call. 1109C<start> hooks will be called before this call returns, and are free to
1110refer to global data (which is race free).
934 1111
935=cut 1112=cut
936 1113
937sub new { 1114sub new {
938 my ($class, $env, @args) = @_; 1115 my ($class, $env, @args) = @_;
939 1116
1117 $env or Carp::croak "environment hash missing in call to urxvt::term->new";
1118 @args or Carp::croak "name argument missing in call to urxvt::term->new";
1119
940 _new ([ map "$_=$env->{$_}", keys %$env ], @args); 1120 _new ([ map "$_=$env->{$_}", keys %$env ], \@args);
941} 1121}
942 1122
943=item $term->destroy 1123=item $term->destroy
944 1124
945Destroy the terminal object (close the window, free resources 1125Destroy the terminal object (close the window, free resources
1202 1382
1203Normally its not a good idea to use this function, as programs might be 1383Normally 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 1384confused by changes in cursor position or scrolling. Its useful inside a
1205C<on_add_lines> hook, though. 1385C<on_add_lines> hook, though.
1206 1386
1387=item $term->scr_change_screen ($screen)
1388
1389Switch to given screen - 0 primary, 1 secondary.
1390
1207=item $term->cmd_parse ($octets) 1391=item $term->cmd_parse ($octets)
1208 1392
1209Similar to C<scr_add_lines>, but the argument must be in the 1393Similar to C<scr_add_lines>, but the argument must be in the
1210locale-specific encoding of the terminal and can contain command sequences 1394locale-specific encoding of the terminal and can contain command sequences
1211(escape codes) that will be interpreted. 1395(escape codes) that will be interpreted.
1221Replaces the event mask of the pty watcher by the given event mask. Can 1405Replaces 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 1406be used to suppress input and output handling to the pty/tty. See the
1223description of C<< urxvt::timer->events >>. Make sure to always restore 1407description of C<< urxvt::timer->events >>. Make sure to always restore
1224the previous value. 1408the previous value.
1225 1409
1410=item $fd = $term->pty_fd
1411
1412Returns the master file descriptor for the pty in use, or C<-1> if no pty
1413is used.
1414
1226=item $windowid = $term->parent 1415=item $windowid = $term->parent
1227 1416
1228Return the window id of the toplevel window. 1417Return the window id of the toplevel window.
1229 1418
1230=item $windowid = $term->vt 1419=item $windowid = $term->vt
1235 1424
1236Adds the specified events to the vt event mask. Useful e.g. when you want 1425Adds the specified events to the vt event mask. Useful e.g. when you want
1237to receive pointer events all the times: 1426to receive pointer events all the times:
1238 1427
1239 $term->vt_emask_add (urxvt::PointerMotionMask); 1428 $term->vt_emask_add (urxvt::PointerMotionMask);
1429
1430=item $term->focus_in
1431
1432=item $term->focus_out
1433
1434=item $term->key_press ($state, $keycode[, $time])
1435
1436=item $term->key_release ($state, $keycode[, $time])
1437
1438Deliver various fake events to to terminal.
1240 1439
1241=item $window_width = $term->width 1440=item $window_width = $term->width
1242 1441
1243=item $window_height = $term->height 1442=item $window_height = $term->height
1244 1443
1294=item $modifiermask = $term->ModNumLockMask 1493=item $modifiermask = $term->ModNumLockMask
1295 1494
1296Return the modifier masks corresponding to the "ISO Level 3 Shift" (often 1495Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
1297AltGr), the meta key (often Alt) and the num lock key, if applicable. 1496AltGr), the meta key (often Alt) and the num lock key, if applicable.
1298 1497
1498=item $screen = $term->current_screen
1499
1500Returns the currently displayed screen (0 primary, 1 secondary).
1501
1502=item $cursor_is_hidden = $term->hidden_cursor
1503
1504Returns wether the cursor is currently hidden or not.
1505
1299=item $view_start = $term->view_start ([$newvalue]) 1506=item $view_start = $term->view_start ([$newvalue])
1300 1507
1301Returns the row number of the topmost displayed line. Maximum value is 1508Returns the row number of the topmost displayed line. Maximum value is
1302C<0>, which displays the normal terminal contents. Lower values scroll 1509C<0>, which displays the normal terminal contents. Lower values scroll
1303this many lines into the scrollback buffer. 1510this many lines into the scrollback buffer.
1322line, starting at column C<$start_col> (default C<0>), which is useful 1529line, 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 1530to replace only parts of a line. The font index in the rendition will
1324automatically be updated. 1531automatically be updated.
1325 1532
1326C<$text> is in a special encoding: tabs and wide characters that use more 1533C<$text> is in a special encoding: tabs and wide characters that use more
1327than one cell when displayed are padded with urxvt::NOCHAR characters 1534than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535)
1328(C<chr 65535>). Characters with combining characters and other characters 1535characters. Characters with combining characters and other characters that
1329that do not fit into the normal tetx encoding will be replaced with 1536do not fit into the normal tetx encoding will be replaced with characters
1330characters in the private use area. 1537in the private use area.
1331 1538
1332You have to obey this encoding when changing text. The advantage is 1539You have to obey this encoding when changing text. The advantage is
1333that C<substr> and similar functions work on screen cells and not on 1540that C<substr> and similar functions work on screen cells and not on
1334characters. 1541characters.
1335 1542
1482=item $string = $term->special_decode $text 1689=item $string = $term->special_decode $text
1483 1690
1484Converts rxvt-unicodes text reprsentation into a perl string. See 1691Converts rxvt-unicodes text reprsentation into a perl string. See
1485C<< $term->ROW_t >> for details. 1692C<< $term->ROW_t >> for details.
1486 1693
1487=item $success = $term->grab_button ($button, $modifiermask) 1694=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1488 1695
1696=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1697
1489Registers a synchronous button grab. See the XGrabButton manpage. 1698Register/unregister a synchronous button grab. See the XGrabButton
1699manpage.
1490 1700
1491=item $success = $term->grab ($eventtime[, $sync]) 1701=item $success = $term->grab ($eventtime[, $sync])
1492 1702
1493Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1703Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1494synchronous (C<$sync> is true). Also remembers the grab timestampe. 1704synchronous (C<$sync> is true). Also remembers the grab timestampe.
1509=item $term->ungrab 1719=item $term->ungrab
1510 1720
1511Calls XUngrab for the most recent grab. Is called automatically on 1721Calls 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 1722evaluation errors, as it is better to lose the grab in the error case as
1513the session. 1723the session.
1724
1725=item $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
1726
1727=item $atom_name = $term->XGetAtomName ($atom)
1728
1729=item @atoms = $term->XListProperties ($window)
1730
1731=item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
1732
1733=item $term->XChangeWindowProperty ($window, $property, $type, $format, $octets)
1734
1735=item $term->XDeleteProperty ($window, $property)
1736
1737=item $window = $term->DefaultRootWindow
1738
1739=item $term->XReparentWindow ($window, $parent, [$x, $y])
1740
1741=item $term->XMapWindow ($window)
1742
1743=item $term->XUnmapWindow ($window)
1744
1745=item $term->XMoveResizeWindow ($window, $x, $y, $width, $height)
1746
1747=item ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x, $y)
1748
1749=item $term->XChangeInput ($window, $add_events[, $del_events])
1750
1751Various X or X-related functions. The C<$term> object only serves as
1752the source of the display, otherwise those functions map more-or-less
1753directory onto the X functions of the same name.
1514 1754
1515=back 1755=back
1516 1756
1517=cut 1757=cut
1518 1758
1582 my ($self, $text, $cb) = @_; 1822 my ($self, $text, $cb) = @_;
1583 1823
1584 $self->add_item ({ type => "button", text => $text, activate => $cb}); 1824 $self->add_item ({ type => "button", text => $text, activate => $cb});
1585} 1825}
1586 1826
1587=item $popup->add_toggle ($text, $cb, $initial_value) 1827=item $popup->add_toggle ($text, $initial_value, $cb)
1588 1828
1589Adds a toggle/checkbox item to the popup. Teh callback gets called 1829Adds a toggle/checkbox item to the popup. The callback gets called
1590whenever it gets toggled, with a boolean indicating its value as its first 1830whenever it gets toggled, with a boolean indicating its new value as its
1591argument. 1831first argument.
1592 1832
1593=cut 1833=cut
1594 1834
1595sub add_toggle { 1835sub add_toggle {
1596 my ($self, $text, $cb, $value) = @_; 1836 my ($self, $text, $value, $cb) = @_;
1597 1837
1598 my $item; $item = { 1838 my $item; $item = {
1599 type => "button", 1839 type => "button",
1600 text => " $text", 1840 text => " $text",
1601 value => $value, 1841 value => $value,
1638 delete $self->{term}{_destroy}{$self}; 1878 delete $self->{term}{_destroy}{$self};
1639 $self->{term}->ungrab; 1879 $self->{term}->ungrab;
1640} 1880}
1641 1881
1642=back 1882=back
1883
1884=cut
1885
1886package urxvt::watcher;
1887
1888@urxvt::timer::ISA = __PACKAGE__;
1889@urxvt::iow::ISA = __PACKAGE__;
1890@urxvt::pw::ISA = __PACKAGE__;
1891@urxvt::iw::ISA = __PACKAGE__;
1643 1892
1644=head2 The C<urxvt::timer> Class 1893=head2 The C<urxvt::timer> Class
1645 1894
1646This class implements timer watchers/events. Time is represented as a 1895This class implements timer watchers/events. Time is represented as a
1647fractional number of seconds since the epoch. Example: 1896fractional number of seconds since the epoch. Example:
1745 1994
1746Stop watching for events on the given filehandle. 1995Stop watching for events on the given filehandle.
1747 1996
1748=back 1997=back
1749 1998
1999=head2 The C<urxvt::iw> Class
2000
2001This class implements idle watchers, that get called automatically when
2002the process is idle. They should return as fast as possible, after doing
2003some useful work.
2004
2005=over 4
2006
2007=item $iw = new urxvt::iw
2008
2009Create a new idle watcher object in stopped state.
2010
2011=item $iw = $iw->cb (sub { my ($iw) = @_; ... })
2012
2013Set the callback to be called when the watcher triggers.
2014
2015=item $timer = $timer->start
2016
2017Start the watcher.
2018
2019=item $timer = $timer->stop
2020
2021Stop the watcher.
2022
2023=back
2024
2025=head2 The C<urxvt::pw> Class
2026
2027This class implements process watchers. They create an event whenever a
2028process exits, after which they stop automatically.
2029
2030 my $pid = fork;
2031 ...
2032 $term->{pw} = urxvt::pw
2033 ->new
2034 ->start ($pid)
2035 ->cb (sub {
2036 my ($pw, $exit_status) = @_;
2037 ...
2038 });
2039
2040=over 4
2041
2042=item $pw = new urxvt::pw
2043
2044Create a new process watcher in stopped state.
2045
2046=item $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
2047
2048Set the callback to be called when the timer triggers.
2049
2050=item $pw = $timer->start ($pid)
2051
2052Tells the wqtcher to start watching for process C<$pid>.
2053
2054=item $pw = $pw->stop
2055
2056Stop the watcher.
2057
2058=back
2059
1750=head1 ENVIRONMENT 2060=head1 ENVIRONMENT
1751 2061
1752=head2 URXVT_PERL_VERBOSITY 2062=head2 URXVT_PERL_VERBOSITY
1753 2063
1754This variable controls the verbosity level of the perl extension. Higher 2064This variable controls the verbosity level of the perl extension. Higher

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines