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.113 by root, Fri Jan 20 10:27:08 2006 UTC vs.
Revision 1.143 by root, Thu Jul 6 23:48:11 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
156The regex defaults to "(?i)", resulting in a case-insensitive search. To
157get a case-sensitive search you can delete this prefix using C<BackSpace>
158or simply use an uppercase character which removes the "(?i)" prefix.
159
160See L<perlre> for more info about perl regular expression syntax.
161
162=item readline (enabled by default)
163
164A support package that tries to make editing with readline easier. At
165the moment, it reacts to clicking shift-left mouse button by trying to
166move the text cursor to this position. It does so by generating as many
167cursor-left or cursor-right keypresses as required (the this only works
168for programs that correctly support wide characters).
169
170To avoid too many false positives, this is only done when:
171
172=over 4
173
174=item - the tty is in ICANON state.
175
176=item - the text cursor is visible.
177
178=item - the primary screen is currently being displayed.
179
180=item - the mouse is on the same (multi-row-) line as the text cursor.
181
182=back
183
184The normal selection mechanism isn't disabled, so quick successive clicks
185might interfere with selection creation in harmless ways.
186
132=item selection-autotransform 187=item selection-autotransform
133 188
134This selection allows you to do automatic transforms on a selection 189This selection allows you to do automatic transforms on a selection
135whenever a selection is made. 190whenever a selection is made.
136 191
161 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/ 216 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/
162 217
163The first line tells the selection code to treat the unchanging part of 218The first line tells the selection code to treat the unchanging part of
164every error message as a selection pattern, and the second line transforms 219every error message as a selection pattern, and the second line transforms
165the message into vi commands to load the file. 220the message into vi commands to load the file.
221
222=item tabbed
223
224This transforms the terminal into a tabbar with additional terminals, that
225is, it implements what is commonly refered to as "tabbed terminal". The topmost line
226displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one
227button per tab.
228
229Clicking a button will activate that tab. Pressing B<Shift-Left> and
230B<Shift-Right> will switch to the tab left or right of the current one,
231while B<Shift-Down> creates a new tab.
232
233The tabbar itself can be configured similarly to a normal terminal, but
234with a resource class of C<URxvt.tabbed>. In addition, it supports the
235following four resources (shown with defaults):
236
237 URxvt.tabbed.tabbar-fg: <colour-index, default 3>
238 URxvt.tabbed.tabbar-bg: <colour-index, default 0>
239 URxvt.tabbed.tab-fg: <colour-index, default 0>
240 URxvt.tabbed.tab-bg: <colour-index, default 1>
241
242See I<COLOR AND GRAPHICS> in the @@RXVT_NAME@@(1) manpage for valid
243indices.
166 244
167=item mark-urls 245=item mark-urls
168 246
169Uses per-line display filtering (C<on_line_update>) to underline urls and 247Uses per-line display filtering (C<on_line_update>) to underline urls and
170make them clickable. When middle-clicked, the program specified in the 248make them clickable. When middle-clicked, the program specified in the
171resource C<urlLauncher> (default C<x-www-browser>) will be started with 249resource C<urlLauncher> (default C<x-www-browser>) will be started with
172the URL as first argument. 250the URL as first argument.
173 251
252=item xim-onthespot
253
254This (experimental) perl extension implements OnTheSpot editing. It does
255not work perfectly, and some input methods don't seem to work well with
256OnTheSpot editing in general, but it seems to work at leats for SCIM and
257kinput2.
258
259You enable it by specifying this extension and a preedit style of
260C<OnTheSpot>, i.e.:
261
262 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot
263
264=item kuake<hotkey>
265
266A very primitive quake-console-like extension. It was inspired by a
267description of how the programs C<kuake> and C<yakuake> work: Whenever the
268user presses a global accelerator key (by default C<F10>), the terminal
269will show or hide itself. Another press of the accelerator key will hide
270or show it again.
271
272Initially, the window will not be shown when using this extension.
273
274This is useful if you need a single terminal thats not using any desktop
275space most of the time but is quickly available at the press of a key.
276
277The accelerator key is grabbed regardless of any modifers, so this
278extension will actually grab a physical key just for this function.
279
280If you want a quake-like animation, tell your window manager to do so
281(fvwm can do it).
282
174=item automove-background 283=item automove-background
175 284
176This is basically a one-line extension that dynamically changes the background pixmap offset 285This is basically a very small extension that dynamically changes the
177to the window position, in effect creating the same effect as pseudo transparency with 286background pixmap offset to the window position, in effect creating the
178a custom pixmap. No scaling is supported in this mode. Exmaple: 287same effect as pseudo transparency with a custom pixmap. No scaling is
288supported in this mode. Exmaple:
179 289
180 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background 290 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background
181 291
182=item block-graphics-to-ascii 292=item block-graphics-to-ascii
183 293
184A not very useful example of filtering all text output to the terminal, 294A not very useful example of filtering all text output to the terminal
185by replacing all line-drawing characters (U+2500 .. U+259F) by a 295by replacing all line-drawing characters (U+2500 .. U+259F) by a
186similar-looking ascii character. 296similar-looking ascii character.
187 297
188=item digital-clock 298=item digital-clock
189 299
190Displays a digital clock using the built-in overlay. 300Displays a digital clock using the built-in overlay.
191 301
192=item example-refresh-hooks 302=item remote-clipboard
193 303
194Displays a very simple digital clock in the upper right corner of the 304Somewhat of a misnomer, this extension adds two menu entries to the
195window. Illustrates overwriting the refresh callbacks to create your own 305selection popup that allows one ti run external commands to store the
196overlays or changes. 306selection somewhere and fetch it again.
307
308We use it to implement a "distributed selection mechanism", which just
309means that one command uploads the file to a remote server, and another
310reads it.
311
312The commands can be set using the C<URxvt.remote-selection.store> and
313C<URxvt.remote-selection.fetch> resources. The first should read the
314selection to store from STDIN (always in UTF-8), the second should provide
315the selection data on STDOUT (also in UTF-8).
316
317The defaults (which are likely useless to you) use rsh and cat:
318
319 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
320 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
197 321
198=item selection-pastebin 322=item selection-pastebin
199 323
200This is a little rarely useful extension that Uploads the selection as 324This is a little rarely useful extension that Uploads the selection as
201textfile to a remote site (or does other things). (The implementation is 325textfile to a remote site (or does other things). (The implementation is
221After a successful upload the selection will be replaced by the text given 345After a successful upload the selection will be replaced by the text given
222in the C<selection-pastebin-url> resource (again, the % is the placeholder 346in the C<selection-pastebin-url> resource (again, the % is the placeholder
223for the filename): 347for the filename):
224 348
225 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/% 349 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
350
351=item example-refresh-hooks
352
353Displays a very simple digital clock in the upper right corner of the
354window. Illustrates overwriting the refresh callbacks to create your own
355overlays or changes.
226 356
227=back 357=back
228 358
229=head1 API DOCUMENTATION 359=head1 API DOCUMENTATION
230 360
264 394
265=back 395=back
266 396
267=head2 Extension Objects 397=head2 Extension Objects
268 398
269Very perl extension is a perl class. A separate perl object is created 399Every perl extension is a perl class. A separate perl object is created
270for each terminal and each extension and passed as the first parameter to 400for each terminal and each extension and passed as the first parameter to
271hooks. So extensions can use their C<$self> object without having to think 401hooks. So extensions can use their C<$self> object without having to think
272about other extensions, with the exception of methods and members that 402about other extensions, with the exception of methods and members that
273begin with an underscore character C<_>: these are reserved for internal 403begin with an underscore character C<_>: these are reserved for internal
274use. 404use.
327Called at the very end of initialisation of a new terminal, just before 457Called at the very end of initialisation of a new terminal, just before
328trying to map (display) the toplevel and returning to the mainloop. 458trying to map (display) the toplevel and returning to the mainloop.
329 459
330=item on_destroy $term 460=item on_destroy $term
331 461
332Called whenever something tries to destroy terminal, before doing anything 462Called whenever something tries to destroy terminal, when the terminal is
333yet. If this hook returns true, then destruction is skipped, but this is 463still fully functional (not for long, though).
334rarely a good idea.
335 464
336=item on_reset $term 465=item on_reset $term
337 466
338Called after the screen is "reset" for any reason, such as resizing or 467Called after the screen is "reset" for any reason, such as resizing or
339control sequences. Here is where you can react on changes to size-related 468control sequences. Here is where you can react on changes to size-related
390 519
391It is called before lines are scrolled out (so rows 0 .. min ($lines - 1, 520It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
392$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total 521$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
393number of lines that will be in the scrollback buffer. 522number of lines that will be in the scrollback buffer.
394 523
524=item on_osc_seq $term, $op, $args
525
526Called on every OSC sequence and can be used to suppress it or modify its
527behaviour. The default should be to return an empty list. A true value
528suppresses execution of the request completely. Make sure you don't get
529confused by recursive invocations when you output an osc sequence within
530this callback.
531
532C<on_osc_seq_perl> should be used for new behaviour.
533
395=item on_osc_seq $term, $string 534=item on_osc_seq_perl $term, $string
396 535
397Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 536Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
398operating system command) is processed. Cursor position and other state 537operating system command) is processed. Cursor position and other state
399information is up-to-date when this happens. For interoperability, the 538information is up-to-date when this happens. For interoperability, the
400string should start with the extension name and a colon, to distinguish 539string should start with the extension name and a colon, to distinguish
441 580
442=item on_refresh_end $term 581=item on_refresh_end $term
443 582
444Called just after the screen gets redrawn. See C<on_refresh_begin>. 583Called just after the screen gets redrawn. See C<on_refresh_begin>.
445 584
446=item on_keyboard_command $term, $string 585=item on_user_command $term, $string
447 586
448Called whenever the user presses a key combination that has a 587Called whenever the a user-configured event is being activated (e.g. via
449C<perl:string> action bound to it (see description of the B<keysym> 588a C<perl:string> action bound to a key, see description of the B<keysym>
450resource in the @@RXVT_NAME@@(1) manpage). 589resource in the @@RXVT_NAME@@(1) manpage).
590
591The event is simply the action string. This interface is assumed to change
592slightly in the future.
593
594=item on_resize_all_windows $tern, $new_width, $new_height
595
596Called just after the new window size has been calculcated, but before
597windows are actually being resized or hints are being set. If this hook
598returns TRUE, setting of the window hints is being skipped.
451 599
452=item on_x_event $term, $event 600=item on_x_event $term, $event
453 601
454Called on every X event received on the vt window (and possibly other 602Called on every X event received on the vt window (and possibly other
455windows). Should only be used as a last resort. Most event structure 603windows). Should only be used as a last resort. Most event structure
456members are not passed. 604members are not passed.
457 605
606=item on_root_event $term, $event
607
608Like C<on_x_event>, but is called for events on the root window.
609
458=item on_focus_in $term 610=item on_focus_in $term
459 611
460Called whenever the window gets the keyboard focus, before rxvt-unicode 612Called whenever the window gets the keyboard focus, before rxvt-unicode
461does focus in processing. 613does focus in processing.
462 614
465Called wheneever the window loses keyboard focus, before rxvt-unicode does 617Called wheneever the window loses keyboard focus, before rxvt-unicode does
466focus out processing. 618focus out processing.
467 619
468=item on_configure_notify $term, $event 620=item on_configure_notify $term, $event
469 621
622=item on_property_notify $term, $event
623
470=item on_key_press $term, $event, $keysym, $octets 624=item on_key_press $term, $event, $keysym, $octets
471 625
472=item on_key_release $term, $event, $keysym 626=item on_key_release $term, $event, $keysym
473 627
474=item on_button_press $term, $event 628=item on_button_press $term, $event
483 637
484Called whenever the corresponding X event is received for the terminal If 638Called whenever the corresponding X event is received for the terminal If
485the hook returns true, then the even will be ignored by rxvt-unicode. 639the hook returns true, then the even will be ignored by rxvt-unicode.
486 640
487The event is a hash with most values as named by Xlib (see the XEvent 641The event is a hash with most values as named by Xlib (see the XEvent
488manpage), with the additional members C<row> and C<col>, which are the row 642manpage), with the additional members C<row> and C<col>, which are the
489and column under the mouse cursor. 643(real, not screen-based) row and column under the mouse cursor.
490 644
491C<on_key_press> additionally receives the string rxvt-unicode would 645C<on_key_press> additionally receives the string rxvt-unicode would
492output, if any, in locale-specific encoding. 646output, if any, in locale-specific encoding.
493 647
494subwindow. 648subwindow.
649
650=item on_client_message $term, $event
651
652=item on_wm_protocols $term, $event
653
654=item on_wm_delete_window $term, $event
655
656Called when various types of ClientMessage events are received (all with
657format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
495 658
496=back 659=back
497 660
498=cut 661=cut
499 662
516our $LIBDIR; 679our $LIBDIR;
517our $RESNAME; 680our $RESNAME;
518our $RESCLASS; 681our $RESCLASS;
519our $RXVTNAME; 682our $RXVTNAME;
520 683
684our $NOCHAR = chr 0xffff;
685
521=head2 Variables in the C<urxvt> Package 686=head2 Variables in the C<urxvt> Package
522 687
523=over 4 688=over 4
524 689
525=item $urxvt::LIBDIR 690=item $urxvt::LIBDIR
576 741
577Using this function has the advantage that its output ends up in the 742Using this function has the advantage that its output ends up in the
578correct place, e.g. on stderr of the connecting urxvtc client. 743correct place, e.g. on stderr of the connecting urxvtc client.
579 744
580Messages have a size limit of 1023 bytes currently. 745Messages have a size limit of 1023 bytes currently.
746
747=item @terms = urxvt::termlist
748
749Returns all urxvt::term objects that exist in this process, regardless of
750wether they are started, being destroyed etc., so be careful. Only term
751objects that have perl extensions attached will be returned (because there
752is no urxvt::term objet associated with others).
581 753
582=item $time = urxvt::NOW 754=item $time = urxvt::NOW
583 755
584Returns the "current time" (as per the event loop). 756Returns the "current time" (as per the event loop).
585 757
643Return the foreground/background colour index, respectively. 815Return the foreground/background colour index, respectively.
644 816
645=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour 817=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
646 818
647=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour 819=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
820
821=item $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
648 822
649Replace the foreground/background colour in the rendition mask with the 823Replace the foreground/background colour in the rendition mask with the
650specified one. 824specified one.
651 825
652=item $value = urxvt::GET_CUSTOM $rend 826=item $value = urxvt::GET_CUSTOM $rend
671 unless $msg =~ /\n$/; 845 unless $msg =~ /\n$/;
672 urxvt::warn ($msg); 846 urxvt::warn ($msg);
673 }; 847 };
674} 848}
675 849
850no warnings 'utf8';
851
676my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 852my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
677 853
678sub verbose { 854sub verbose {
679 my ($level, $msg) = @_; 855 my ($level, $msg) = @_;
680 warn "$msg\n" if $level <= $verbosity; 856 warn "$msg\n" if $level <= $verbosity;
696 872
697 open my $fh, "<:raw", $path 873 open my $fh, "<:raw", $path
698 or die "$path: $!"; 874 or die "$path: $!";
699 875
700 my $source = 876 my $source =
701 "package $pkg; use strict; use utf8;\n" 877 "package $pkg; use strict; use utf8; no warnings 'utf8';\n"
702 . "#line 1 \"$path\"\n{\n" 878 . "#line 1 \"$path\"\n{\n"
703 . (do { local $/; <$fh> }) 879 . (do { local $/; <$fh> })
704 . "\n};\n1"; 880 . "\n};\n1";
705 881
706 eval $source 882 eval $source
731 $TERM->register_package ($_) for @pkg; 907 $TERM->register_package ($_) for @pkg;
732 } 908 }
733 909
734 for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) { 910 for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
735 if ($_ eq "default") { 911 if ($_ eq "default") {
736 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback); 912 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback readline);
737 } elsif (/^-(.*)$/) { 913 } elsif (/^-(.*)$/) {
738 delete $ext_arg{$1}; 914 delete $ext_arg{$1};
739 } elsif (/^([^<]+)<(.*)>$/) { 915 } elsif (/^([^<]+)<(.*)>$/) {
740 push @{ $ext_arg{$1} }, $2; 916 push @{ $ext_arg{$1} }, $2;
741 } else { 917 } else {
742 $ext_arg{$_} ||= []; 918 $ext_arg{$_} ||= [];
743 } 919 }
744 } 920 }
745 921
746 while (my ($ext, $argv) = each %ext_arg) { 922 for my $ext (sort keys %ext_arg) {
747 my @files = grep -f $_, map "$_/$ext", @dirs; 923 my @files = grep -f $_, map "$_/$ext", @dirs;
748 924
749 if (@files) { 925 if (@files) {
750 $TERM->register_package (extension_package $files[0], $argv); 926 $TERM->register_package (extension_package $files[0], $ext_arg{$ext});
751 } else { 927 } else {
752 warn "perl extension '$ext' not found in perl library search path\n"; 928 warn "perl extension '$ext' not found in perl library search path\n";
753 } 929 }
754 } 930 }
755 931
761 937
762 if (my $cb = $TERM->{_hook}[$htype]) { 938 if (my $cb = $TERM->{_hook}[$htype]) {
763 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")" 939 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
764 if $verbosity >= 10; 940 if $verbosity >= 10;
765 941
766 keys %$cb; 942 for my $pkg (keys %$cb) {
767
768 while (my ($pkg, $cb) = each %$cb) {
769 my $retval_ = eval { $cb->($TERM->{_pkg}{$pkg}, @_) }; 943 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg}, @_) };
770 $retval ||= $retval_; 944 $retval ||= $retval_;
771 945
772 if ($@) { 946 if ($@) {
773 $TERM->ungrab; # better to lose the grab than the session 947 $TERM->ungrab; # better to lose the grab than the session
774 warn $@; 948 warn $@;
786 # clear package 960 # clear package
787 %$TERM = (); 961 %$TERM = ();
788 } 962 }
789 963
790 $retval 964 $retval
965}
966
967sub SET_COLOR($$$) {
968 SET_BGCOLOR (SET_FGCOLOR ($_[0], $_[1]), $_[2])
791} 969}
792 970
793# urxvt::term::extension 971# urxvt::term::extension
794 972
795package urxvt::term::extension; 973package urxvt::term::extension;
964hash which defines the environment of the new terminal. 1142hash which defines the environment of the new terminal.
965 1143
966Croaks (and probably outputs an error message) if the new instance 1144Croaks (and probably outputs an error message) if the new instance
967couldn't be created. Returns C<undef> if the new instance didn't 1145couldn't be created. Returns C<undef> if the new instance didn't
968initialise perl, and the terminal object otherwise. The C<init> and 1146initialise perl, and the terminal object otherwise. The C<init> and
969C<start> hooks will be called during this call. 1147C<start> hooks will be called before this call returns, and are free to
1148refer to global data (which is race free).
970 1149
971=cut 1150=cut
972 1151
973sub new { 1152sub new {
974 my ($class, $env, @args) = @_; 1153 my ($class, $env, @args) = @_;
975 1154
1155 $env or Carp::croak "environment hash missing in call to urxvt::term->new";
1156 @args or Carp::croak "name argument missing in call to urxvt::term->new";
1157
976 _new ([ map "$_=$env->{$_}", keys %$env ], @args); 1158 _new ([ map "$_=$env->{$_}", keys %$env ], \@args);
977} 1159}
978 1160
979=item $term->destroy 1161=item $term->destroy
980 1162
981Destroy the terminal object (close the window, free resources 1163Destroy the terminal object (close the window, free resources
1238 1420
1239Normally its not a good idea to use this function, as programs might be 1421Normally its not a good idea to use this function, as programs might be
1240confused by changes in cursor position or scrolling. Its useful inside a 1422confused by changes in cursor position or scrolling. Its useful inside a
1241C<on_add_lines> hook, though. 1423C<on_add_lines> hook, though.
1242 1424
1425=item $term->scr_change_screen ($screen)
1426
1427Switch to given screen - 0 primary, 1 secondary.
1428
1243=item $term->cmd_parse ($octets) 1429=item $term->cmd_parse ($octets)
1244 1430
1245Similar to C<scr_add_lines>, but the argument must be in the 1431Similar to C<scr_add_lines>, but the argument must be in the
1246locale-specific encoding of the terminal and can contain command sequences 1432locale-specific encoding of the terminal and can contain command sequences
1247(escape codes) that will be interpreted. 1433(escape codes) that will be interpreted.
1257Replaces the event mask of the pty watcher by the given event mask. Can 1443Replaces the event mask of the pty watcher by the given event mask. Can
1258be used to suppress input and output handling to the pty/tty. See the 1444be used to suppress input and output handling to the pty/tty. See the
1259description of C<< urxvt::timer->events >>. Make sure to always restore 1445description of C<< urxvt::timer->events >>. Make sure to always restore
1260the previous value. 1446the previous value.
1261 1447
1448=item $fd = $term->pty_fd
1449
1450Returns the master file descriptor for the pty in use, or C<-1> if no pty
1451is used.
1452
1262=item $windowid = $term->parent 1453=item $windowid = $term->parent
1263 1454
1264Return the window id of the toplevel window. 1455Return the window id of the toplevel window.
1265 1456
1266=item $windowid = $term->vt 1457=item $windowid = $term->vt
1272Adds the specified events to the vt event mask. Useful e.g. when you want 1463Adds the specified events to the vt event mask. Useful e.g. when you want
1273to receive pointer events all the times: 1464to receive pointer events all the times:
1274 1465
1275 $term->vt_emask_add (urxvt::PointerMotionMask); 1466 $term->vt_emask_add (urxvt::PointerMotionMask);
1276 1467
1468=item $term->focus_in
1469
1470=item $term->focus_out
1471
1472=item $term->key_press ($state, $keycode[, $time])
1473
1474=item $term->key_release ($state, $keycode[, $time])
1475
1476Deliver various fake events to to terminal.
1477
1277=item $window_width = $term->width 1478=item $window_width = $term->width
1278 1479
1279=item $window_height = $term->height 1480=item $window_height = $term->height
1280 1481
1281=item $font_width = $term->fwidth 1482=item $font_width = $term->fwidth
1311=item $env = $term->env 1512=item $env = $term->env
1312 1513
1313Returns a copy of the environment in effect for the terminal as a hashref 1514Returns a copy of the environment in effect for the terminal as a hashref
1314similar to C<\%ENV>. 1515similar to C<\%ENV>.
1315 1516
1517=item @envv = $term->envv
1518
1519Returns the environment as array of strings of the form C<VAR=VALUE>.
1520
1521=item @argv = $term->argv
1522
1523Return the argument vector as this terminal, similar to @ARGV, but
1524includes the program name as first element.
1525
1316=cut 1526=cut
1317 1527
1318sub env { 1528sub env {
1319 if (my $env = $_[0]->_env) {
1320 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env } 1529 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), $_[0]->envv }
1321 } else {
1322 +{ %ENV }
1323 }
1324} 1530}
1325 1531
1326=item $modifiermask = $term->ModLevel3Mask 1532=item $modifiermask = $term->ModLevel3Mask
1327 1533
1328=item $modifiermask = $term->ModMetaMask 1534=item $modifiermask = $term->ModMetaMask
1329 1535
1330=item $modifiermask = $term->ModNumLockMask 1536=item $modifiermask = $term->ModNumLockMask
1331 1537
1332Return the modifier masks corresponding to the "ISO Level 3 Shift" (often 1538Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
1333AltGr), the meta key (often Alt) and the num lock key, if applicable. 1539AltGr), the meta key (often Alt) and the num lock key, if applicable.
1540
1541=item $screen = $term->current_screen
1542
1543Returns the currently displayed screen (0 primary, 1 secondary).
1544
1545=item $cursor_is_hidden = $term->hidden_cursor
1546
1547Returns wether the cursor is currently hidden or not.
1334 1548
1335=item $view_start = $term->view_start ([$newvalue]) 1549=item $view_start = $term->view_start ([$newvalue])
1336 1550
1337Returns the row number of the topmost displayed line. Maximum value is 1551Returns the row number of the topmost displayed line. Maximum value is
1338C<0>, which displays the normal terminal contents. Lower values scroll 1552C<0>, which displays the normal terminal contents. Lower values scroll
1358line, starting at column C<$start_col> (default C<0>), which is useful 1572line, starting at column C<$start_col> (default C<0>), which is useful
1359to replace only parts of a line. The font index in the rendition will 1573to replace only parts of a line. The font index in the rendition will
1360automatically be updated. 1574automatically be updated.
1361 1575
1362C<$text> is in a special encoding: tabs and wide characters that use more 1576C<$text> is in a special encoding: tabs and wide characters that use more
1363than one cell when displayed are padded with urxvt::NOCHAR characters 1577than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535)
1364(C<chr 65535>). Characters with combining characters and other characters 1578characters. Characters with combining characters and other characters that
1365that do not fit into the normal tetx encoding will be replaced with 1579do not fit into the normal tetx encoding will be replaced with characters
1366characters in the private use area. 1580in the private use area.
1367 1581
1368You have to obey this encoding when changing text. The advantage is 1582You have to obey this encoding when changing text. The advantage is
1369that C<substr> and similar functions work on screen cells and not on 1583that C<substr> and similar functions work on screen cells and not on
1370characters. 1584characters.
1371 1585
1518=item $string = $term->special_decode $text 1732=item $string = $term->special_decode $text
1519 1733
1520Converts rxvt-unicodes text reprsentation into a perl string. See 1734Converts rxvt-unicodes text reprsentation into a perl string. See
1521C<< $term->ROW_t >> for details. 1735C<< $term->ROW_t >> for details.
1522 1736
1523=item $success = $term->grab_button ($button, $modifiermask) 1737=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1524 1738
1739=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1740
1525Registers a synchronous button grab. See the XGrabButton manpage. 1741Register/unregister a synchronous button grab. See the XGrabButton
1742manpage.
1526 1743
1527=item $success = $term->grab ($eventtime[, $sync]) 1744=item $success = $term->grab ($eventtime[, $sync])
1528 1745
1529Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1746Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1530synchronous (C<$sync> is true). Also remembers the grab timestampe. 1747synchronous (C<$sync> is true). Also remembers the grab timestampe.
1545=item $term->ungrab 1762=item $term->ungrab
1546 1763
1547Calls XUngrab for the most recent grab. Is called automatically on 1764Calls XUngrab for the most recent grab. Is called automatically on
1548evaluation errors, as it is better to lose the grab in the error case as 1765evaluation errors, as it is better to lose the grab in the error case as
1549the session. 1766the session.
1767
1768=item $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
1769
1770=item $atom_name = $term->XGetAtomName ($atom)
1771
1772=item @atoms = $term->XListProperties ($window)
1773
1774=item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
1775
1776=item $term->XChangeWindowProperty ($window, $property, $type, $format, $octets)
1777
1778=item $term->XDeleteProperty ($window, $property)
1779
1780=item $window = $term->DefaultRootWindow
1781
1782=item $term->XReparentWindow ($window, $parent, [$x, $y])
1783
1784=item $term->XMapWindow ($window)
1785
1786=item $term->XUnmapWindow ($window)
1787
1788=item $term->XMoveResizeWindow ($window, $x, $y, $width, $height)
1789
1790=item ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x, $y)
1791
1792=item $term->XChangeInput ($window, $add_events[, $del_events])
1793
1794Various X or X-related functions. The C<$term> object only serves as
1795the source of the display, otherwise those functions map more-or-less
1796directory onto the X functions of the same name.
1550 1797
1551=back 1798=back
1552 1799
1553=cut 1800=cut
1554 1801
1618 my ($self, $text, $cb) = @_; 1865 my ($self, $text, $cb) = @_;
1619 1866
1620 $self->add_item ({ type => "button", text => $text, activate => $cb}); 1867 $self->add_item ({ type => "button", text => $text, activate => $cb});
1621} 1868}
1622 1869
1623=item $popup->add_toggle ($text, $cb, $initial_value) 1870=item $popup->add_toggle ($text, $initial_value, $cb)
1624 1871
1625Adds a toggle/checkbox item to the popup. Teh callback gets called 1872Adds a toggle/checkbox item to the popup. The callback gets called
1626whenever it gets toggled, with a boolean indicating its value as its first 1873whenever it gets toggled, with a boolean indicating its new value as its
1627argument. 1874first argument.
1628 1875
1629=cut 1876=cut
1630 1877
1631sub add_toggle { 1878sub add_toggle {
1632 my ($self, $text, $cb, $value) = @_; 1879 my ($self, $text, $value, $cb) = @_;
1633 1880
1634 my $item; $item = { 1881 my $item; $item = {
1635 type => "button", 1882 type => "button",
1636 text => " $text", 1883 text => " $text",
1637 value => $value, 1884 value => $value,
1790 2037
1791Stop watching for events on the given filehandle. 2038Stop watching for events on the given filehandle.
1792 2039
1793=back 2040=back
1794 2041
2042=head2 The C<urxvt::iw> Class
2043
2044This class implements idle watchers, that get called automatically when
2045the process is idle. They should return as fast as possible, after doing
2046some useful work.
2047
2048=over 4
2049
2050=item $iw = new urxvt::iw
2051
2052Create a new idle watcher object in stopped state.
2053
2054=item $iw = $iw->cb (sub { my ($iw) = @_; ... })
2055
2056Set the callback to be called when the watcher triggers.
2057
2058=item $timer = $timer->start
2059
2060Start the watcher.
2061
2062=item $timer = $timer->stop
2063
2064Stop the watcher.
2065
2066=back
2067
2068=head2 The C<urxvt::pw> Class
2069
2070This class implements process watchers. They create an event whenever a
2071process exits, after which they stop automatically.
2072
2073 my $pid = fork;
2074 ...
2075 $term->{pw} = urxvt::pw
2076 ->new
2077 ->start ($pid)
2078 ->cb (sub {
2079 my ($pw, $exit_status) = @_;
2080 ...
2081 });
2082
2083=over 4
2084
2085=item $pw = new urxvt::pw
2086
2087Create a new process watcher in stopped state.
2088
2089=item $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
2090
2091Set the callback to be called when the timer triggers.
2092
2093=item $pw = $timer->start ($pid)
2094
2095Tells the wqtcher to start watching for process C<$pid>.
2096
2097=item $pw = $pw->stop
2098
2099Stop the watcher.
2100
2101=back
2102
1795=head1 ENVIRONMENT 2103=head1 ENVIRONMENT
1796 2104
1797=head2 URXVT_PERL_VERBOSITY 2105=head2 URXVT_PERL_VERBOSITY
1798 2106
1799This variable controls the verbosity level of the perl extension. Higher 2107This variable controls the verbosity level of the perl extension. Higher

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines