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.121 by root, Fri Jan 20 22:49:34 2006 UTC vs.
Revision 1.132 by root, Mon Feb 6 05:40:15 2006 UTC

66contain at least one pair of capturing parentheses, which will be used for 66contain at least one pair of capturing parentheses, which will be used for
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
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: ^(/[^:]+):\
71 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:
127bottom. C<Escape> leaves search mode and returns to the point where search 134bottom. 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 135was 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 136additionally stores the first match in the current line into the primary
130selection. 137selection.
131 138
132=item selection-autotransform 139=item readline (enabled by default)
133
134This selection allows you to do automatic transforms on a selection
135whenever a selection is made.
136
137It works by specifying perl snippets (most useful is a single C<s///>
138operator) that modify C<$_> as resources:
139
140 URxvt.selection-autotransform.0: transform
141 URxvt.selection-autotransform.1: transform
142 ...
143
144For example, the following will transform selections of the form
145C<filename:number>, often seen in compiler messages, into C<vi +$filename
146$word>:
147
148 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
149
150And this example matches the same,but replaces it with vi-commands you can
151paste directly into your (vi :) editor:
152
153 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/
154
155Of course, this can be modified to suit your needs and your editor :)
156
157To expand the example above to typical perl error messages ("XXX at
158FILENAME line YYY."), you need a slightly more elaborate solution:
159
160 URxvt.selection.pattern-0: ( at .*? line \\d+[,.])
161 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/
162
163The first line tells the selection code to treat the unchanging part of
164every error message as a selection pattern, and the second line transforms
165the message into vi commands to load the file.
166
167=item readline
168 140
169A support package that tries to make editing with readline easier. At the 141A support package that tries to make editing with readline easier. At the
170moment, it reacts to clicking with the left mouse button by trying to 142moment, it reacts to clicking with the left mouse button by trying to
171move the text cursor to this position. It does so by generating as many 143move the text cursor to this position. It does so by generating as many
172cursor-left or cursor-right keypresses as required (the this only works 144cursor-left or cursor-right keypresses as required (the this only works
173for programs that correctly support wide characters). 145for programs that correctly support wide characters).
174 146
175It only works when clicking into the same line (possibly extended over 147To avoid too many false positives, this is only done when:
176multiple rows) as the text cursor and on the primary screen, to reduce the 148
177risk of misinterpreting. The normal selection isn't disabled, so quick 149=over 4
150
151=item - the tty is in ICANON state.
152
153=item - the text cursor is visible.
154
155=item - the primary screen is currently being displayed.
156
157=item - the mouse is on the same (multi-row-) line as the text cursor.
158
159=back
160
161The normal selection mechanism isn't disabled, so quick successive clicks
178successive clicks might interfere with selection creation in harmless 162might interfere with selection creation in harmless ways.
179ways. 163
164=item selection-autotransform
165
166This selection allows you to do automatic transforms on a selection
167whenever a selection is made.
168
169It works by specifying perl snippets (most useful is a single C<s///>
170operator) that modify C<$_> as resources:
171
172 URxvt.selection-autotransform.0: transform
173 URxvt.selection-autotransform.1: transform
174 ...
175
176For example, the following will transform selections of the form
177C<filename:number>, often seen in compiler messages, into C<vi +$filename
178$word>:
179
180 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
181
182And this example matches the same,but replaces it with vi-commands you can
183paste directly into your (vi :) editor:
184
185 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/
186
187Of course, this can be modified to suit your needs and your editor :)
188
189To expand the example above to typical perl error messages ("XXX at
190FILENAME line YYY."), you need a slightly more elaborate solution:
191
192 URxvt.selection.pattern-0: ( at .*? line \\d+[,.])
193 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/
194
195The first line tells the selection code to treat the unchanging part of
196every error message as a selection pattern, and the second line transforms
197the message into vi commands to load the file.
180 198
181=item tabbed 199=item tabbed
182 200
183This transforms the terminal into a tabbar with additional terminals, that 201This transforms the terminal into a tabbar with additional terminals, that
184is, it implements what is commonly refered to as "tabbed terminal". The topmost line 202is, it implements what is commonly refered to as "tabbed terminal". The topmost line
187 205
188Clicking a button will activate that tab. Pressing B<Shift-Left> and 206Clicking a button will activate that tab. Pressing B<Shift-Left> and
189B<Shift-Right> will switch to the tab left or right of the current one, 207B<Shift-Right> will switch to the tab left or right of the current one,
190while B<Shift-Down> creates a new tab. 208while B<Shift-Down> creates a new tab.
191 209
210The tabbar itself can be configured similarly to a normal terminal, but
211with a resource class of C<URxvt.tabbed>. In addition, it supports the
212following four resources (shown with defaults):
213
214 URxvt.tabbed.tabbar-fg: <colour-index, default 3>
215 URxvt.tabbed.tabbar-bg: <colour-index, default 0>
216 URxvt.tabbed.tab-fg: <colour-index, default 0>
217 URxvt.tabbed.tab-bg: <colour-index, default 1>
218
219See I<COLOR AND GRAPHICS> in the @@RXVT_NAME@@(1) manpage for valid
220indices.
221
192=item mark-urls 222=item mark-urls
193 223
194Uses per-line display filtering (C<on_line_update>) to underline urls and 224Uses per-line display filtering (C<on_line_update>) to underline urls and
195make them clickable. When middle-clicked, the program specified in the 225make them clickable. When middle-clicked, the program specified in the
196resource C<urlLauncher> (default C<x-www-browser>) will be started with 226resource C<urlLauncher> (default C<x-www-browser>) will be started with
197the URL as first argument. 227the URL as first argument.
198 228
229=item xim-onthespot
230
231This (experimental) perl extension implements OnTheSpot editing. It does
232not work perfectly, and some input methods don't seem to work well with
233OnTheSpot editing in general, but it seems to work at leats for SCIM and
234kinput2.
235
236You enable it by specifying this extension and a preedit style of
237C<OnTheSpot>, i.e.:
238
239 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot
240
199=item automove-background 241=item automove-background
200 242
201This is basically a one-line extension that dynamically changes the background pixmap offset 243This is basically a one-line extension that dynamically changes the background pixmap offset
202to the window position, in effect creating the same effect as pseudo transparency with 244to the window position, in effect creating the same effect as pseudo transparency with
203a custom pixmap. No scaling is supported in this mode. Exmaple: 245a custom pixmap. No scaling is supported in this mode. Exmaple:
212 254
213=item digital-clock 255=item digital-clock
214 256
215Displays a digital clock using the built-in overlay. 257Displays a digital clock using the built-in overlay.
216 258
217=item example-refresh-hooks 259=item remote-clipboard
218 260
219Displays a very simple digital clock in the upper right corner of the 261Somewhat of a misnomer, this extension adds two menu entries to the
220window. Illustrates overwriting the refresh callbacks to create your own 262selection popup that allows one ti run external commands to store the
221overlays or changes. 263selection somewhere and fetch it again.
264
265We use it to implement a "distributed selection mechanism", which just
266means that one command uploads the file to a remote server, and another
267reads it.
268
269The commands can be set using the C<URxvt.remote-selection.store> and
270C<URxvt.remote-selection.fetch> resources. The first should read the
271selection to store from STDIN (always in UTF-8), the second should provide
272the selection data on STDOUT (also in UTF-8).
273
274The defaults (which are likely useless to you) use rsh and cat:
275
276 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
277 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
222 278
223=item selection-pastebin 279=item selection-pastebin
224 280
225This is a little rarely useful extension that Uploads the selection as 281This is a little rarely useful extension that Uploads the selection as
226textfile to a remote site (or does other things). (The implementation is 282textfile to a remote site (or does other things). (The implementation is
246After a successful upload the selection will be replaced by the text given 302After a successful upload the selection will be replaced by the text given
247in the C<selection-pastebin-url> resource (again, the % is the placeholder 303in the C<selection-pastebin-url> resource (again, the % is the placeholder
248for the filename): 304for the filename):
249 305
250 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/% 306 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
307
308=item example-refresh-hooks
309
310Displays a very simple digital clock in the upper right corner of the
311window. Illustrates overwriting the refresh callbacks to create your own
312overlays or changes.
251 313
252=back 314=back
253 315
254=head1 API DOCUMENTATION 316=head1 API DOCUMENTATION
255 317
352Called at the very end of initialisation of a new terminal, just before 414Called at the very end of initialisation of a new terminal, just before
353trying to map (display) the toplevel and returning to the mainloop. 415trying to map (display) the toplevel and returning to the mainloop.
354 416
355=item on_destroy $term 417=item on_destroy $term
356 418
357Called whenever something tries to destroy terminal, before doing anything 419Called whenever something tries to destroy terminal, when the terminal is
358yet. If this hook returns true, then destruction is skipped, but this is 420still fully functional (not for long, though).
359rarely a good idea.
360 421
361=item on_reset $term 422=item on_reset $term
362 423
363Called after the screen is "reset" for any reason, such as resizing or 424Called after the screen is "reset" for any reason, such as resizing or
364control sequences. Here is where you can react on changes to size-related 425control sequences. Here is where you can react on changes to size-related
466 527
467=item on_refresh_end $term 528=item on_refresh_end $term
468 529
469Called just after the screen gets redrawn. See C<on_refresh_begin>. 530Called just after the screen gets redrawn. See C<on_refresh_begin>.
470 531
471=item on_keyboard_command $term, $string 532=item on_user_command $term, $string
472 533
473Called whenever the user presses a key combination that has a 534Called whenever the a user-configured event is being activated (e.g. via
474C<perl:string> action bound to it (see description of the B<keysym> 535a C<perl:string> action bound to a key, see description of the B<keysym>
475resource in the @@RXVT_NAME@@(1) manpage). 536resource in the @@RXVT_NAME@@(1) manpage).
537
538The event is simply the action string. This interface is assumed to change
539slightly in the future.
476 540
477=item on_x_event $term, $event 541=item on_x_event $term, $event
478 542
479Called on every X event received on the vt window (and possibly other 543Called on every X event received on the vt window (and possibly other
480windows). Should only be used as a last resort. Most event structure 544windows). Should only be used as a last resort. Most event structure
552our $LIBDIR; 616our $LIBDIR;
553our $RESNAME; 617our $RESNAME;
554our $RESCLASS; 618our $RESCLASS;
555our $RXVTNAME; 619our $RXVTNAME;
556 620
557our $NOCHAR = chr 0xfffe; 621our $NOCHAR = chr 0xffff;
558 622
559=head2 Variables in the C<urxvt> Package 623=head2 Variables in the C<urxvt> Package
560 624
561=over 4 625=over 4
562 626
614 678
615Using this function has the advantage that its output ends up in the 679Using this function has the advantage that its output ends up in the
616correct place, e.g. on stderr of the connecting urxvtc client. 680correct place, e.g. on stderr of the connecting urxvtc client.
617 681
618Messages have a size limit of 1023 bytes currently. 682Messages have a size limit of 1023 bytes currently.
683
684=item @terms = urxvt::termlist
685
686Returns all urxvt::term objects that exist in this process, regardless of
687wether they are started, being destroyed etc., so be careful. Only term
688objects that have perl extensions attached will be returned (because there
689is no urxvt::term objet associated with others).
619 690
620=item $time = urxvt::NOW 691=item $time = urxvt::NOW
621 692
622Returns the "current time" (as per the event loop). 693Returns the "current time" (as per the event loop).
623 694
681Return the foreground/background colour index, respectively. 752Return the foreground/background colour index, respectively.
682 753
683=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour 754=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
684 755
685=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour 756=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
757
758=item $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
686 759
687Replace the foreground/background colour in the rendition mask with the 760Replace the foreground/background colour in the rendition mask with the
688specified one. 761specified one.
689 762
690=item $value = urxvt::GET_CUSTOM $rend 763=item $value = urxvt::GET_CUSTOM $rend
709 unless $msg =~ /\n$/; 782 unless $msg =~ /\n$/;
710 urxvt::warn ($msg); 783 urxvt::warn ($msg);
711 }; 784 };
712} 785}
713 786
787no warnings 'utf8';
788
714my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 789my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
715 790
716sub verbose { 791sub verbose {
717 my ($level, $msg) = @_; 792 my ($level, $msg) = @_;
718 warn "$msg\n" if $level <= $verbosity; 793 warn "$msg\n" if $level <= $verbosity;
734 809
735 open my $fh, "<:raw", $path 810 open my $fh, "<:raw", $path
736 or die "$path: $!"; 811 or die "$path: $!";
737 812
738 my $source = 813 my $source =
739 "package $pkg; use strict; use utf8;\n" 814 "package $pkg; use strict; use utf8; no warnings 'utf8';\n"
740 . "#line 1 \"$path\"\n{\n" 815 . "#line 1 \"$path\"\n{\n"
741 . (do { local $/; <$fh> }) 816 . (do { local $/; <$fh> })
742 . "\n};\n1"; 817 . "\n};\n1";
743 818
744 eval $source 819 eval $source
769 $TERM->register_package ($_) for @pkg; 844 $TERM->register_package ($_) for @pkg;
770 } 845 }
771 846
772 for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) { 847 for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
773 if ($_ eq "default") { 848 if ($_ eq "default") {
774 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback); 849 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback readline);
775 } elsif (/^-(.*)$/) { 850 } elsif (/^-(.*)$/) {
776 delete $ext_arg{$1}; 851 delete $ext_arg{$1};
777 } elsif (/^([^<]+)<(.*)>$/) { 852 } elsif (/^([^<]+)<(.*)>$/) {
778 push @{ $ext_arg{$1} }, $2; 853 push @{ $ext_arg{$1} }, $2;
779 } else { 854 } else {
824 # clear package 899 # clear package
825 %$TERM = (); 900 %$TERM = ();
826 } 901 }
827 902
828 $retval 903 $retval
904}
905
906sub SET_COLOR($$$) {
907 SET_BGCOLOR (SET_FGCOLOR ($_[0], $_[1]), $_[2])
829} 908}
830 909
831# urxvt::term::extension 910# urxvt::term::extension
832 911
833package urxvt::term::extension; 912package urxvt::term::extension;
1002hash which defines the environment of the new terminal. 1081hash which defines the environment of the new terminal.
1003 1082
1004Croaks (and probably outputs an error message) if the new instance 1083Croaks (and probably outputs an error message) if the new instance
1005couldn't be created. Returns C<undef> if the new instance didn't 1084couldn't be created. Returns C<undef> if the new instance didn't
1006initialise perl, and the terminal object otherwise. The C<init> and 1085initialise perl, and the terminal object otherwise. The C<init> and
1007C<start> hooks will be called during this call. 1086C<start> hooks will be called before this call returns, and are free to
1087refer to global data (which is race free).
1008 1088
1009=cut 1089=cut
1010 1090
1011sub new { 1091sub new {
1012 my ($class, $env, @args) = @_; 1092 my ($class, $env, @args) = @_;
1013 1093
1094 $env or Carp::croak "environment hash missing in call to urxvt::term->new";
1095 @args or Carp::croak "name argument missing in call to urxvt::term->new";
1096
1014 _new ([ map "$_=$env->{$_}", keys %$env ], @args); 1097 _new ([ map "$_=$env->{$_}", keys %$env ], \@args);
1015} 1098}
1016 1099
1017=item $term->destroy 1100=item $term->destroy
1018 1101
1019Destroy the terminal object (close the window, free resources 1102Destroy the terminal object (close the window, free resources
1299Replaces the event mask of the pty watcher by the given event mask. Can 1382Replaces the event mask of the pty watcher by the given event mask. Can
1300be used to suppress input and output handling to the pty/tty. See the 1383be used to suppress input and output handling to the pty/tty. See the
1301description of C<< urxvt::timer->events >>. Make sure to always restore 1384description of C<< urxvt::timer->events >>. Make sure to always restore
1302the previous value. 1385the previous value.
1303 1386
1387=item $fd = $term->pty_fd
1388
1389Returns the master file descriptor for the pty in use, or C<-1> if no pty
1390is used.
1391
1304=item $windowid = $term->parent 1392=item $windowid = $term->parent
1305 1393
1306Return the window id of the toplevel window. 1394Return the window id of the toplevel window.
1307 1395
1308=item $windowid = $term->vt 1396=item $windowid = $term->vt
1313 1401
1314Adds the specified events to the vt event mask. Useful e.g. when you want 1402Adds the specified events to the vt event mask. Useful e.g. when you want
1315to receive pointer events all the times: 1403to receive pointer events all the times:
1316 1404
1317 $term->vt_emask_add (urxvt::PointerMotionMask); 1405 $term->vt_emask_add (urxvt::PointerMotionMask);
1406
1407=item $term->focus_in
1408
1409=item $term->focus_out
1410
1411=item $term->key_press ($state, $keycode[, $time])
1412
1413=item $term->key_release ($state, $keycode[, $time])
1414
1415Deliver various fake events to to terminal.
1318 1416
1319=item $window_width = $term->width 1417=item $window_width = $term->width
1320 1418
1321=item $window_height = $term->height 1419=item $window_height = $term->height
1322 1420
1376 1474
1377=item $screen = $term->current_screen 1475=item $screen = $term->current_screen
1378 1476
1379Returns the currently displayed screen (0 primary, 1 secondary). 1477Returns the currently displayed screen (0 primary, 1 secondary).
1380 1478
1479=item $cursor_is_hidden = $term->hidden_cursor
1480
1481Returns wether the cursor is currently hidden or not.
1482
1381=item $view_start = $term->view_start ([$newvalue]) 1483=item $view_start = $term->view_start ([$newvalue])
1382 1484
1383Returns the row number of the topmost displayed line. Maximum value is 1485Returns the row number of the topmost displayed line. Maximum value is
1384C<0>, which displays the normal terminal contents. Lower values scroll 1486C<0>, which displays the normal terminal contents. Lower values scroll
1385this many lines into the scrollback buffer. 1487this many lines into the scrollback buffer.
1403If C<$new_text> is specified, it will replace characters in the current 1505If C<$new_text> is specified, it will replace characters in the current
1404line, starting at column C<$start_col> (default C<0>), which is useful 1506line, starting at column C<$start_col> (default C<0>), which is useful
1405to replace only parts of a line. The font index in the rendition will 1507to replace only parts of a line. The font index in the rendition will
1406automatically be updated. 1508automatically be updated.
1407 1509
1408C<$text> is in a special encoding: tabs and wide characters that use 1510C<$text> is in a special encoding: tabs and wide characters that use more
1409more than one cell when displayed are padded with C<$urxvt::NOCHAR> 1511than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535)
1410characters. Characters with combining characters and other characters that 1512characters. Characters with combining characters and other characters that
1411do not fit into the normal tetx encoding will be replaced with characters 1513do not fit into the normal tetx encoding will be replaced with characters
1412in the private use area. 1514in the private use area.
1413 1515
1414You have to obey this encoding when changing text. The advantage is 1516You have to obey this encoding when changing text. The advantage is
1564=item $string = $term->special_decode $text 1666=item $string = $term->special_decode $text
1565 1667
1566Converts rxvt-unicodes text reprsentation into a perl string. See 1668Converts rxvt-unicodes text reprsentation into a perl string. See
1567C<< $term->ROW_t >> for details. 1669C<< $term->ROW_t >> for details.
1568 1670
1569=item $success = $term->grab_button ($button, $modifiermask) 1671=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1570 1672
1673=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1674
1571Registers a synchronous button grab. See the XGrabButton manpage. 1675Register/unregister a synchronous button grab. See the XGrabButton
1676manpage.
1572 1677
1573=item $success = $term->grab ($eventtime[, $sync]) 1678=item $success = $term->grab ($eventtime[, $sync])
1574 1679
1575Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1680Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1576synchronous (C<$sync> is true). Also remembers the grab timestampe. 1681synchronous (C<$sync> is true). Also remembers the grab timestampe.

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines