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.19 by root, Tue Jan 10 19:46:28 2006 UTC vs.
Revision 1.37 by root, Wed Jan 25 21:48:47 2006 UTC

29 29
30 You can activate them like this: 30 You can activate them like this:
31 31
32 rxvt -pe <extensionname> 32 rxvt -pe <extensionname>
33 33
34 Or by adding them to the resource for extensions loaded by default:
35
36 URxvt.perl-ext-common: default,automove-background,selection-autotransform
37
34 selection (enabled by default) 38 selection (enabled by default)
35 (More) intelligent selection. This extension tries to be more 39 (More) intelligent selection. This extension tries to be more
36 intelligent when the user extends selections (double-click). Right 40 intelligent when the user extends selections (double-click and
37 now, it tries to select urls and complete shell-quoted arguments, 41 further clicks). Right now, it tries to select words, urls and
38 which is very convenient, too, if your ls supports 42 complete shell-quoted arguments, which is very convenient, too, if
39 "--quoting-style=shell". 43 your ls supports "--quoting-style=shell".
40 44
45 A double-click usually selects the word under the cursor, further
46 clicks will enlarge the selection.
47
48 The selection works by trying to match a number of regexes and
49 displaying them in increasing order of length. You can add your own
50 regexes by specifying resources of the form:
51
52 URxvt.selection.pattern-0: perl-regex
53 URxvt.selection.pattern-1: perl-regex
54 ...
55
56 The index number (0, 1...) must not have any holes, and each regex
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
59 matches everything between two vertical bars:
60
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: ^(/[^:]+):\
69
70 You can look at the source of the selection extension to see more
71 interesting uses, such as parsing a line from beginning to end.
72
41 It also offers the following bindable keyboard command: 73 This extension also offers following bindable keyboard commands:
42 74
43 rot13 75 rot13
44 Rot-13 the selection when activated. Used via keyboard trigger: 76 Rot-13 the selection when activated. Used via keyboard trigger:
45 77
46 URxvt.keysym.C-M-r: perl:selection:rot13 78 URxvt.keysym.C-M-r: perl:selection:rot13
50 options at runtime. 82 options at runtime.
51 83
52 selection-popup (enabled by default) 84 selection-popup (enabled by default)
53 Binds a popup menu to Ctrl-Button3 that lets you convert the 85 Binds a popup menu to Ctrl-Button3 that lets you convert the
54 selection text into various other formats/action (such as uri 86 selection text into various other formats/action (such as uri
55 unescaping, perl evalution, web-browser starting etc.), depending on 87 unescaping, perl evaluation, web-browser starting etc.), depending
56 content. 88 on content.
89
90 Other extensions can extend this popup menu by pushing a code
91 reference onto "@{ $term-"{selection_popup_hook} }>, that is called
92 whenever the popup is displayed.
93
94 It's sole argument is the popup menu, which can be modified. The
95 selection is in $_, which can be used to decide wether to add
96 something or not. It should either return nothing or a string and a
97 code reference. The string will be used as button text and the code
98 reference will be called when the button gets activated and should
99 transform $_.
100
101 The following will add an entry "a to b" that transforms all "a"s in
102 the selection to "b"s, but only if the selection currently contains
103 any "a"s:
104
105 push @{ $self->{term}{selection_popup_hook} }, sub {
106 /a/ ? ("a to be" => sub { s/a/b/g }
107 : ()
108 };
57 109
58 searchable-scrollback<hotkey> (enabled by default) 110 searchable-scrollback<hotkey> (enabled by default)
59 Adds regex search functionality to the scrollback buffer, triggered 111 Adds regex search functionality to the scrollback buffer, triggered
60 by a hotkey (default: "M-s"). When in search mode, normal terminal 112 by a hotkey (default: "M-s"). While in search mode, normal terminal
61 input/output is suspended. 113 input/output is suspended and a regex is displayed at the bottom of
114 the screen.
62 115
63 "/" starts an incremental regex search, "n" searches further, "p" or 116 Inputting characters appends them to the regex and continues
64 "N" jump to the previous match, "G" jumps to the bottom and clears 117 incremental search. "BackSpace" removes a character from the regex,
65 the history, "enter" leaves search mode at the current position and 118 "Up" and "Down" search upwards/downwards in the scrollback buffer,
66 "escape" returns to the original position. 119 "End" jumps to the bottom. "Escape" leaves search mode and returns
120 to the point where search was started, while "Enter" or "Return"
121 stay at the current position and additionally stores the first match
122 in the current line into the primary selection.
67 123
68 digital-clock 124 readline (enabled by default)
69 Displays a digital clock using the built-in overlay. 125 A support package that tries to make editing with readline easier.
126 At the moment, it reacts to clicking with the left mouse button by
127 trying to move the text cursor to this position. It does so by
128 generating as many cursor-left or cursor-right keypresses as
129 required (the this only works for programs that correctly support
130 wide characters).
131
132 To avoid too many false positives, this is only done when:
133
134 - the tty is in ICANON state.
135 - the text cursor is visible.
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.
176
177 tabbed
178 This transforms the terminal into a tabbar with additional
179 terminals, that is, it implements what is commonly refered to as
180 "tabbed terminal". The topmost line displays a "[NEW]" button,
181 which, when clicked, will add a new tab, followed by one button per
182 tab.
183
184 Clicking a button will activate that tab. Pressing Shift-Left and
185 Shift-Right will switch to the tab left or right of the current one,
186 while Shift-Down creates a new tab.
70 187
71 mark-urls 188 mark-urls
72 Uses per-line display filtering ("on_line_update") to underline 189 Uses per-line display filtering ("on_line_update") to underline urls
73 urls. 190 and make them clickable. When middle-clicked, the program specified
191 in the resource "urlLauncher" (default "x-www-browser") will be
192 started with the URL as first argument.
193
194 xim-onthespot
195 This (experimental) perl extension implements OnTheSpot editing. It
196 does not work perfectly, and some input methods don't seem to work
197 well with OnTheSpot editing in general, but it seems to work at
198 leats for SCIM and kinput2.
199
200 You enable it by specifying this extension and a preedit style of
201 "OnTheSpot", i.e.:
202
203 rxvt -pt OnTheSpot -pe xim-onthespot
204
205 automove-background
206 This is basically a one-line extension that dynamically changes the
207 background pixmap offset to the window position, in effect creating
208 the same effect as pseudo transparency with a custom pixmap. No
209 scaling is supported in this mode. Exmaple:
210
211 rxvt -pixmap background.xpm -pe automove-background
74 212
75 block-graphics-to-ascii 213 block-graphics-to-ascii
76 A not very useful example of filtering all text output to the 214 A not very useful example of filtering all text output to the
77 terminal, by replacing all line-drawing characters (U+2500 .. 215 terminal, by replacing all line-drawing characters (U+2500 ..
78 U+259F) by a similar-looking ascii character. 216 U+259F) by a similar-looking ascii character.
217
218 digital-clock
219 Displays a digital clock using the built-in overlay.
220
221 remote-clipboard
222 Somewhat of a misnomer, this extension adds two menu entries to the
223 selection popup that allows one ti run external commands to store
224 the selection somewhere and fetch it again.
225
226 We use it to implement a "distributed selection mechanism", which
227 just means that one command uploads the file to a remote server, and
228 another reads it.
229
230 The commands can be set using the "URxvt.remote-selection.store" and
231 "URxvt.remote-selection.fetch" resources. The first should read the
232 selection to store from STDIN (always in UTF-8), the second should
233 provide the selection data on STDOUT (also in UTF-8).
234
235 The defaults (which are likely useless to you) use rsh and cat:
236
237 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
238 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
239
240 selection-pastebin
241 This is a little rarely useful extension that Uploads the selection
242 as textfile to a remote site (or does other things). (The
243 implementation is not currently secure for use in a multiuser
244 environment as it writes to /tmp directly.).
245
246 It listens to the "selection-pastebin:remote-pastebin" keyboard
247 command, i.e.
248
249 URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin
250
251 Pressing this combination runs a command with "%" replaced by the
252 name of the textfile. This command can be set via a resource:
253
254 URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
255
256 And the default is likely not useful to anybody but the few people
257 around here :)
258
259 The name of the textfile is the hex encoded md5 sum of the
260 selection, so the same content should lead to the same filename.
261
262 After a successful upload the selection will be replaced by the text
263 given in the "selection-pastebin-url" resource (again, the % is the
264 placeholder for the filename):
265
266 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
79 267
80 example-refresh-hooks 268 example-refresh-hooks
81 Displays a very simple digital clock in the upper right corner of 269 Displays a very simple digital clock in the upper right corner of
82 the window. Illustrates overwriting the refresh callbacks to create 270 the window. Illustrates overwriting the refresh callbacks to create
83 your own overlays or changes. 271 your own overlays or changes.
98 Argument names also often indicate the type of a parameter. Here are 286 Argument names also often indicate the type of a parameter. Here are
99 some hints on what they mean: 287 some hints on what they mean:
100 288
101 $text 289 $text
102 Rxvt-unicodes special way of encoding text, where one "unicode" 290 Rxvt-unicodes special way of encoding text, where one "unicode"
103 character always represents one screen cell. See row_t for a 291 character always represents one screen cell. See ROW_t for a
104 discussion of this format. 292 discussion of this format.
105 293
106 $string 294 $string
107 A perl text string, with an emphasis on *text*. It can store all 295 A perl text string, with an emphasis on *text*. It can store all
108 unicode characters and is to be distinguished with text encoded in a 296 unicode characters and is to be distinguished with text encoded in a
142 be called whenever the relevant event happens. 330 be called whenever the relevant event happens.
143 331
144 The first argument passed to them is an extension oject as described in 332 The first argument passed to them is an extension oject as described in
145 the in the "Extension Objects" section. 333 the in the "Extension Objects" section.
146 334
147 All of these hooks must return a boolean value. If it is true, then the 335 All of these hooks must return a boolean value. If any of the called
148 event counts as being *consumed*, and the invocation of other hooks is 336 hooks returns true, then the event counts as being *consumed*, and the
149 skipped, and the relevant action might not be carried out by the C++ 337 relevant action might not be carried out by the C++ code.
150 code.
151 338
152 *When in doubt, return a false value (preferably "()").* 339 *When in doubt, return a false value (preferably "()").*
153 340
154 on_init $term 341 on_init $term
155 Called after a new terminal object has been initialized, but before 342 Called after a new terminal object has been initialized, but before
156 windows are created or the command gets run. Most methods are unsafe 343 windows are created or the command gets run. Most methods are unsafe
157 to call or deliver senseless data, as terminal size and other 344 to call or deliver senseless data, as terminal size and other
158 characteristics have not yet been determined. You can safely query 345 characteristics have not yet been determined. You can safely query
159 and change resources, though. 346 and change resources and options, though. For many purposes the
347 "on_start" hook is a better place.
348
349 on_start $term
350 Called at the very end of initialisation of a new terminal, just
351 before trying to map (display) the toplevel and returning to the
352 mainloop.
353
354 on_destroy $term
355 Called whenever something tries to destroy terminal, when the
356 terminal is still fully functional (not for long, though).
160 357
161 on_reset $term 358 on_reset $term
162 Called after the screen is "reset" for any reason, such as resizing 359 Called after the screen is "reset" for any reason, such as resizing
163 or control sequences. Here is where you can react on changes to 360 or control sequences. Here is where you can react on changes to
164 size-related variables. 361 size-related variables.
165 362
166 on_start $term 363 on_child_start $term, $pid
167 Called at the very end of initialisation of a new terminal, just 364 Called just after the child process has been "fork"ed.
168 before returning to the mainloop. 365
366 on_child_exit $term, $status
367 Called just after the child process has exited. $status is the
368 status from "waitpid".
169 369
170 on_sel_make $term, $eventtime 370 on_sel_make $term, $eventtime
171 Called whenever a selection has been made by the user, but before 371 Called whenever a selection has been made by the user, but before
172 the selection text is copied, so changes to the beginning, end or 372 the selection text is copied, so changes to the beginning, end or
173 type of the selection will be honored. 373 type of the selection will be honored.
186 386
187 on_sel_extend $term 387 on_sel_extend $term
188 Called whenever the user tries to extend the selection (e.g. with a 388 Called whenever the user tries to extend the selection (e.g. with a
189 double click) and is either supposed to return false (normal 389 double click) and is either supposed to return false (normal
190 operation), or should extend the selection itelf and return true to 390 operation), or should extend the selection itelf and return true to
191 suppress the built-in processing. 391 suppress the built-in processing. This can happen multiple times, as
392 long as the callback returns true, it will be called on every
393 further click by the user and is supposed to enlarge the selection
394 more and more, if possible.
192 395
193 See the selection example extension. 396 See the selection example extension.
194 397
195 on_view_change $term, $offset 398 on_view_change $term, $offset
196 Called whenever the view offset changes, i..e the user or program 399 Called whenever the view offset changes, i..e the user or program
250 display code is run after this hook, and takes precedence. 453 display code is run after this hook, and takes precedence.
251 454
252 on_refresh_end $term 455 on_refresh_end $term
253 Called just after the screen gets redrawn. See "on_refresh_begin". 456 Called just after the screen gets redrawn. See "on_refresh_begin".
254 457
255 on_keyboard_command $term, $string 458 on_user_command $term, $string
256 Called whenever the user presses a key combination that has a 459 Called whenever the a user-configured event is being activated (e.g.
257 "perl:string" action bound to it (see description of the keysym 460 via a "perl:string" action bound to a key, see description of the
258 resource in the rxvt(1) manpage). 461 keysym resource in the rxvt(1) manpage).
462
463 The event is simply the action string. This interface is assumed to
464 change slightly in the future.
465
466 on_x_event $term, $event
467 Called on every X event received on the vt window (and possibly
468 other windows). Should only be used as a last resort. Most event
469 structure members are not passed.
259 470
260 on_focus_in $term 471 on_focus_in $term
261 Called whenever the window gets the keyboard focus, before 472 Called whenever the window gets the keyboard focus, before
262 rxvt-unicode does focus in processing. 473 rxvt-unicode does focus in processing.
263 474
264 on_focus_out $term 475 on_focus_out $term
265 Called wheneever the window loses keyboard focus, before 476 Called wheneever the window loses keyboard focus, before
266 rxvt-unicode does focus out processing. 477 rxvt-unicode does focus out processing.
267 478
479 on_configure_notify $term, $event
480 on_property_notify $term, $event
268 on_key_press $term, $event, $keysym, $octets 481 on_key_press $term, $event, $keysym, $octets
269 on_key_release $term, $event, $keysym 482 on_key_release $term, $event, $keysym
270 on_button_press $term, $event 483 on_button_press $term, $event
271 on_button_release $term, $event 484 on_button_release $term, $event
272 on_motion_notify $term, $event 485 on_motion_notify $term, $event
276 terminal If the hook returns true, then the even will be ignored by 489 terminal If the hook returns true, then the even will be ignored by
277 rxvt-unicode. 490 rxvt-unicode.
278 491
279 The event is a hash with most values as named by Xlib (see the 492 The event is a hash with most values as named by Xlib (see the
280 XEvent manpage), with the additional members "row" and "col", which 493 XEvent manpage), with the additional members "row" and "col", which
281 are the row and column under the mouse cursor. 494 are the (real, not screen-based) row and column under the mouse
495 cursor.
282 496
283 "on_key_press" additionally receives the string rxvt-unicode would 497 "on_key_press" additionally receives the string rxvt-unicode would
284 output, if any, in locale-specific encoding. 498 output, if any, in locale-specific encoding.
285 499
286 subwindow. 500 subwindow.
501
502 on_client_message $term, $event
503 on_wm_protocols $term, $event
504 on_wm_delete_window $term, $event
505 Called when various types of ClientMessage events are received (all
506 with format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
287 507
288 Variables in the "urxvt" Package 508 Variables in the "urxvt" Package
289 $urxvt::LIBDIR 509 $urxvt::LIBDIR
290 The rxvt-unicode library directory, where, among other things, the 510 The rxvt-unicode library directory, where, among other things, the
291 perl modules and scripts are stored. 511 perl modules and scripts are stored.
299 519
300 $urxvt::TERM 520 $urxvt::TERM
301 The current terminal. This variable stores the current "urxvt::term" 521 The current terminal. This variable stores the current "urxvt::term"
302 object, whenever a callback/hook is executing. 522 object, whenever a callback/hook is executing.
303 523
304 * 524 @urxvt::TERM_INIT
525 All coderefs in this array will be called as methods of the next
526 newly created "urxvt::term" object (during the "on_init" phase). The
527 array gets cleared before the codereferences that were in it are
528 being executed, so coderefs can push themselves onto it again if
529 they so desire.
530
531 This complements to the perl-eval commandline option, but gets
532 executed first.
533
534 @urxvt::TERM_EXT
535 Works similar to @TERM_INIT, but contains perl package/class names,
536 which get registered as normal extensions after calling the hooks in
537 @TERM_INIT but before other extensions. Gets cleared just like
538 @TERM_INIT.
305 539
306 Functions in the "urxvt" Package 540 Functions in the "urxvt" Package
307 $term = new urxvt [arg...]
308 Creates a new terminal, very similar as if you had started it with
309 "system $binfile, arg...". Croaks (and probably outputs an error
310 message) if the new instance couldn't be created. Returns "undef" if
311 the new instance didn't initialise perl, and the terminal object
312 otherwise. The "init" and "start" hooks will be called during the
313 call.
314
315 urxvt::fatal $errormessage 541 urxvt::fatal $errormessage
316 Fatally aborts execution with the given error message. Avoid at all 542 Fatally aborts execution with the given error message. Avoid at all
317 costs! The only time this is acceptable is when the terminal process 543 costs! The only time this is acceptable is when the terminal process
318 starts up. 544 starts up.
319 545
323 function that calls this function. 549 function that calls this function.
324 550
325 Using this function has the advantage that its output ends up in the 551 Using this function has the advantage that its output ends up in the
326 correct place, e.g. on stderr of the connecting urxvtc client. 552 correct place, e.g. on stderr of the connecting urxvtc client.
327 553
328 $is_safe = urxvt::safe 554 Messages have a size limit of 1023 bytes currently.
329 Returns true when it is safe to do potentially unsafe things, such
330 as evaluating perl code specified by the user. This is true when
331 urxvt was started setuid or setgid.
332 555
333 $time = urxvt::NOW 556 $time = urxvt::NOW
334 Returns the "current time" (as per the event loop). 557 Returns the "current time" (as per the event loop).
335 558
336 urxvt::CurrentTime 559 urxvt::CurrentTime
337 urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, 560 urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask,
338 Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask, 561 Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask,
339 Button5Mask, AnyModifier 562 Button5Mask, AnyModifier
563 urxvt::NoEventMask, KeyPressMask, KeyReleaseMask, ButtonPressMask,
564 ButtonReleaseMask, EnterWindowMask, LeaveWindowMask, PointerMotionMask,
565 PointerMotionHintMask, Button1MotionMask, Button2MotionMask,
566 Button3MotionMask, Button4MotionMask, Button5MotionMask,
567 ButtonMotionMask, KeymapStateMask, ExposureMask, VisibilityChangeMask,
568 StructureNotifyMask, ResizeRedirectMask, SubstructureNotifyMask,
569 SubstructureRedirectMask, FocusChangeMask, PropertyChangeMask,
570 ColormapChangeMask, OwnerGrabButtonMask
571 urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify,
572 EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose,
573 GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify, DestroyNotify,
574 UnmapNotify, MapNotify, MapRequest, ReparentNotify, ConfigureNotify,
575 ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify,
576 CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest,
577 SelectionNotify, ColormapNotify, ClientMessage, MappingNotify
340 Various constants for use in X calls and event processing. 578 Various constants for use in X calls and event processing.
341 579
342 RENDITION 580 RENDITION
343 Rendition bitsets contain information about colour, font, font styles 581 Rendition bitsets contain information about colour, font, font styles
344 and similar information for each screen cell. 582 and similar information for each screen cell.
385 condition variables, but non-blocking condvar use is ok. What this means 623 condition variables, but non-blocking condvar use is ok. What this means
386 is that you cannot use blocking APIs, but the non-blocking variant 624 is that you cannot use blocking APIs, but the non-blocking variant
387 should work. 625 should work.
388 626
389 The "urxvt::term" Class 627 The "urxvt::term" Class
628 $term = new urxvt::term $envhashref, $rxvtname, [arg...]
629 Creates a new terminal, very similar as if you had started it with
630 system "$rxvtname, arg...". $envhashref must be a reference to a
631 %ENV-like hash which defines the environment of the new terminal.
632
633 Croaks (and probably outputs an error message) if the new instance
634 couldn't be created. Returns "undef" if the new instance didn't
635 initialise perl, and the terminal object otherwise. The "init" and
636 "start" hooks will be called during this call.
637
390 $term->destroy 638 $term->destroy
391 Destroy the terminal object (close the window, free resources etc.). 639 Destroy the terminal object (close the window, free resources etc.).
392 Please note that rxvt will not exit as long as any event watchers 640 Please note that rxvt will not exit as long as any event watchers
393 (timers, io watchers) are still active. 641 (timers, io watchers) are still active.
642
643 $term->exec_async ($cmd[, @args])
644 Works like the combination of the "fork"/"exec" builtins, which
645 executes ("starts") programs in the background. This function takes
646 care of setting the user environment before exec'ing the command
647 (e.g. "PATH") and should be preferred over explicit calls to "exec"
648 or "system".
649
650 Returns the pid of the subprocess or "undef" on error.
394 651
395 $isset = $term->option ($optval[, $set]) 652 $isset = $term->option ($optval[, $set])
396 Returns true if the option specified by $optval is enabled, and 653 Returns true if the option specified by $optval is enabled, and
397 optionally change it. All option values are stored by name in the 654 optionally change it. All option values are stored by name in the
398 hash %urxvt::OPTION. Options not enabled in this binary are not in 655 hash %urxvt::OPTION. Options not enabled in this binary are not in
401 Here is a a likely non-exhaustive list of option names, please see 658 Here is a a likely non-exhaustive list of option names, please see
402 the source file /src/optinc.h to see the actual list: 659 the source file /src/optinc.h to see the actual list:
403 660
404 borderLess console cursorBlink cursorUnderline hold iconic insecure 661 borderLess console cursorBlink cursorUnderline hold iconic insecure
405 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 662 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
406 pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating 663 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
407 scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer 664 scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput
408 secondaryScreen secondaryScroll skipBuiltinGlyphs transparent 665 scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs
409 tripleclickwords utmpInhibit visualBell 666 transparent tripleclickwords utmpInhibit visualBell
410 667
411 $value = $term->resource ($name[, $newval]) 668 $value = $term->resource ($name[, $newval])
412 Returns the current resource value associated with a given name and 669 Returns the current resource value associated with a given name and
413 optionally sets a new value. Setting values is most useful in the 670 optionally sets a new value. Setting values is most useful in the
414 "init" hook. Unset resources are returned and accepted as "undef". 671 "init" hook. Unset resources are returned and accepted as "undef".
431 688
432 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 689 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
433 borderLess color cursorBlink cursorUnderline cutchars delete_key 690 borderLess color cursorBlink cursorUnderline cutchars delete_key
434 display_name embed ext_bwidth fade font geometry hold iconName 691 display_name embed ext_bwidth fade font geometry hold iconName
435 imFont imLocale inputMethod insecure int_bwidth intensityStyles 692 imFont imLocale inputMethod insecure int_bwidth intensityStyles
436 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier 693 italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier
437 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2 694 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
438 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 695 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
439 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 696 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
440 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 697 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
441 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 698 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
699 secondaryScreen secondaryScroll selectstyle shade term_name title
442 shade term_name title transparent transparent_all tripleclickwords 700 transient_for transparent transparent_all tripleclickwords utmpInhibit
443 utmpInhibit visualBell 701 visualBell
702
703 $value = $term->x_resource ($pattern)
704 Returns the X-Resource for the given pattern, excluding the program
705 or class name, i.e. "$term->x_resource ("boldFont")" should return
706 the same value as used by this instance of rxvt-unicode. Returns
707 "undef" if no resource with that pattern exists.
708
709 This method should only be called during the "on_start" hook, as
710 there is only one resource database per display, and later
711 invocations might return the wrong resources.
444 712
445 $success = $term->parse_keysym ($keysym_spec, $command_string) 713 $success = $term->parse_keysym ($keysym_spec, $command_string)
446 Adds a keymap translation exactly as specified via a resource. See 714 Adds a keymap translation exactly as specified via a resource. See
447 the "keysym" resource in the rxvt(1) manpage. 715 the "keysym" resource in the rxvt(1) manpage.
448 716
459 ($row, $col) = $term->selection_beg ([$row, $col]) 727 ($row, $col) = $term->selection_beg ([$row, $col])
460 ($row, $col) = $term->selection_end ([$row, $col]) 728 ($row, $col) = $term->selection_end ([$row, $col])
461 Return the current values of the selection mark, begin or end 729 Return the current values of the selection mark, begin or end
462 positions, and optionally set them to new values. 730 positions, and optionally set them to new values.
463 731
732 $term->selection_make ($eventtime[, $rectangular])
733 Tries to make a selection as set by "selection_beg" and
734 "selection_end". If $rectangular is true (default: false), a
735 rectangular selection will be made. This is the prefered function to
736 make a selection.
737
464 $success = $term->selection_grab ($eventtime) 738 $success = $term->selection_grab ($eventtime)
465 Try to request the primary selection from the server (for example, 739 Try to request the primary selection text from the server (for
466 as set by the next method). 740 example, as set by the next method). No visual feedback will be
741 given. This function is mostly useful from within "on_sel_grab"
742 hooks.
467 743
468 $oldtext = $term->selection ([$newtext]) 744 $oldtext = $term->selection ([$newtext])
469 Return the current selection text and optionally replace it by 745 Return the current selection text and optionally replace it by
470 $newtext. 746 $newtext.
471 747
516 $string = $term->locale_decode ($octets) 792 $string = $term->locale_decode ($octets)
517 Convert the given locale-encoded octets into a perl string. 793 Convert the given locale-encoded octets into a perl string.
518 794
519 $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle]) 795 $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
520 XORs the rendition values in the given span with the provided value 796 XORs the rendition values in the given span with the provided value
521 (default: "RS_RVid"). Useful in refresh hooks to provide effects 797 (default: "RS_RVid"), which *MUST NOT* contain font styles. Useful
522 similar to the selection. 798 in refresh hooks to provide effects similar to the selection.
523 799
524 $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, 800 $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[,
525 $rstyle2]]) 801 $rstyle2]])
526 Similar to "scr_xor_span", but xors a rectangle instead. Trailing 802 Similar to "scr_xor_span", but xors a rectangle instead. Trailing
527 whitespace will additionally be xored with the $rstyle2, which 803 whitespace will additionally be xored with the $rstyle2, which
528 defaults to "RS_RVid | RS_Uline", which removes reverse video again 804 defaults to "RS_RVid | RS_Uline", which removes reverse video again
529 and underlines it instead. 805 and underlines it instead. Both styles *MUST NOT* contain font
806 styles.
530 807
531 $term->scr_bell 808 $term->scr_bell
532 Ring the bell! 809 Ring the bell!
533 810
534 $term->scr_add_lines ($string) 811 $term->scr_add_lines ($string)
540 817
541 Normally its not a good idea to use this function, as programs might 818 Normally its not a good idea to use this function, as programs might
542 be confused by changes in cursor position or scrolling. Its useful 819 be confused by changes in cursor position or scrolling. Its useful
543 inside a "on_add_lines" hook, though. 820 inside a "on_add_lines" hook, though.
544 821
822 $term->scr_change_screen ($screen)
823 Switch to given screen - 0 primary, 1 secondary.
824
545 $term->cmd_parse ($octets) 825 $term->cmd_parse ($octets)
546 Similar to "scr_add_lines", but the argument must be in the 826 Similar to "scr_add_lines", but the argument must be in the
547 locale-specific encoding of the terminal and can contain command 827 locale-specific encoding of the terminal and can contain command
548 sequences (escape codes) that will be interpreted. 828 sequences (escape codes) that will be interpreted.
549 829
557 Replaces the event mask of the pty watcher by the given event mask. 837 Replaces the event mask of the pty watcher by the given event mask.
558 Can be used to suppress input and output handling to the pty/tty. 838 Can be used to suppress input and output handling to the pty/tty.
559 See the description of "urxvt::timer->events". Make sure to always 839 See the description of "urxvt::timer->events". Make sure to always
560 restore the previous value. 840 restore the previous value.
561 841
842 $fd = $term->pty_fd
843 Returns the master file descriptor for the pty in use, or -1 if no
844 pty is used.
845
562 $windowid = $term->parent 846 $windowid = $term->parent
563 Return the window id of the toplevel window. 847 Return the window id of the toplevel window.
564 848
565 $windowid = $term->vt 849 $windowid = $term->vt
566 Return the window id of the terminal window. 850 Return the window id of the terminal window.
851
852 $term->vt_emask_add ($x_event_mask)
853 Adds the specified events to the vt event mask. Useful e.g. when you
854 want to receive pointer events all the times:
855
856 $term->vt_emask_add (urxvt::PointerMotionMask);
567 857
568 $window_width = $term->width 858 $window_width = $term->width
569 $window_height = $term->height 859 $window_height = $term->height
570 $font_width = $term->fwidth 860 $font_width = $term->fwidth
571 $font_height = $term->fheight 861 $font_height = $term->fheight
574 $terminal_columns = $term->ncol 864 $terminal_columns = $term->ncol
575 $has_focus = $term->focus 865 $has_focus = $term->focus
576 $is_mapped = $term->mapped 866 $is_mapped = $term->mapped
577 $max_scrollback = $term->saveLines 867 $max_scrollback = $term->saveLines
578 $nrow_plus_saveLines = $term->total_rows 868 $nrow_plus_saveLines = $term->total_rows
579 $lines_in_scrollback = $term->nsaved 869 $topmost_scrollback_row = $term->top_row
580 Return various integers describing terminal characteristics. 870 Return various integers describing terminal characteristics.
871
872 $x_display = $term->display_id
873 Return the DISPLAY used by rxvt-unicode.
581 874
582 $lc_ctype = $term->locale 875 $lc_ctype = $term->locale
583 Returns the LC_CTYPE category string used by this rxvt-unicode. 876 Returns the LC_CTYPE category string used by this rxvt-unicode.
584 877
585 $x_display = $term->display_id 878 $env = $term->env
586 Return the DISPLAY used by rxvt-unicode. 879 Returns a copy of the environment in effect for the terminal as a
880 hashref similar to "\%ENV".
587 881
588 $modifiermask = $term->ModLevel3Mask 882 $modifiermask = $term->ModLevel3Mask
589 $modifiermask = $term->ModMetaMask 883 $modifiermask = $term->ModMetaMask
590 $modifiermask = $term->ModNumLockMask 884 $modifiermask = $term->ModNumLockMask
591 Return the modifier masks corresponding to the "ISO Level 3 Shift" 885 Return the modifier masks corresponding to the "ISO Level 3 Shift"
592 (often AltGr), the meta key (often Alt) and the num lock key, if 886 (often AltGr), the meta key (often Alt) and the num lock key, if
593 applicable. 887 applicable.
594 888
889 $screen = $term->current_screen
890 Returns the currently displayed screen (0 primary, 1 secondary).
891
892 $cursor_is_hidden = $term->hidden_cursor
893 Returns wether the cursor is currently hidden or not.
894
595 $view_start = $term->view_start ([$newvalue]) 895 $view_start = $term->view_start ([$newvalue])
596 Returns the negative row number of the topmost line. Minimum value 896 Returns the row number of the topmost displayed line. Maximum value
597 is 0, which displays the normal terminal contents. Larger values 897 is 0, which displays the normal terminal contents. Lower values
598 scroll this many lines into the scrollback buffer. 898 scroll this many lines into the scrollback buffer.
599 899
600 $term->want_refresh 900 $term->want_refresh
601 Requests a screen refresh. At the next opportunity, rxvt-unicode 901 Requests a screen refresh. At the next opportunity, rxvt-unicode
602 will compare the on-screen display with its stored representation. 902 will compare the on-screen display with its stored representation.
615 line, starting at column $start_col (default 0), which is useful to 915 line, starting at column $start_col (default 0), which is useful to
616 replace only parts of a line. The font index in the rendition will 916 replace only parts of a line. The font index in the rendition will
617 automatically be updated. 917 automatically be updated.
618 918
619 $text is in a special encoding: tabs and wide characters that use 919 $text is in a special encoding: tabs and wide characters that use
620 more than one cell when displayed are padded with urxvt::NOCHAR 920 more than one cell when displayed are padded with $urxvt::NOCHAR
621 characters ("chr 65535"). Characters with combining characters and 921 (chr 65535) characters. Characters with combining characters and
622 other characters that do not fit into the normal tetx encoding will 922 other characters that do not fit into the normal tetx encoding will
623 be replaced with characters in the private use area. 923 be replaced with characters in the private use area.
624 924
625 You have to obey this encoding when changing text. The advantage is 925 You have to obey this encoding when changing text. The advantage is
626 that "substr" and similar functions work on screen cells and not on 926 that "substr" and similar functions work on screen cells and not on
670 Return the row number of the first/last row of the line, 970 Return the row number of the first/last row of the line,
671 respectively. 971 respectively.
672 972
673 $offset = $line->offset_of ($row, $col) 973 $offset = $line->offset_of ($row, $col)
674 Returns the character offset of the given row|col pair within 974 Returns the character offset of the given row|col pair within
675 the logical line. 975 the logical line. Works for rows outside the line, too, and
976 returns corresponding offsets outside the string.
676 977
677 ($row, $col) = $line->coord_of ($offset) 978 ($row, $col) = $line->coord_of ($offset)
678 Translates a string offset into terminal coordinates again. 979 Translates a string offset into terminal coordinates again.
679 980
680 $text = $term->special_encode $string 981 $text = $term->special_encode $string
706 $term->ungrab 1007 $term->ungrab
707 Calls XUngrab for the most recent grab. Is called automatically on 1008 Calls XUngrab for the most recent grab. Is called automatically on
708 evaluation errors, as it is better to lose the grab in the error 1009 evaluation errors, as it is better to lose the grab in the error
709 case as the session. 1010 case as the session.
710 1011
1012 $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
1013 $atom_name = $term->XGetAtomName ($atom)
1014 @atoms = $term->XListProperties ($window)
1015 ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
1016 $term->XChangeWindowProperty ($window, $property, $type, $format,
1017 $octets)
1018 $term->XDeleteProperty ($window, $property)
1019 $window = $term->DefaultRootWindow
1020 $term->XReparentWindow ($window, $parent, [$x, $y])
1021 $term->XMapWindow ($window)
1022 $term->XUnmapWindow ($window)
1023 $term->XMoveResizeWindow ($window, $x, $y, $width, $height)
1024 ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x,
1025 $y)
1026 $term->XChangeInput ($window, $add_events[, $del_events])
1027 Various X or X-related functions. The $term object only serves as
1028 the source of the display, otherwise those functions map
1029 more-or-less directory onto the X functions of the same name.
1030
711 The "urxvt::popup" Class 1031 The "urxvt::popup" Class
712 $popup->add_title ($title) 1032 $popup->add_title ($title)
713 Adds a non-clickable title to the popup. 1033 Adds a non-clickable title to the popup.
714 1034
715 $popup->add_separator ([$sepchr]) 1035 $popup->add_separator ([$sepchr])
727 1047
728 $popup->show 1048 $popup->show
729 Displays the popup (which is initially hidden). 1049 Displays the popup (which is initially hidden).
730 1050
731 The "urxvt::timer" Class 1051 The "urxvt::timer" Class
732 This class implements timer watchers/events. Time is represented as 1052 This class implements timer watchers/events. Time is represented as a
733 a fractional number of seconds since the epoch. Example: 1053 fractional number of seconds since the epoch. Example:
734 1054
735 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0); 1055 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
736 $term->{timer} = urxvt::timer 1056 $term->{timer} = urxvt::timer
737 ->new 1057 ->new
738 ->interval (1) 1058 ->interval (1)
739 ->cb (sub { 1059 ->cb (sub {
740 $term->{overlay}->set (0, 0, 1060 $term->{overlay}->set (0, 0,
741 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]); 1061 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
742 }); 1062 });
743 1063
744 $timer = new urxvt::timer 1064 $timer = new urxvt::timer
745 Create a new timer object in started state. It is scheduled to 1065 Create a new timer object in started state. It is scheduled to fire
746 fire immediately. 1066 immediately.
747 1067
748 $timer = $timer->cb (sub { my ($timer) = @_; ... }) 1068 $timer = $timer->cb (sub { my ($timer) = @_; ... })
749 Set the callback to be called when the timer triggers. 1069 Set the callback to be called when the timer triggers.
750 1070
751 $tstamp = $timer->at 1071 $tstamp = $timer->at
752 Return the time this watcher will fire next. 1072 Return the time this watcher will fire next.
753 1073
754 $timer = $timer->set ($tstamp) 1074 $timer = $timer->set ($tstamp)
755 Set the time the event is generated to $tstamp. 1075 Set the time the event is generated to $tstamp.
756 1076
757 $timer = $timer->interval ($interval) 1077 $timer = $timer->interval ($interval)
758 Normally (and when $interval is 0), the timer will automatically 1078 Normally (and when $interval is 0), the timer will automatically
759 stop after it has fired once. If $interval is non-zero, then the 1079 stop after it has fired once. If $interval is non-zero, then the
760 timer is automatically rescheduled at the given intervals. 1080 timer is automatically rescheduled at the given intervals.
761 1081
762 $timer = $timer->start 1082 $timer = $timer->start
763 Start the timer. 1083 Start the timer.
764 1084
765 $timer = $timer->start ($tstamp) 1085 $timer = $timer->start ($tstamp)
766 Set the event trigger time to $tstamp and start the timer. 1086 Set the event trigger time to $tstamp and start the timer.
767 1087
1088 $timer = $timer->after ($delay)
1089 Like "start", but sets the expiry timer to c<urxvt::NOW + $delay>.
1090
768 $timer = $timer->stop 1091 $timer = $timer->stop
769 Stop the timer. 1092 Stop the timer.
770 1093
771 The "urxvt::iow" Class 1094 The "urxvt::iow" Class
772 This class implements io watchers/events. Example: 1095 This class implements io watchers/events. Example:
773 1096
774 $term->{socket} = ... 1097 $term->{socket} = ...
775 $term->{iow} = urxvt::iow 1098 $term->{iow} = urxvt::iow
1099 ->new
1100 ->fd (fileno $term->{socket})
1101 ->events (urxvt::EVENT_READ)
1102 ->start
1103 ->cb (sub {
1104 my ($iow, $revents) = @_;
1105 # $revents must be 1 here, no need to check
1106 sysread $term->{socket}, my $buf, 8192
1107 or end-of-file;
1108 });
1109
1110 $iow = new urxvt::iow
1111 Create a new io watcher object in stopped state.
1112
1113 $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
1114 Set the callback to be called when io events are triggered.
1115 $reventmask is a bitset as described in the "events" method.
1116
1117 $iow = $iow->fd ($fd)
1118 Set the filedescriptor (not handle) to watch.
1119
1120 $iow = $iow->events ($eventmask)
1121 Set the event mask to watch. The only allowed values are
1122 "urxvt::EVENT_READ" and "urxvt::EVENT_WRITE", which might be ORed
1123 together, or "urxvt::EVENT_NONE".
1124
1125 $iow = $iow->start
1126 Start watching for requested events on the given handle.
1127
1128 $iow = $iow->stop
1129 Stop watching for events on the given filehandle.
1130
1131 The "urxvt::iw" Class
1132 This class implements idle watchers, that get called automatically when
1133 the process is idle. They should return as fast as possible, after doing
1134 some useful work.
1135
1136 $iw = new urxvt::iw
1137 Create a new idle watcher object in stopped state.
1138
1139 $iw = $iw->cb (sub { my ($iw) = @_; ... })
1140 Set the callback to be called when the watcher triggers.
1141
1142 $timer = $timer->start
1143 Start the watcher.
1144
1145 $timer = $timer->stop
1146 Stop the watcher.
1147
1148 The "urxvt::pw" Class
1149 This class implements process watchers. They create an event whenever a
1150 process exits, after which they stop automatically.
1151
1152 my $pid = fork;
1153 ...
1154 $term->{pw} = urxvt::pw
776 ->new 1155 ->new
777 ->fd (fileno $term->{socket})
778 ->events (urxvt::EVENT_READ)
779 ->start 1156 ->start ($pid)
780 ->cb (sub { 1157 ->cb (sub {
781 my ($iow, $revents) = @_; 1158 my ($pw, $exit_status) = @_;
782 # $revents must be 1 here, no need to check
783 sysread $term->{socket}, my $buf, 8192
784 or end-of-file;
785 }); 1159 ...
1160 });
786 1161
787 $iow = new urxvt::iow 1162 $pw = new urxvt::pw
788 Create a new io watcher object in stopped state. 1163 Create a new process watcher in stopped state.
789 1164
790 $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... }) 1165 $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
791 Set the callback to be called when io events are triggered. 1166 Set the callback to be called when the timer triggers.
792 $reventmask is a bitset as described in the "events" method.
793 1167
794 $iow = $iow->fd ($fd) 1168 $pw = $timer->start ($pid)
795 Set the filedescriptor (not handle) to watch. 1169 Tells the wqtcher to start watching for process $pid.
796 1170
797 $iow = $iow->events ($eventmask)
798 Set the event mask to watch. The only allowed values are
799 "urxvt::EVENT_READ" and "urxvt::EVENT_WRITE", which might be
800 ORed together, or "urxvt::EVENT_NONE".
801
802 $iow = $iow->start
803 Start watching for requested events on the given handle.
804
805 $iow = $iow->stop 1171 $pw = $pw->stop
806 Stop watching for events on the given filehandle. 1172 Stop the watcher.
807 1173
808ENVIRONMENT 1174ENVIRONMENT
809 URXVT_PERL_VERBOSITY 1175 URXVT_PERL_VERBOSITY
810 This variable controls the verbosity level of the perl extension. 1176 This variable controls the verbosity level of the perl extension. Higher
811 Higher numbers indicate more verbose output. 1177 numbers indicate more verbose output.
812 1178
813 == 0 - fatal messages 1179 == 0 - fatal messages
814 >= 3 - script loading and management 1180 >= 3 - script loading and management
815 >=10 - all events received 1181 >=10 - all called hooks
1182 >=11 - hook reutrn values
816 1183
817AUTHOR 1184AUTHOR
818 Marc Lehmann <pcg@goof.com> 1185 Marc Lehmann <pcg@goof.com>
819 http://software.schmorp.de/pkg/rxvt-unicode 1186 http://software.schmorp.de/pkg/rxvt-unicode
820 1187

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines