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.128 by root, Wed Jan 25 00:57:57 2006 UTC vs.
Revision 1.140 by root, Mon Jul 3 19:10:09 2006 UTC

94=item option-popup (enabled by default) 94=item option-popup (enabled by default)
95 95
96Binds 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
97runtime. 97runtime.
98 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
99=item selection-popup (enabled by default) 116=item selection-popup (enabled by default)
100 117
101Binds 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
102text into various other formats/action (such as uri unescaping, perl 119text into various other formats/action (such as uri unescaping, perl
103evaluation, web-browser starting etc.), depending on content. 120evaluation, web-browser starting etc.), depending on content.
104 121
105Other extensions can extend this popup menu by pushing a code reference 122Other extensions can extend this popup menu by pushing a code reference
106onto C<@{ $term->{selection_popup_hook} }>, that is called whenever the 123onto C<@{ $term->{selection_popup_hook} }>, which gets called whenever the
107popup is displayed. 124popup is being displayed.
108 125
109It'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
110is 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.
111It 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
112string 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
136additionally stores the first match in the current line into the primary 153additionally stores the first match in the current line into the primary
137selection. 154selection.
138 155
139=item readline (enabled by default) 156=item readline (enabled by default)
140 157
141A support package that tries to make editing with readline easier. At the 158A support package that tries to make editing with readline easier. At
142moment, it reacts to clicking with the left mouse button by trying to 159the moment, it reacts to clicking shift-left mouse button by trying to
143move the text cursor to this position. It does so by generating as many 160move the text cursor to this position. It does so by generating as many
144cursor-left or cursor-right keypresses as required (the this only works 161cursor-left or cursor-right keypresses as required (the this only works
145for programs that correctly support wide characters). 162for programs that correctly support wide characters).
146 163
147To avoid too many false positives, this is only done when: 164To avoid too many false positives, this is only done when:
205 222
206Clicking a button will activate that tab. Pressing B<Shift-Left> and 223Clicking a button will activate that tab. Pressing B<Shift-Left> and
207B<Shift-Right> will switch to the tab left or right of the current one, 224B<Shift-Right> will switch to the tab left or right of the current one,
208while B<Shift-Down> creates a new tab. 225while B<Shift-Down> creates a new tab.
209 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.
238
210=item mark-urls 239=item mark-urls
211 240
212Uses 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
213make them clickable. When middle-clicked, the program specified in the 242make them clickable. When middle-clicked, the program specified in the
214resource C<urlLauncher> (default C<x-www-browser>) will be started with 243resource C<urlLauncher> (default C<x-www-browser>) will be started with
226 255
227 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot 256 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot
228 257
229=item automove-background 258=item automove-background
230 259
231This is basically a one-line extension that dynamically changes the background pixmap offset 260This is basically a very small extension that dynamically changes the
232to the window position, in effect creating the same effect as pseudo transparency with 261background pixmap offset to the window position, in effect creating the
233a custom pixmap. No scaling is supported in this mode. Exmaple: 262same effect as pseudo transparency with a custom pixmap. No scaling is
263supported in this mode. Exmaple:
234 264
235 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background 265 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background
236 266
237=item block-graphics-to-ascii 267=item block-graphics-to-ascii
238 268
242 272
243=item digital-clock 273=item digital-clock
244 274
245Displays a digital clock using the built-in overlay. 275Displays a digital clock using the built-in overlay.
246 276
247=item example-refresh-hooks 277=item remote-clipboard
248 278
249Displays a very simple digital clock in the upper right corner of the 279Somewhat of a misnomer, this extension adds two menu entries to the
250window. Illustrates overwriting the refresh callbacks to create your own 280selection popup that allows one ti run external commands to store the
251overlays or changes. 281selection somewhere and fetch it again.
282
283We use it to implement a "distributed selection mechanism", which just
284means that one command uploads the file to a remote server, and another
285reads it.
286
287The commands can be set using the C<URxvt.remote-selection.store> and
288C<URxvt.remote-selection.fetch> resources. The first should read the
289selection to store from STDIN (always in UTF-8), the second should provide
290the selection data on STDOUT (also in UTF-8).
291
292The defaults (which are likely useless to you) use rsh and cat:
293
294 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
295 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
252 296
253=item selection-pastebin 297=item selection-pastebin
254 298
255This is a little rarely useful extension that Uploads the selection as 299This is a little rarely useful extension that Uploads the selection as
256textfile to a remote site (or does other things). (The implementation is 300textfile to a remote site (or does other things). (The implementation is
276After a successful upload the selection will be replaced by the text given 320After a successful upload the selection will be replaced by the text given
277in the C<selection-pastebin-url> resource (again, the % is the placeholder 321in the C<selection-pastebin-url> resource (again, the % is the placeholder
278for the filename): 322for the filename):
279 323
280 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/% 324 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
325
326=item example-refresh-hooks
327
328Displays a very simple digital clock in the upper right corner of the
329window. Illustrates overwriting the refresh callbacks to create your own
330overlays or changes.
281 331
282=back 332=back
283 333
284=head1 API DOCUMENTATION 334=head1 API DOCUMENTATION
285 335
319 369
320=back 370=back
321 371
322=head2 Extension Objects 372=head2 Extension Objects
323 373
324Very perl extension is a perl class. A separate perl object is created 374Every perl extension is a perl class. A separate perl object is created
325for each terminal and each extension and passed as the first parameter to 375for each terminal and each extension and passed as the first parameter to
326hooks. So extensions can use their C<$self> object without having to think 376hooks. So extensions can use their C<$self> object without having to think
327about other extensions, with the exception of methods and members that 377about other extensions, with the exception of methods and members that
328begin with an underscore character C<_>: these are reserved for internal 378begin with an underscore character C<_>: these are reserved for internal
329use. 379use.
444 494
445It is called before lines are scrolled out (so rows 0 .. min ($lines - 1, 495It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
446$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total 496$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
447number of lines that will be in the scrollback buffer. 497number of lines that will be in the scrollback buffer.
448 498
499=item on_osc_seq $term, $op, $args
500
501Called on every OSC sequence and can be used to suppress it or modify its
502behaviour. The default should be to return an empty list. A true value
503suppresses execution of the request completely. Make sure you don't get
504confused by recursive invocations when you output an osc sequence within
505this callback.
506
507C<on_osc_seq_perl> should be used for new behaviour.
508
449=item on_osc_seq $term, $string 509=item on_osc_seq_perl $term, $string
450 510
451Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 511Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
452operating system command) is processed. Cursor position and other state 512operating system command) is processed. Cursor position and other state
453information is up-to-date when this happens. For interoperability, the 513information is up-to-date when this happens. For interoperability, the
454string should start with the extension name and a colon, to distinguish 514string should start with the extension name and a colon, to distinguish
495 555
496=item on_refresh_end $term 556=item on_refresh_end $term
497 557
498Called just after the screen gets redrawn. See C<on_refresh_begin>. 558Called just after the screen gets redrawn. See C<on_refresh_begin>.
499 559
500=item on_keyboard_command $term, $string 560=item on_user_command $term, $string
501 561
502Called whenever the user presses a key combination that has a 562Called whenever the a user-configured event is being activated (e.g. via
503C<perl:string> action bound to it (see description of the B<keysym> 563a C<perl:string> action bound to a key, see description of the B<keysym>
504resource in the @@RXVT_NAME@@(1) manpage). 564resource in the @@RXVT_NAME@@(1) manpage).
565
566The event is simply the action string. This interface is assumed to change
567slightly in the future.
568
569=item on_resize_all_windows $tern, $new_width, $new_height
570
571Called just after the new window size has been calculcated, but before
572windows are actually being resized or hints are being set. If this hook
573returns TRUE, setting of the window hints is being skipped.
505 574
506=item on_x_event $term, $event 575=item on_x_event $term, $event
507 576
508Called on every X event received on the vt window (and possibly other 577Called on every X event received on the vt window (and possibly other
509windows). Should only be used as a last resort. Most event structure 578windows). Should only be used as a last resort. Most event structure
644Using this function has the advantage that its output ends up in the 713Using this function has the advantage that its output ends up in the
645correct place, e.g. on stderr of the connecting urxvtc client. 714correct place, e.g. on stderr of the connecting urxvtc client.
646 715
647Messages have a size limit of 1023 bytes currently. 716Messages have a size limit of 1023 bytes currently.
648 717
718=item @terms = urxvt::termlist
719
720Returns all urxvt::term objects that exist in this process, regardless of
721wether they are started, being destroyed etc., so be careful. Only term
722objects that have perl extensions attached will be returned (because there
723is no urxvt::term objet associated with others).
724
649=item $time = urxvt::NOW 725=item $time = urxvt::NOW
650 726
651Returns the "current time" (as per the event loop). 727Returns the "current time" (as per the event loop).
652 728
653=item urxvt::CurrentTime 729=item urxvt::CurrentTime
710Return the foreground/background colour index, respectively. 786Return the foreground/background colour index, respectively.
711 787
712=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour 788=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
713 789
714=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour 790=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
791
792=item $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
715 793
716Replace the foreground/background colour in the rendition mask with the 794Replace the foreground/background colour in the rendition mask with the
717specified one. 795specified one.
718 796
719=item $value = urxvt::GET_CUSTOM $rend 797=item $value = urxvt::GET_CUSTOM $rend
810 } else { 888 } else {
811 $ext_arg{$_} ||= []; 889 $ext_arg{$_} ||= [];
812 } 890 }
813 } 891 }
814 892
815 while (my ($ext, $argv) = each %ext_arg) { 893 for my $ext (sort keys %ext_arg) {
816 my @files = grep -f $_, map "$_/$ext", @dirs; 894 my @files = grep -f $_, map "$_/$ext", @dirs;
817 895
818 if (@files) { 896 if (@files) {
819 $TERM->register_package (extension_package $files[0], $argv); 897 $TERM->register_package (extension_package $files[0], $ext_arg{$ext});
820 } else { 898 } else {
821 warn "perl extension '$ext' not found in perl library search path\n"; 899 warn "perl extension '$ext' not found in perl library search path\n";
822 } 900 }
823 } 901 }
824 902
830 908
831 if (my $cb = $TERM->{_hook}[$htype]) { 909 if (my $cb = $TERM->{_hook}[$htype]) {
832 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")" 910 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
833 if $verbosity >= 10; 911 if $verbosity >= 10;
834 912
835 keys %$cb; 913 for my $pkg (keys %$cb) {
836
837 while (my ($pkg, $cb) = each %$cb) {
838 my $retval_ = eval { $cb->($TERM->{_pkg}{$pkg}, @_) }; 914 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg}, @_) };
839 $retval ||= $retval_; 915 $retval ||= $retval_;
840 916
841 if ($@) { 917 if ($@) {
842 $TERM->ungrab; # better to lose the grab than the session 918 $TERM->ungrab; # better to lose the grab than the session
843 warn $@; 919 warn $@;
855 # clear package 931 # clear package
856 %$TERM = (); 932 %$TERM = ();
857 } 933 }
858 934
859 $retval 935 $retval
936}
937
938sub SET_COLOR($$$) {
939 SET_BGCOLOR (SET_FGCOLOR ($_[0], $_[1]), $_[2])
860} 940}
861 941
862# urxvt::term::extension 942# urxvt::term::extension
863 943
864package urxvt::term::extension; 944package urxvt::term::extension;
1033hash which defines the environment of the new terminal. 1113hash which defines the environment of the new terminal.
1034 1114
1035Croaks (and probably outputs an error message) if the new instance 1115Croaks (and probably outputs an error message) if the new instance
1036couldn't be created. Returns C<undef> if the new instance didn't 1116couldn't be created. Returns C<undef> if the new instance didn't
1037initialise perl, and the terminal object otherwise. The C<init> and 1117initialise perl, and the terminal object otherwise. The C<init> and
1038C<start> hooks will be called during this call. 1118C<start> hooks will be called before this call returns, and are free to
1119refer to global data (which is race free).
1039 1120
1040=cut 1121=cut
1041 1122
1042sub new { 1123sub new {
1043 my ($class, $env, @args) = @_; 1124 my ($class, $env, @args) = @_;
1044 1125
1126 $env or Carp::croak "environment hash missing in call to urxvt::term->new";
1127 @args or Carp::croak "name argument missing in call to urxvt::term->new";
1128
1045 _new ([ map "$_=$env->{$_}", keys %$env ], @args); 1129 _new ([ map "$_=$env->{$_}", keys %$env ], \@args);
1046} 1130}
1047 1131
1048=item $term->destroy 1132=item $term->destroy
1049 1133
1050Destroy the terminal object (close the window, free resources 1134Destroy the terminal object (close the window, free resources
1350Adds the specified events to the vt event mask. Useful e.g. when you want 1434Adds the specified events to the vt event mask. Useful e.g. when you want
1351to receive pointer events all the times: 1435to receive pointer events all the times:
1352 1436
1353 $term->vt_emask_add (urxvt::PointerMotionMask); 1437 $term->vt_emask_add (urxvt::PointerMotionMask);
1354 1438
1439=item $term->focus_in
1440
1441=item $term->focus_out
1442
1443=item $term->key_press ($state, $keycode[, $time])
1444
1445=item $term->key_release ($state, $keycode[, $time])
1446
1447Deliver various fake events to to terminal.
1448
1355=item $window_width = $term->width 1449=item $window_width = $term->width
1356 1450
1357=item $window_height = $term->height 1451=item $window_height = $term->height
1358 1452
1359=item $font_width = $term->fwidth 1453=item $font_width = $term->fwidth
1389=item $env = $term->env 1483=item $env = $term->env
1390 1484
1391Returns a copy of the environment in effect for the terminal as a hashref 1485Returns a copy of the environment in effect for the terminal as a hashref
1392similar to C<\%ENV>. 1486similar to C<\%ENV>.
1393 1487
1488=item @envv = $term->envv
1489
1490Returns the environment as array of strings of the form C<VAR=VALUE>.
1491
1492=item @argv = $term->argv
1493
1494Return the argument vector as this terminal, similar to @ARGV, but
1495includes the program name as first element.
1496
1394=cut 1497=cut
1395 1498
1396sub env { 1499sub env {
1397 if (my $env = $_[0]->_env) {
1398 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env } 1500 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), $_[0]->envv }
1399 } else {
1400 +{ %ENV }
1401 }
1402} 1501}
1403 1502
1404=item $modifiermask = $term->ModLevel3Mask 1503=item $modifiermask = $term->ModLevel3Mask
1405 1504
1406=item $modifiermask = $term->ModMetaMask 1505=item $modifiermask = $term->ModMetaMask
1604=item $string = $term->special_decode $text 1703=item $string = $term->special_decode $text
1605 1704
1606Converts rxvt-unicodes text reprsentation into a perl string. See 1705Converts rxvt-unicodes text reprsentation into a perl string. See
1607C<< $term->ROW_t >> for details. 1706C<< $term->ROW_t >> for details.
1608 1707
1609=item $success = $term->grab_button ($button, $modifiermask) 1708=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1610 1709
1710=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1711
1611Registers a synchronous button grab. See the XGrabButton manpage. 1712Register/unregister a synchronous button grab. See the XGrabButton
1713manpage.
1612 1714
1613=item $success = $term->grab ($eventtime[, $sync]) 1715=item $success = $term->grab ($eventtime[, $sync])
1614 1716
1615Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1717Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1616synchronous (C<$sync> is true). Also remembers the grab timestampe. 1718synchronous (C<$sync> is true). Also remembers the grab timestampe.
1734 my ($self, $text, $cb) = @_; 1836 my ($self, $text, $cb) = @_;
1735 1837
1736 $self->add_item ({ type => "button", text => $text, activate => $cb}); 1838 $self->add_item ({ type => "button", text => $text, activate => $cb});
1737} 1839}
1738 1840
1739=item $popup->add_toggle ($text, $cb, $initial_value) 1841=item $popup->add_toggle ($text, $initial_value, $cb)
1740 1842
1741Adds a toggle/checkbox item to the popup. Teh callback gets called 1843Adds a toggle/checkbox item to the popup. The callback gets called
1742whenever it gets toggled, with a boolean indicating its value as its first 1844whenever it gets toggled, with a boolean indicating its new value as its
1743argument. 1845first argument.
1744 1846
1745=cut 1847=cut
1746 1848
1747sub add_toggle { 1849sub add_toggle {
1748 my ($self, $text, $cb, $value) = @_; 1850 my ($self, $text, $value, $cb) = @_;
1749 1851
1750 my $item; $item = { 1852 my $item; $item = {
1751 type => "button", 1853 type => "button",
1752 text => " $text", 1854 text => " $text",
1753 value => $value, 1855 value => $value,

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines