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.133 by root, Mon Feb 6 06:14:08 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
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
242 271
243=item digital-clock 272=item digital-clock
244 273
245Displays a digital clock using the built-in overlay. 274Displays a digital clock using the built-in overlay.
246 275
247=item example-refresh-hooks 276=item remote-clipboard
248 277
249Displays a very simple digital clock in the upper right corner of the 278Somewhat of a misnomer, this extension adds two menu entries to the
250window. Illustrates overwriting the refresh callbacks to create your own 279selection popup that allows one ti run external commands to store the
251overlays 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'
252 295
253=item selection-pastebin 296=item selection-pastebin
254 297
255This is a little rarely useful extension that Uploads the selection as 298This is a little rarely useful extension that Uploads the selection as
256textfile to a remote site (or does other things). (The implementation is 299textfile to a remote site (or does other things). (The implementation is
276After 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
277in the C<selection-pastebin-url> resource (again, the % is the placeholder 320in the C<selection-pastebin-url> resource (again, the % is the placeholder
278for the filename): 321for the filename):
279 322
280 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.
281 330
282=back 331=back
283 332
284=head1 API DOCUMENTATION 333=head1 API DOCUMENTATION
285 334
495 544
496=item on_refresh_end $term 545=item on_refresh_end $term
497 546
498Called just after the screen gets redrawn. See C<on_refresh_begin>. 547Called just after the screen gets redrawn. See C<on_refresh_begin>.
499 548
500=item on_keyboard_command $term, $string 549=item on_user_command $term, $string
501 550
502Called whenever the user presses a key combination that has a 551Called 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> 552a C<perl:string> action bound to a key, see description of the B<keysym>
504resource 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.
505 557
506=item on_x_event $term, $event 558=item on_x_event $term, $event
507 559
508Called on every X event received on the vt window (and possibly other 560Called on every X event received on the vt window (and possibly other
509windows). Should only be used as a last resort. Most event structure 561windows). Should only be used as a last resort. Most event structure
644Using this function has the advantage that its output ends up in the 696Using this function has the advantage that its output ends up in the
645correct place, e.g. on stderr of the connecting urxvtc client. 697correct place, e.g. on stderr of the connecting urxvtc client.
646 698
647Messages have a size limit of 1023 bytes currently. 699Messages have a size limit of 1023 bytes currently.
648 700
701=item @terms = urxvt::termlist
702
703Returns all urxvt::term objects that exist in this process, regardless of
704wether they are started, being destroyed etc., so be careful. Only term
705objects that have perl extensions attached will be returned (because there
706is no urxvt::term objet associated with others).
707
649=item $time = urxvt::NOW 708=item $time = urxvt::NOW
650 709
651Returns the "current time" (as per the event loop). 710Returns the "current time" (as per the event loop).
652 711
653=item urxvt::CurrentTime 712=item urxvt::CurrentTime
710Return the foreground/background colour index, respectively. 769Return the foreground/background colour index, respectively.
711 770
712=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour 771=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
713 772
714=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour 773=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
774
775=item $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
715 776
716Replace the foreground/background colour in the rendition mask with the 777Replace the foreground/background colour in the rendition mask with the
717specified one. 778specified one.
718 779
719=item $value = urxvt::GET_CUSTOM $rend 780=item $value = urxvt::GET_CUSTOM $rend
810 } else { 871 } else {
811 $ext_arg{$_} ||= []; 872 $ext_arg{$_} ||= [];
812 } 873 }
813 } 874 }
814 875
815 while (my ($ext, $argv) = each %ext_arg) { 876 for my $ext (sort keys %ext_arg) {
816 my @files = grep -f $_, map "$_/$ext", @dirs; 877 my @files = grep -f $_, map "$_/$ext", @dirs;
817 878
818 if (@files) { 879 if (@files) {
819 $TERM->register_package (extension_package $files[0], $argv); 880 $TERM->register_package (extension_package $files[0], $ext_arg{$ext});
820 } else { 881 } else {
821 warn "perl extension '$ext' not found in perl library search path\n"; 882 warn "perl extension '$ext' not found in perl library search path\n";
822 } 883 }
823 } 884 }
824 885
855 # clear package 916 # clear package
856 %$TERM = (); 917 %$TERM = ();
857 } 918 }
858 919
859 $retval 920 $retval
921}
922
923sub SET_COLOR($$$) {
924 SET_BGCOLOR (SET_FGCOLOR ($_[0], $_[1]), $_[2])
860} 925}
861 926
862# urxvt::term::extension 927# urxvt::term::extension
863 928
864package urxvt::term::extension; 929package urxvt::term::extension;
1033hash which defines the environment of the new terminal. 1098hash which defines the environment of the new terminal.
1034 1099
1035Croaks (and probably outputs an error message) if the new instance 1100Croaks (and probably outputs an error message) if the new instance
1036couldn't be created. Returns C<undef> if the new instance didn't 1101couldn't be created. Returns C<undef> if the new instance didn't
1037initialise perl, and the terminal object otherwise. The C<init> and 1102initialise perl, and the terminal object otherwise. The C<init> and
1038C<start> hooks will be called during this call. 1103C<start> hooks will be called before this call returns, and are free to
1104refer to global data (which is race free).
1039 1105
1040=cut 1106=cut
1041 1107
1042sub new { 1108sub new {
1043 my ($class, $env, @args) = @_; 1109 my ($class, $env, @args) = @_;
1044 1110
1111 $env or Carp::croak "environment hash missing in call to urxvt::term->new";
1112 @args or Carp::croak "name argument missing in call to urxvt::term->new";
1113
1045 _new ([ map "$_=$env->{$_}", keys %$env ], @args); 1114 _new ([ map "$_=$env->{$_}", keys %$env ], \@args);
1046} 1115}
1047 1116
1048=item $term->destroy 1117=item $term->destroy
1049 1118
1050Destroy the terminal object (close the window, free resources 1119Destroy the terminal object (close the window, free resources
1350Adds the specified events to the vt event mask. Useful e.g. when you want 1419Adds the specified events to the vt event mask. Useful e.g. when you want
1351to receive pointer events all the times: 1420to receive pointer events all the times:
1352 1421
1353 $term->vt_emask_add (urxvt::PointerMotionMask); 1422 $term->vt_emask_add (urxvt::PointerMotionMask);
1354 1423
1424=item $term->focus_in
1425
1426=item $term->focus_out
1427
1428=item $term->key_press ($state, $keycode[, $time])
1429
1430=item $term->key_release ($state, $keycode[, $time])
1431
1432Deliver various fake events to to terminal.
1433
1355=item $window_width = $term->width 1434=item $window_width = $term->width
1356 1435
1357=item $window_height = $term->height 1436=item $window_height = $term->height
1358 1437
1359=item $font_width = $term->fwidth 1438=item $font_width = $term->fwidth
1604=item $string = $term->special_decode $text 1683=item $string = $term->special_decode $text
1605 1684
1606Converts rxvt-unicodes text reprsentation into a perl string. See 1685Converts rxvt-unicodes text reprsentation into a perl string. See
1607C<< $term->ROW_t >> for details. 1686C<< $term->ROW_t >> for details.
1608 1687
1609=item $success = $term->grab_button ($button, $modifiermask) 1688=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1610 1689
1690=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1691
1611Registers a synchronous button grab. See the XGrabButton manpage. 1692Register/unregister a synchronous button grab. See the XGrabButton
1693manpage.
1612 1694
1613=item $success = $term->grab ($eventtime[, $sync]) 1695=item $success = $term->grab ($eventtime[, $sync])
1614 1696
1615Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1697Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1616synchronous (C<$sync> is true). Also remembers the grab timestampe. 1698synchronous (C<$sync> is true). Also remembers the grab timestampe.
1734 my ($self, $text, $cb) = @_; 1816 my ($self, $text, $cb) = @_;
1735 1817
1736 $self->add_item ({ type => "button", text => $text, activate => $cb}); 1818 $self->add_item ({ type => "button", text => $text, activate => $cb});
1737} 1819}
1738 1820
1739=item $popup->add_toggle ($text, $cb, $initial_value) 1821=item $popup->add_toggle ($text, $initial_value, $cb)
1740 1822
1741Adds a toggle/checkbox item to the popup. Teh callback gets called 1823Adds a toggle/checkbox item to the popup. The callback gets called
1742whenever it gets toggled, with a boolean indicating its value as its first 1824whenever it gets toggled, with a boolean indicating its new value as its
1743argument. 1825first argument.
1744 1826
1745=cut 1827=cut
1746 1828
1747sub add_toggle { 1829sub add_toggle {
1748 my ($self, $text, $cb, $value) = @_; 1830 my ($self, $text, $value, $cb) = @_;
1749 1831
1750 my $item; $item = { 1832 my $item; $item = {
1751 type => "button", 1833 type => "button",
1752 text => " $text", 1834 text => " $text",
1753 value => $value, 1835 value => $value,

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines