ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/rxvt-unicode/doc/rxvtperl.3.txt
(Generate patch)

Comparing rxvt-unicode/doc/rxvtperl.3.txt (file contents):
Revision 1.33 by root, Fri Jan 20 22:49:34 2006 UTC vs.
Revision 1.39 by root, Mon Feb 6 05:55:33 2006 UTC

… …
57 must contain at least one pair of capturing parentheses, which will 57 must contain at least one pair of capturing parentheses, which will
58 be used for the match. For example, the followign adds a regex that 58 be used for the match. For example, the followign adds a regex that
59 matches everything between two vertical bars: 59 matches everything between two vertical bars:
60 60
61 URxvt.selection.pattern-0: \\|([^|]+)\\| 61 URxvt.selection.pattern-0: \\|([^|]+)\\|
62
63 Another example: Programs I use often output "absolute path: " at
64 the beginning of a line when they process multiple files. The
65 following pattern matches the filename (note, there is a single
66 space at the very end):
67
68 URxvt.selection.pattern-0: ^(/[^:]+):\
62 69
63 You can look at the source of the selection extension to see more 70 You can look at the source of the selection extension to see more
64 interesting uses, such as parsing a line from beginning to end. 71 interesting uses, such as parsing a line from beginning to end.
65 72
66 This extension also offers following bindable keyboard commands: 73 This extension also offers following bindable keyboard commands:
… …
112 "End" jumps to the bottom. "Escape" leaves search mode and returns 119 "End" jumps to the bottom. "Escape" leaves search mode and returns
113 to the point where search was started, while "Enter" or "Return" 120 to the point where search was started, while "Enter" or "Return"
114 stay at the current position and additionally stores the first match 121 stay at the current position and additionally stores the first match
115 in the current line into the primary selection. 122 in the current line into the primary selection.
116 123
117 selection-autotransform 124 readline (enabled by default)
118 This selection allows you to do automatic transforms on a selection
119 whenever a selection is made.
120
121 It works by specifying perl snippets (most useful is a single "s///"
122 operator) that modify $_ as resources:
123
124 URxvt.selection-autotransform.0: transform
125 URxvt.selection-autotransform.1: transform
126 ...
127
128 For example, the following will transform selections of the form
129 "filename:number", often seen in compiler messages, into "vi
130 +$filename $word":
131
132 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
133
134 And this example matches the same,but replaces it with vi-commands
135 you can paste directly into your (vi :) editor:
136
137 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/
138
139 Of course, this can be modified to suit your needs and your editor
140 :)
141
142 To expand the example above to typical perl error messages ("XXX at
143 FILENAME line YYY."), you need a slightly more elaborate solution:
144
145 URxvt.selection.pattern-0: ( at .*? line \\d+[,.])
146 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/
147
148 The first line tells the selection code to treat the unchanging part
149 of every error message as a selection pattern, and the second line
150 transforms the message into vi commands to load the file.
151
152 readline
153 A support package that tries to make editing with readline easier. 125 A support package that tries to make editing with readline easier.
154 At the moment, it reacts to clicking with the left mouse button by 126 At the moment, it reacts to clicking with the left mouse button by
155 trying to move the text cursor to this position. It does so by 127 trying to move the text cursor to this position. It does so by
156 generating as many cursor-left or cursor-right keypresses as 128 generating as many cursor-left or cursor-right keypresses as
157 required (the this only works for programs that correctly support 129 required (the this only works for programs that correctly support
158 wide characters). 130 wide characters).
159 131
160 It only works when clicking into the same line (possibly extended 132 To avoid too many false positives, this is only done when:
161 over multiple rows) as the text cursor and on the primary screen, to 133
162 reduce the risk of misinterpreting. The normal selection isn't 134 - the tty is in ICANON state.
163 disabled, so quick successive clicks might interfere with selection 135 - the text cursor is visible.
164 creation in harmless ways. 136 - the primary screen is currently being displayed.
137 - the mouse is on the same (multi-row-) line as the text cursor.
138
139 The normal selection mechanism isn't disabled, so quick successive
140 clicks might interfere with selection creation in harmless ways.
141
142 selection-autotransform
143 This selection allows you to do automatic transforms on a selection
144 whenever a selection is made.
145
146 It works by specifying perl snippets (most useful is a single "s///"
147 operator) that modify $_ as resources:
148
149 URxvt.selection-autotransform.0: transform
150 URxvt.selection-autotransform.1: transform
151 ...
152
153 For example, the following will transform selections of the form
154 "filename:number", often seen in compiler messages, into "vi
155 +$filename $word":
156
157 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
158
159 And this example matches the same,but replaces it with vi-commands
160 you can paste directly into your (vi :) editor:
161
162 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/
163
164 Of course, this can be modified to suit your needs and your editor
165 :)
166
167 To expand the example above to typical perl error messages ("XXX at
168 FILENAME line YYY."), you need a slightly more elaborate solution:
169
170 URxvt.selection.pattern-0: ( at .*? line \\d+[,.])
171 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/
172
173 The first line tells the selection code to treat the unchanging part
174 of every error message as a selection pattern, and the second line
175 transforms the message into vi commands to load the file.
165 176
166 tabbed 177 tabbed
167 This transforms the terminal into a tabbar with additional 178 This transforms the terminal into a tabbar with additional
168 terminals, that is, it implements what is commonly refered to as 179 terminals, that is, it implements what is commonly refered to as
169 "tabbed terminal". The topmost line displays a "[NEW]" button, 180 "tabbed terminal". The topmost line displays a "[NEW]" button,
… …
172 183
173 Clicking a button will activate that tab. Pressing Shift-Left and 184 Clicking a button will activate that tab. Pressing Shift-Left and
174 Shift-Right will switch to the tab left or right of the current one, 185 Shift-Right will switch to the tab left or right of the current one,
175 while Shift-Down creates a new tab. 186 while Shift-Down creates a new tab.
176 187
188 The tabbar itself can be configured similarly to a normal terminal,
189 but with a resource class of "URxvt.tabbed". In addition, it
190 supports the following four resources (shown with defaults):
191
192 URxvt.tabbed.tabbar-fg: <colour-index, default 3>
193 URxvt.tabbed.tabbar-bg: <colour-index, default 0>
194 URxvt.tabbed.tab-fg: <colour-index, default 0>
195 URxvt.tabbed.tab-bg: <colour-index, default 1>
196
197 See *COLOR AND GRAPHICS* in the rxvt(1) manpage for valid indices.
198
177 mark-urls 199 mark-urls
178 Uses per-line display filtering ("on_line_update") to underline urls 200 Uses per-line display filtering ("on_line_update") to underline urls
179 and make them clickable. When middle-clicked, the program specified 201 and make them clickable. When middle-clicked, the program specified
180 in the resource "urlLauncher" (default "x-www-browser") will be 202 in the resource "urlLauncher" (default "x-www-browser") will be
181 started with the URL as first argument. 203 started with the URL as first argument.
182 204
205 xim-onthespot
206 This (experimental) perl extension implements OnTheSpot editing. It
207 does not work perfectly, and some input methods don't seem to work
208 well with OnTheSpot editing in general, but it seems to work at
209 leats for SCIM and kinput2.
210
211 You enable it by specifying this extension and a preedit style of
212 "OnTheSpot", i.e.:
213
214 rxvt -pt OnTheSpot -pe xim-onthespot
215
183 automove-background 216 automove-background
184 This is basically a one-line extension that dynamically changes the 217 This is basically a one-line extension that dynamically changes the
185 background pixmap offset to the window position, in effect creating 218 background pixmap offset to the window position, in effect creating
186 the same effect as pseudo transparency with a custom pixmap. No 219 the same effect as pseudo transparency with a custom pixmap. No
187 scaling is supported in this mode. Exmaple: 220 scaling is supported in this mode. Exmaple:
… …
194 U+259F) by a similar-looking ascii character. 227 U+259F) by a similar-looking ascii character.
195 228
196 digital-clock 229 digital-clock
197 Displays a digital clock using the built-in overlay. 230 Displays a digital clock using the built-in overlay.
198 231
199 example-refresh-hooks 232 remote-clipboard
200 Displays a very simple digital clock in the upper right corner of 233 Somewhat of a misnomer, this extension adds two menu entries to the
201 the window. Illustrates overwriting the refresh callbacks to create 234 selection popup that allows one ti run external commands to store
202 your own overlays or changes. 235 the selection somewhere and fetch it again.
236
237 We use it to implement a "distributed selection mechanism", which
238 just means that one command uploads the file to a remote server, and
239 another reads it.
240
241 The commands can be set using the "URxvt.remote-selection.store" and
242 "URxvt.remote-selection.fetch" resources. The first should read the
243 selection to store from STDIN (always in UTF-8), the second should
244 provide the selection data on STDOUT (also in UTF-8).
245
246 The defaults (which are likely useless to you) use rsh and cat:
247
248 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
249 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
203 250
204 selection-pastebin 251 selection-pastebin
205 This is a little rarely useful extension that Uploads the selection 252 This is a little rarely useful extension that Uploads the selection
206 as textfile to a remote site (or does other things). (The 253 as textfile to a remote site (or does other things). (The
207 implementation is not currently secure for use in a multiuser 254 implementation is not currently secure for use in a multiuser
… …
226 After a successful upload the selection will be replaced by the text 273 After a successful upload the selection will be replaced by the text
227 given in the "selection-pastebin-url" resource (again, the % is the 274 given in the "selection-pastebin-url" resource (again, the % is the
228 placeholder for the filename): 275 placeholder for the filename):
229 276
230 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/% 277 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
278
279 example-refresh-hooks
280 Displays a very simple digital clock in the upper right corner of
281 the window. Illustrates overwriting the refresh callbacks to create
282 your own overlays or changes.
231 283
232API DOCUMENTATION 284API DOCUMENTATION
233 General API Considerations 285 General API Considerations
234 All objects (such as terminals, time watchers etc.) are typical 286 All objects (such as terminals, time watchers etc.) are typical
235 reference-to-hash objects. The hash can be used to store anything you 287 reference-to-hash objects. The hash can be used to store anything you
… …
309 Called at the very end of initialisation of a new terminal, just 361 Called at the very end of initialisation of a new terminal, just
310 before trying to map (display) the toplevel and returning to the 362 before trying to map (display) the toplevel and returning to the
311 mainloop. 363 mainloop.
312 364
313 on_destroy $term 365 on_destroy $term
314 Called whenever something tries to destroy terminal, before doing 366 Called whenever something tries to destroy terminal, when the
315 anything yet. If this hook returns true, then destruction is 367 terminal is still fully functional (not for long, though).
316 skipped, but this is rarely a good idea.
317 368
318 on_reset $term 369 on_reset $term
319 Called after the screen is "reset" for any reason, such as resizing 370 Called after the screen is "reset" for any reason, such as resizing
320 or control sequences. Here is where you can react on changes to 371 or control sequences. Here is where you can react on changes to
321 size-related variables. 372 size-related variables.
… …
413 display code is run after this hook, and takes precedence. 464 display code is run after this hook, and takes precedence.
414 465
415 on_refresh_end $term 466 on_refresh_end $term
416 Called just after the screen gets redrawn. See "on_refresh_begin". 467 Called just after the screen gets redrawn. See "on_refresh_begin".
417 468
418 on_keyboard_command $term, $string 469 on_user_command $term, $string
419 Called whenever the user presses a key combination that has a 470 Called whenever the a user-configured event is being activated (e.g.
420 "perl:string" action bound to it (see description of the keysym 471 via a "perl:string" action bound to a key, see description of the
421 resource in the rxvt(1) manpage). 472 keysym resource in the rxvt(1) manpage).
473
474 The event is simply the action string. This interface is assumed to
475 change slightly in the future.
422 476
423 on_x_event $term, $event 477 on_x_event $term, $event
424 Called on every X event received on the vt window (and possibly 478 Called on every X event received on the vt window (and possibly
425 other windows). Should only be used as a last resort. Most event 479 other windows). Should only be used as a last resort. Most event
426 structure members are not passed. 480 structure members are not passed.
… …
507 561
508 Using this function has the advantage that its output ends up in the 562 Using this function has the advantage that its output ends up in the
509 correct place, e.g. on stderr of the connecting urxvtc client. 563 correct place, e.g. on stderr of the connecting urxvtc client.
510 564
511 Messages have a size limit of 1023 bytes currently. 565 Messages have a size limit of 1023 bytes currently.
566
567 @terms = urxvt::termlist
568 Returns all urxvt::term objects that exist in this process,
569 regardless of wether they are started, being destroyed etc., so be
570 careful. Only term objects that have perl extensions attached will
571 be returned (because there is no urxvt::term objet associated with
572 others).
512 573
513 $time = urxvt::NOW 574 $time = urxvt::NOW
514 Returns the "current time" (as per the event loop). 575 Returns the "current time" (as per the event loop).
515 576
516 urxvt::CurrentTime 577 urxvt::CurrentTime
… …
560 $background = urxvt::GET_BASEBG $rend 621 $background = urxvt::GET_BASEBG $rend
561 Return the foreground/background colour index, respectively. 622 Return the foreground/background colour index, respectively.
562 623
563 $rend = urxvt::SET_FGCOLOR $rend, $new_colour 624 $rend = urxvt::SET_FGCOLOR $rend, $new_colour
564 $rend = urxvt::SET_BGCOLOR $rend, $new_colour 625 $rend = urxvt::SET_BGCOLOR $rend, $new_colour
626 $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
565 Replace the foreground/background colour in the rendition mask with 627 Replace the foreground/background colour in the rendition mask with
566 the specified one. 628 the specified one.
567 629
568 $value = urxvt::GET_CUSTOM $rend 630 $value = urxvt::GET_CUSTOM $rend
569 Return the "custom" value: Every rendition has 5 bits for use by 631 Return the "custom" value: Every rendition has 5 bits for use by
… …
588 %ENV-like hash which defines the environment of the new terminal. 650 %ENV-like hash which defines the environment of the new terminal.
589 651
590 Croaks (and probably outputs an error message) if the new instance 652 Croaks (and probably outputs an error message) if the new instance
591 couldn't be created. Returns "undef" if the new instance didn't 653 couldn't be created. Returns "undef" if the new instance didn't
592 initialise perl, and the terminal object otherwise. The "init" and 654 initialise perl, and the terminal object otherwise. The "init" and
593 "start" hooks will be called during this call. 655 "start" hooks will be called before this call returns, and are free
656 to refer to global data (which is race free).
594 657
595 $term->destroy 658 $term->destroy
596 Destroy the terminal object (close the window, free resources etc.). 659 Destroy the terminal object (close the window, free resources etc.).
597 Please note that rxvt will not exit as long as any event watchers 660 Please note that rxvt will not exit as long as any event watchers
598 (timers, io watchers) are still active. 661 (timers, io watchers) are still active.
… …
794 Replaces the event mask of the pty watcher by the given event mask. 857 Replaces the event mask of the pty watcher by the given event mask.
795 Can be used to suppress input and output handling to the pty/tty. 858 Can be used to suppress input and output handling to the pty/tty.
796 See the description of "urxvt::timer->events". Make sure to always 859 See the description of "urxvt::timer->events". Make sure to always
797 restore the previous value. 860 restore the previous value.
798 861
862 $fd = $term->pty_fd
863 Returns the master file descriptor for the pty in use, or -1 if no
864 pty is used.
865
799 $windowid = $term->parent 866 $windowid = $term->parent
800 Return the window id of the toplevel window. 867 Return the window id of the toplevel window.
801 868
802 $windowid = $term->vt 869 $windowid = $term->vt
803 Return the window id of the terminal window. 870 Return the window id of the terminal window.
… …
805 $term->vt_emask_add ($x_event_mask) 872 $term->vt_emask_add ($x_event_mask)
806 Adds the specified events to the vt event mask. Useful e.g. when you 873 Adds the specified events to the vt event mask. Useful e.g. when you
807 want to receive pointer events all the times: 874 want to receive pointer events all the times:
808 875
809 $term->vt_emask_add (urxvt::PointerMotionMask); 876 $term->vt_emask_add (urxvt::PointerMotionMask);
877
878 $term->focus_in
879 $term->focus_out
880 $term->key_press ($state, $keycode[, $time])
881 $term->key_release ($state, $keycode[, $time])
882 Deliver various fake events to to terminal.
810 883
811 $window_width = $term->width 884 $window_width = $term->width
812 $window_height = $term->height 885 $window_height = $term->height
813 $font_width = $term->fwidth 886 $font_width = $term->fwidth
814 $font_height = $term->fheight 887 $font_height = $term->fheight
… …
840 applicable. 913 applicable.
841 914
842 $screen = $term->current_screen 915 $screen = $term->current_screen
843 Returns the currently displayed screen (0 primary, 1 secondary). 916 Returns the currently displayed screen (0 primary, 1 secondary).
844 917
918 $cursor_is_hidden = $term->hidden_cursor
919 Returns wether the cursor is currently hidden or not.
920
845 $view_start = $term->view_start ([$newvalue]) 921 $view_start = $term->view_start ([$newvalue])
846 Returns the row number of the topmost displayed line. Maximum value 922 Returns the row number of the topmost displayed line. Maximum value
847 is 0, which displays the normal terminal contents. Lower values 923 is 0, which displays the normal terminal contents. Lower values
848 scroll this many lines into the scrollback buffer. 924 scroll this many lines into the scrollback buffer.
849 925
… …
866 replace only parts of a line. The font index in the rendition will 942 replace only parts of a line. The font index in the rendition will
867 automatically be updated. 943 automatically be updated.
868 944
869 $text is in a special encoding: tabs and wide characters that use 945 $text is in a special encoding: tabs and wide characters that use
870 more than one cell when displayed are padded with $urxvt::NOCHAR 946 more than one cell when displayed are padded with $urxvt::NOCHAR
871 characters. Characters with combining characters and other 947 (chr 65535) characters. Characters with combining characters and
872 characters that do not fit into the normal tetx encoding will be 948 other characters that do not fit into the normal tetx encoding will
873 replaced with characters in the private use area. 949 be replaced with characters in the private use area.
874 950
875 You have to obey this encoding when changing text. The advantage is 951 You have to obey this encoding when changing text. The advantage is
876 that "substr" and similar functions work on screen cells and not on 952 that "substr" and similar functions work on screen cells and not on
877 characters. 953 characters.
878 954
… …
935 1011
936 $string = $term->special_decode $text 1012 $string = $term->special_decode $text
937 Converts rxvt-unicodes text reprsentation into a perl string. See 1013 Converts rxvt-unicodes text reprsentation into a perl string. See
938 "$term->ROW_t" for details. 1014 "$term->ROW_t" for details.
939 1015
940 $success = $term->grab_button ($button, $modifiermask) 1016 $success = $term->grab_button ($button, $modifiermask[, $window =
1017 $term->vt])
1018 $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
941 Registers a synchronous button grab. See the XGrabButton manpage. 1019 Register/unregister a synchronous button grab. See the XGrabButton
1020 manpage.
942 1021
943 $success = $term->grab ($eventtime[, $sync]) 1022 $success = $term->grab ($eventtime[, $sync])
944 Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1023 Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
945 synchronous ($sync is true). Also remembers the grab timestampe. 1024 synchronous ($sync is true). Also remembers the grab timestampe.
946 1025

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines