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.26 by root, Fri Jan 13 01:09:37 2006 UTC vs.
Revision 1.39 by root, Mon Feb 6 05:55:33 2006 UTC

… …
28 can find them in /opt/rxvt/lib/urxvt/perl/. 28 can find them in /opt/rxvt/lib/urxvt/perl/.
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
34 Or by adding them to the resource for extensions loaded by default:
35
36 URxvt.perl-ext-common: default,automove-background,selection-autotransform
33 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 and 40 intelligent when the user extends selections (double-click and
37 further clicks). Right now, it tries to select words, urls and 41 further clicks). Right now, it tries to select words, urls and
… …
54 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
55 matches everything between two vertical bars: 59 matches everything between two vertical bars:
56 60
57 URxvt.selection.pattern-0: \\|([^|]+)\\| 61 URxvt.selection.pattern-0: \\|([^|]+)\\|
58 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
59 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
60 interesting uses, such as parsing a line from beginning to end. 71 interesting uses, such as parsing a line from beginning to end.
61 72
62 This extension also offers the following bindable keyboard command: 73 This extension also offers following bindable keyboard commands:
63 74
64 rot13 75 rot13
65 Rot-13 the selection when activated. Used via keyboard trigger: 76 Rot-13 the selection when activated. Used via keyboard trigger:
66 77
67 URxvt.keysym.C-M-r: perl:selection:rot13 78 URxvt.keysym.C-M-r: perl:selection:rot13
… …
71 options at runtime. 82 options at runtime.
72 83
73 selection-popup (enabled by default) 84 selection-popup (enabled by default)
74 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
75 selection text into various other formats/action (such as uri 86 selection text into various other formats/action (such as uri
76 unescaping, perl evalution, web-browser starting etc.), depending on 87 unescaping, perl evaluation, web-browser starting etc.), depending
77 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 };
78 109
79 searchable-scrollback<hotkey> (enabled by default) 110 searchable-scrollback<hotkey> (enabled by default)
80 Adds regex search functionality to the scrollback buffer, triggered 111 Adds regex search functionality to the scrollback buffer, triggered
81 by a hotkey (default: "M-s"). While in search mode, normal terminal 112 by a hotkey (default: "M-s"). While in search mode, normal terminal
82 input/output is suspended and a regex is displayed at the bottom of 113 input/output is suspended and a regex is displayed at the bottom of
… …
88 "End" jumps to the bottom. "Escape" leaves search mode and returns 119 "End" jumps to the bottom. "Escape" leaves search mode and returns
89 to the point where search was started, while "Enter" or "Return" 120 to the point where search was started, while "Enter" or "Return"
90 stay at the current position and additionally stores the first match 121 stay at the current position and additionally stores the first match
91 in the current line into the primary selection. 122 in the current line into the primary selection.
92 123
124 readline (enabled by default)
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
93 selection-autotransform 142 selection-autotransform
94 This selection allows you to do automatic transforms on a selection 143 This selection allows you to do automatic transforms on a selection
95 whenever a selection is made. 144 whenever a selection is made.
96 145
97 It works by specifying perl snippets (most useful is a single "s///" 146 It works by specifying perl snippets (most useful is a single "s///"
… …
103 152
104 For example, the following will transform selections of the form 153 For example, the following will transform selections of the form
105 "filename:number", often seen in compiler messages, into "vi 154 "filename:number", often seen in compiler messages, into "vi
106 +$filename $word": 155 +$filename $word":
107 156
108 URxvt.selection-autotransform.0: s/^(\\S+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/ 157 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
109 158
110 And this example matches the same,but replaces it with vi-commands 159 And this example matches the same,but replaces it with vi-commands
111 you can paste directly into your (vi :) editor: 160 you can paste directly into your (vi :) editor:
112 161
113 URxvt.selection-autotransform.0: s/^(S+):(d+):?$/\\x1b:e \\Q$1\\E\\x0d:$2\\x0d/ 162 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/
114 163
115 Of course, this can be modified to suit your needs and your editor 164 Of course, this can be modified to suit your needs and your editor
116 :) 165 :)
117 166
118 To expand the example above to typical perl error messages ("XXX at 167 To expand the example above to typical perl error messages ("XXX at
119 FILENAME line YYY."), you need a slightly more elaborate solution: 168 FILENAME line YYY."), you need a slightly more elaborate solution:
120 169
121 URxvt.selection.pattern-0: ( at .*? line \\d+\\.) 170 URxvt.selection.pattern-0: ( at .*? line \\d+[,.])
122 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)\\.$/\x1b:e \\Q$1\E\\x0d:$2\\x0d/ 171 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/
123 172
124 The first line tells the selection code to treat the unchanging part 173 The first line tells the selection code to treat the unchanging part
125 of every error message as a selection pattern, and the second line 174 of every error message as a selection pattern, and the second line
126 transforms the message into vi commands to load the file. 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.
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.
127 198
128 mark-urls 199 mark-urls
129 Uses per-line display filtering ("on_line_update") to underline urls 200 Uses per-line display filtering ("on_line_update") to underline urls
130 and make them clickable. When middle-clicked, the program specified 201 and make them clickable. When middle-clicked, the program specified
131 in the resource "urlLauncher" (default "x-www-browser") will be 202 in the resource "urlLauncher" (default "x-www-browser") will be
132 started with the URL as first argument. 203 started with the URL as first argument.
133 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
216 automove-background
217 This is basically a one-line extension that dynamically changes the
218 background pixmap offset to the window position, in effect creating
219 the same effect as pseudo transparency with a custom pixmap. No
220 scaling is supported in this mode. Exmaple:
221
222 rxvt -pixmap background.xpm -pe automove-background
223
134 block-graphics-to-ascii 224 block-graphics-to-ascii
135 A not very useful example of filtering all text output to the 225 A not very useful example of filtering all text output to the
136 terminal, by replacing all line-drawing characters (U+2500 .. 226 terminal, by replacing all line-drawing characters (U+2500 ..
137 U+259F) by a similar-looking ascii character. 227 U+259F) by a similar-looking ascii character.
138 228
139 digital-clock 229 digital-clock
140 Displays a digital clock using the built-in overlay. 230 Displays a digital clock using the built-in overlay.
231
232 remote-clipboard
233 Somewhat of a misnomer, this extension adds two menu entries to the
234 selection popup that allows one ti run external commands to store
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'
250
251 selection-pastebin
252 This is a little rarely useful extension that Uploads the selection
253 as textfile to a remote site (or does other things). (The
254 implementation is not currently secure for use in a multiuser
255 environment as it writes to /tmp directly.).
256
257 It listens to the "selection-pastebin:remote-pastebin" keyboard
258 command, i.e.
259
260 URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin
261
262 Pressing this combination runs a command with "%" replaced by the
263 name of the textfile. This command can be set via a resource:
264
265 URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
266
267 And the default is likely not useful to anybody but the few people
268 around here :)
269
270 The name of the textfile is the hex encoded md5 sum of the
271 selection, so the same content should lead to the same filename.
272
273 After a successful upload the selection will be replaced by the text
274 given in the "selection-pastebin-url" resource (again, the % is the
275 placeholder for the filename):
276
277 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
141 278
142 example-refresh-hooks 279 example-refresh-hooks
143 Displays a very simple digital clock in the upper right corner of 280 Displays a very simple digital clock in the upper right corner of
144 the window. Illustrates overwriting the refresh callbacks to create 281 the window. Illustrates overwriting the refresh callbacks to create
145 your own overlays or changes. 282 your own overlays or changes.
… …
204 be called whenever the relevant event happens. 341 be called whenever the relevant event happens.
205 342
206 The first argument passed to them is an extension oject as described in 343 The first argument passed to them is an extension oject as described in
207 the in the "Extension Objects" section. 344 the in the "Extension Objects" section.
208 345
209 All of these hooks must return a boolean value. If it is true, then the 346 All of these hooks must return a boolean value. If any of the called
210 event counts as being *consumed*, and the invocation of other hooks is 347 hooks returns true, then the event counts as being *consumed*, and the
211 skipped, and the relevant action might not be carried out by the C++ 348 relevant action might not be carried out by the C++ code.
212 code.
213 349
214 *When in doubt, return a false value (preferably "()").* 350 *When in doubt, return a false value (preferably "()").*
215 351
216 on_init $term 352 on_init $term
217 Called after a new terminal object has been initialized, but before 353 Called after a new terminal object has been initialized, but before
218 windows are created or the command gets run. Most methods are unsafe 354 windows are created or the command gets run. Most methods are unsafe
219 to call or deliver senseless data, as terminal size and other 355 to call or deliver senseless data, as terminal size and other
220 characteristics have not yet been determined. You can safely query 356 characteristics have not yet been determined. You can safely query
221 and change resources, though. 357 and change resources and options, though. For many purposes the
358 "on_start" hook is a better place.
359
360 on_start $term
361 Called at the very end of initialisation of a new terminal, just
362 before trying to map (display) the toplevel and returning to the
363 mainloop.
364
365 on_destroy $term
366 Called whenever something tries to destroy terminal, when the
367 terminal is still fully functional (not for long, though).
222 368
223 on_reset $term 369 on_reset $term
224 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
225 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
226 size-related variables. 372 size-related variables.
227 373
228 on_start $term 374 on_child_start $term, $pid
229 Called at the very end of initialisation of a new terminal, just 375 Called just after the child process has been "fork"ed.
230 before returning to the mainloop. 376
377 on_child_exit $term, $status
378 Called just after the child process has exited. $status is the
379 status from "waitpid".
231 380
232 on_sel_make $term, $eventtime 381 on_sel_make $term, $eventtime
233 Called whenever a selection has been made by the user, but before 382 Called whenever a selection has been made by the user, but before
234 the selection text is copied, so changes to the beginning, end or 383 the selection text is copied, so changes to the beginning, end or
235 type of the selection will be honored. 384 type of the selection will be honored.
… …
315 display code is run after this hook, and takes precedence. 464 display code is run after this hook, and takes precedence.
316 465
317 on_refresh_end $term 466 on_refresh_end $term
318 Called just after the screen gets redrawn. See "on_refresh_begin". 467 Called just after the screen gets redrawn. See "on_refresh_begin".
319 468
320 on_keyboard_command $term, $string 469 on_user_command $term, $string
321 Called whenever the user presses a key combination that has a 470 Called whenever the a user-configured event is being activated (e.g.
322 "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
323 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.
476
477 on_x_event $term, $event
478 Called on every X event received on the vt window (and possibly
479 other windows). Should only be used as a last resort. Most event
480 structure members are not passed.
324 481
325 on_focus_in $term 482 on_focus_in $term
326 Called whenever the window gets the keyboard focus, before 483 Called whenever the window gets the keyboard focus, before
327 rxvt-unicode does focus in processing. 484 rxvt-unicode does focus in processing.
328 485
329 on_focus_out $term 486 on_focus_out $term
330 Called wheneever the window loses keyboard focus, before 487 Called wheneever the window loses keyboard focus, before
331 rxvt-unicode does focus out processing. 488 rxvt-unicode does focus out processing.
332 489
490 on_configure_notify $term, $event
491 on_property_notify $term, $event
333 on_key_press $term, $event, $keysym, $octets 492 on_key_press $term, $event, $keysym, $octets
334 on_key_release $term, $event, $keysym 493 on_key_release $term, $event, $keysym
335 on_button_press $term, $event 494 on_button_press $term, $event
336 on_button_release $term, $event 495 on_button_release $term, $event
337 on_motion_notify $term, $event 496 on_motion_notify $term, $event
… …
341 terminal If the hook returns true, then the even will be ignored by 500 terminal If the hook returns true, then the even will be ignored by
342 rxvt-unicode. 501 rxvt-unicode.
343 502
344 The event is a hash with most values as named by Xlib (see the 503 The event is a hash with most values as named by Xlib (see the
345 XEvent manpage), with the additional members "row" and "col", which 504 XEvent manpage), with the additional members "row" and "col", which
346 are the row and column under the mouse cursor. 505 are the (real, not screen-based) row and column under the mouse
506 cursor.
347 507
348 "on_key_press" additionally receives the string rxvt-unicode would 508 "on_key_press" additionally receives the string rxvt-unicode would
349 output, if any, in locale-specific encoding. 509 output, if any, in locale-specific encoding.
350 510
351 subwindow. 511 subwindow.
512
513 on_client_message $term, $event
514 on_wm_protocols $term, $event
515 on_wm_delete_window $term, $event
516 Called when various types of ClientMessage events are received (all
517 with format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
352 518
353 Variables in the "urxvt" Package 519 Variables in the "urxvt" Package
354 $urxvt::LIBDIR 520 $urxvt::LIBDIR
355 The rxvt-unicode library directory, where, among other things, the 521 The rxvt-unicode library directory, where, among other things, the
356 perl modules and scripts are stored. 522 perl modules and scripts are stored.
… …
363 The basename of the installed binaries, usually "urxvt". 529 The basename of the installed binaries, usually "urxvt".
364 530
365 $urxvt::TERM 531 $urxvt::TERM
366 The current terminal. This variable stores the current "urxvt::term" 532 The current terminal. This variable stores the current "urxvt::term"
367 object, whenever a callback/hook is executing. 533 object, whenever a callback/hook is executing.
534
535 @urxvt::TERM_INIT
536 All coderefs in this array will be called as methods of the next
537 newly created "urxvt::term" object (during the "on_init" phase). The
538 array gets cleared before the codereferences that were in it are
539 being executed, so coderefs can push themselves onto it again if
540 they so desire.
541
542 This complements to the perl-eval commandline option, but gets
543 executed first.
544
545 @urxvt::TERM_EXT
546 Works similar to @TERM_INIT, but contains perl package/class names,
547 which get registered as normal extensions after calling the hooks in
548 @TERM_INIT but before other extensions. Gets cleared just like
549 @TERM_INIT.
368 550
369 Functions in the "urxvt" Package 551 Functions in the "urxvt" Package
370 urxvt::fatal $errormessage 552 urxvt::fatal $errormessage
371 Fatally aborts execution with the given error message. Avoid at all 553 Fatally aborts execution with the given error message. Avoid at all
372 costs! The only time this is acceptable is when the terminal process 554 costs! The only time this is acceptable is when the terminal process
… …
380 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
381 correct place, e.g. on stderr of the connecting urxvtc client. 563 correct place, e.g. on stderr of the connecting urxvtc client.
382 564
383 Messages have a size limit of 1023 bytes currently. 565 Messages have a size limit of 1023 bytes currently.
384 566
385 $is_safe = urxvt::safe 567 @terms = urxvt::termlist
386 Returns true when it is safe to do potentially unsafe things, such 568 Returns all urxvt::term objects that exist in this process,
387 as evaluating perl code specified by the user. This is true when 569 regardless of wether they are started, being destroyed etc., so be
388 urxvt was started setuid or setgid. 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).
389 573
390 $time = urxvt::NOW 574 $time = urxvt::NOW
391 Returns the "current time" (as per the event loop). 575 Returns the "current time" (as per the event loop).
392 576
393 urxvt::CurrentTime 577 urxvt::CurrentTime
394 urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, 578 urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask,
395 Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask, 579 Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask,
396 Button5Mask, AnyModifier 580 Button5Mask, AnyModifier
581 urxvt::NoEventMask, KeyPressMask, KeyReleaseMask, ButtonPressMask,
582 ButtonReleaseMask, EnterWindowMask, LeaveWindowMask, PointerMotionMask,
583 PointerMotionHintMask, Button1MotionMask, Button2MotionMask,
584 Button3MotionMask, Button4MotionMask, Button5MotionMask,
585 ButtonMotionMask, KeymapStateMask, ExposureMask, VisibilityChangeMask,
586 StructureNotifyMask, ResizeRedirectMask, SubstructureNotifyMask,
587 SubstructureRedirectMask, FocusChangeMask, PropertyChangeMask,
588 ColormapChangeMask, OwnerGrabButtonMask
589 urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify,
590 EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose,
591 GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify, DestroyNotify,
592 UnmapNotify, MapNotify, MapRequest, ReparentNotify, ConfigureNotify,
593 ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify,
594 CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest,
595 SelectionNotify, ColormapNotify, ClientMessage, MappingNotify
397 Various constants for use in X calls and event processing. 596 Various constants for use in X calls and event processing.
398 597
399 RENDITION 598 RENDITION
400 Rendition bitsets contain information about colour, font, font styles 599 Rendition bitsets contain information about colour, font, font styles
401 and similar information for each screen cell. 600 and similar information for each screen cell.
… …
422 $background = urxvt::GET_BASEBG $rend 621 $background = urxvt::GET_BASEBG $rend
423 Return the foreground/background colour index, respectively. 622 Return the foreground/background colour index, respectively.
424 623
425 $rend = urxvt::SET_FGCOLOR $rend, $new_colour 624 $rend = urxvt::SET_FGCOLOR $rend, $new_colour
426 $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
427 Replace the foreground/background colour in the rendition mask with 627 Replace the foreground/background colour in the rendition mask with
428 the specified one. 628 the specified one.
429 629
430 $value = urxvt::GET_CUSTOM $rend 630 $value = urxvt::GET_CUSTOM $rend
431 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
… …
450 %ENV-like hash which defines the environment of the new terminal. 650 %ENV-like hash which defines the environment of the new terminal.
451 651
452 Croaks (and probably outputs an error message) if the new instance 652 Croaks (and probably outputs an error message) if the new instance
453 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
454 initialise perl, and the terminal object otherwise. The "init" and 654 initialise perl, and the terminal object otherwise. The "init" and
455 "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).
456 657
457 $term->destroy 658 $term->destroy
458 Destroy the terminal object (close the window, free resources etc.). 659 Destroy the terminal object (close the window, free resources etc.).
459 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
460 (timers, io watchers) are still active. 661 (timers, io watchers) are still active.
662
663 $term->exec_async ($cmd[, @args])
664 Works like the combination of the "fork"/"exec" builtins, which
665 executes ("starts") programs in the background. This function takes
666 care of setting the user environment before exec'ing the command
667 (e.g. "PATH") and should be preferred over explicit calls to "exec"
668 or "system".
669
670 Returns the pid of the subprocess or "undef" on error.
461 671
462 $isset = $term->option ($optval[, $set]) 672 $isset = $term->option ($optval[, $set])
463 Returns true if the option specified by $optval is enabled, and 673 Returns true if the option specified by $optval is enabled, and
464 optionally change it. All option values are stored by name in the 674 optionally change it. All option values are stored by name in the
465 hash %urxvt::OPTION. Options not enabled in this binary are not in 675 hash %urxvt::OPTION. Options not enabled in this binary are not in
… …
468 Here is a a likely non-exhaustive list of option names, please see 678 Here is a a likely non-exhaustive list of option names, please see
469 the source file /src/optinc.h to see the actual list: 679 the source file /src/optinc.h to see the actual list:
470 680
471 borderLess console cursorBlink cursorUnderline hold iconic insecure 681 borderLess console cursorBlink cursorUnderline hold iconic insecure
472 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 682 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
473 pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating 683 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
474 scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer 684 scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput
475 secondaryScreen secondaryScroll skipBuiltinGlyphs transparent 685 scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs
476 tripleclickwords utmpInhibit visualBell 686 transparent tripleclickwords utmpInhibit visualBell
477 687
478 $value = $term->resource ($name[, $newval]) 688 $value = $term->resource ($name[, $newval])
479 Returns the current resource value associated with a given name and 689 Returns the current resource value associated with a given name and
480 optionally sets a new value. Setting values is most useful in the 690 optionally sets a new value. Setting values is most useful in the
481 "init" hook. Unset resources are returned and accepted as "undef". 691 "init" hook. Unset resources are returned and accepted as "undef".
… …
498 708
499 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 709 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
500 borderLess color cursorBlink cursorUnderline cutchars delete_key 710 borderLess color cursorBlink cursorUnderline cutchars delete_key
501 display_name embed ext_bwidth fade font geometry hold iconName 711 display_name embed ext_bwidth fade font geometry hold iconName
502 imFont imLocale inputMethod insecure int_bwidth intensityStyles 712 imFont imLocale inputMethod insecure int_bwidth intensityStyles
503 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier 713 italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier
504 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2 714 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
505 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 715 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
506 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 716 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
507 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 717 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
508 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 718 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
719 secondaryScreen secondaryScroll selectstyle shade term_name title
509 shade term_name title transparent transparent_all tripleclickwords 720 transient_for transparent transparent_all tripleclickwords utmpInhibit
510 utmpInhibit visualBell 721 visualBell
511 722
512 $value = $term->x_resource ($pattern) 723 $value = $term->x_resource ($pattern)
513 Returns the X-Resource for the given pattern, excluding the program 724 Returns the X-Resource for the given pattern, excluding the program
514 or class name, i.e. "$term->x_resource ("boldFont")" should return 725 or class name, i.e. "$term->x_resource ("boldFont")" should return
515 the same value as used by this instance of rxvt-unicode. Returns 726 the same value as used by this instance of rxvt-unicode. Returns
… …
626 837
627 Normally its not a good idea to use this function, as programs might 838 Normally its not a good idea to use this function, as programs might
628 be confused by changes in cursor position or scrolling. Its useful 839 be confused by changes in cursor position or scrolling. Its useful
629 inside a "on_add_lines" hook, though. 840 inside a "on_add_lines" hook, though.
630 841
842 $term->scr_change_screen ($screen)
843 Switch to given screen - 0 primary, 1 secondary.
844
631 $term->cmd_parse ($octets) 845 $term->cmd_parse ($octets)
632 Similar to "scr_add_lines", but the argument must be in the 846 Similar to "scr_add_lines", but the argument must be in the
633 locale-specific encoding of the terminal and can contain command 847 locale-specific encoding of the terminal and can contain command
634 sequences (escape codes) that will be interpreted. 848 sequences (escape codes) that will be interpreted.
635 849
… …
643 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.
644 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.
645 See the description of "urxvt::timer->events". Make sure to always 859 See the description of "urxvt::timer->events". Make sure to always
646 restore the previous value. 860 restore the previous value.
647 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
648 $windowid = $term->parent 866 $windowid = $term->parent
649 Return the window id of the toplevel window. 867 Return the window id of the toplevel window.
650 868
651 $windowid = $term->vt 869 $windowid = $term->vt
652 Return the window id of the terminal window. 870 Return the window id of the terminal window.
871
872 $term->vt_emask_add ($x_event_mask)
873 Adds the specified events to the vt event mask. Useful e.g. when you
874 want to receive pointer events all the times:
875
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.
653 883
654 $window_width = $term->width 884 $window_width = $term->width
655 $window_height = $term->height 885 $window_height = $term->height
656 $font_width = $term->fwidth 886 $font_width = $term->fwidth
657 $font_height = $term->fheight 887 $font_height = $term->fheight
… …
660 $terminal_columns = $term->ncol 890 $terminal_columns = $term->ncol
661 $has_focus = $term->focus 891 $has_focus = $term->focus
662 $is_mapped = $term->mapped 892 $is_mapped = $term->mapped
663 $max_scrollback = $term->saveLines 893 $max_scrollback = $term->saveLines
664 $nrow_plus_saveLines = $term->total_rows 894 $nrow_plus_saveLines = $term->total_rows
665 $lines_in_scrollback = $term->nsaved 895 $topmost_scrollback_row = $term->top_row
666 Return various integers describing terminal characteristics. 896 Return various integers describing terminal characteristics.
667 897
668 $x_display = $term->display_id 898 $x_display = $term->display_id
669 Return the DISPLAY used by rxvt-unicode. 899 Return the DISPLAY used by rxvt-unicode.
670 900
… …
680 $modifiermask = $term->ModNumLockMask 910 $modifiermask = $term->ModNumLockMask
681 Return the modifier masks corresponding to the "ISO Level 3 Shift" 911 Return the modifier masks corresponding to the "ISO Level 3 Shift"
682 (often AltGr), the meta key (often Alt) and the num lock key, if 912 (often AltGr), the meta key (often Alt) and the num lock key, if
683 applicable. 913 applicable.
684 914
915 $screen = $term->current_screen
916 Returns the currently displayed screen (0 primary, 1 secondary).
917
918 $cursor_is_hidden = $term->hidden_cursor
919 Returns wether the cursor is currently hidden or not.
920
685 $view_start = $term->view_start ([$newvalue]) 921 $view_start = $term->view_start ([$newvalue])
686 Returns the negative row number of the topmost line. Minimum value 922 Returns the row number of the topmost displayed line. Maximum value
687 is 0, which displays the normal terminal contents. Larger values 923 is 0, which displays the normal terminal contents. Lower values
688 scroll this many lines into the scrollback buffer. 924 scroll this many lines into the scrollback buffer.
689 925
690 $term->want_refresh 926 $term->want_refresh
691 Requests a screen refresh. At the next opportunity, rxvt-unicode 927 Requests a screen refresh. At the next opportunity, rxvt-unicode
692 will compare the on-screen display with its stored representation. 928 will compare the on-screen display with its stored representation.
… …
705 line, starting at column $start_col (default 0), which is useful to 941 line, starting at column $start_col (default 0), which is useful to
706 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
707 automatically be updated. 943 automatically be updated.
708 944
709 $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
710 more than one cell when displayed are padded with urxvt::NOCHAR 946 more than one cell when displayed are padded with $urxvt::NOCHAR
711 characters ("chr 65535"). Characters with combining characters and 947 (chr 65535) characters. Characters with combining characters and
712 other characters that do not fit into the normal tetx encoding will 948 other characters that do not fit into the normal tetx encoding will
713 be replaced with characters in the private use area. 949 be replaced with characters in the private use area.
714 950
715 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
716 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
… …
775 1011
776 $string = $term->special_decode $text 1012 $string = $term->special_decode $text
777 Converts rxvt-unicodes text reprsentation into a perl string. See 1013 Converts rxvt-unicodes text reprsentation into a perl string. See
778 "$term->ROW_t" for details. 1014 "$term->ROW_t" for details.
779 1015
780 $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])
781 Registers a synchronous button grab. See the XGrabButton manpage. 1019 Register/unregister a synchronous button grab. See the XGrabButton
1020 manpage.
782 1021
783 $success = $term->grab ($eventtime[, $sync]) 1022 $success = $term->grab ($eventtime[, $sync])
784 Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1023 Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
785 synchronous ($sync is true). Also remembers the grab timestampe. 1024 synchronous ($sync is true). Also remembers the grab timestampe.
786 1025
… …
796 1035
797 $term->ungrab 1036 $term->ungrab
798 Calls XUngrab for the most recent grab. Is called automatically on 1037 Calls XUngrab for the most recent grab. Is called automatically on
799 evaluation errors, as it is better to lose the grab in the error 1038 evaluation errors, as it is better to lose the grab in the error
800 case as the session. 1039 case as the session.
1040
1041 $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
1042 $atom_name = $term->XGetAtomName ($atom)
1043 @atoms = $term->XListProperties ($window)
1044 ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
1045 $term->XChangeWindowProperty ($window, $property, $type, $format,
1046 $octets)
1047 $term->XDeleteProperty ($window, $property)
1048 $window = $term->DefaultRootWindow
1049 $term->XReparentWindow ($window, $parent, [$x, $y])
1050 $term->XMapWindow ($window)
1051 $term->XUnmapWindow ($window)
1052 $term->XMoveResizeWindow ($window, $x, $y, $width, $height)
1053 ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x,
1054 $y)
1055 $term->XChangeInput ($window, $add_events[, $del_events])
1056 Various X or X-related functions. The $term object only serves as
1057 the source of the display, otherwise those functions map
1058 more-or-less directory onto the X functions of the same name.
801 1059
802 The "urxvt::popup" Class 1060 The "urxvt::popup" Class
803 $popup->add_title ($title) 1061 $popup->add_title ($title)
804 Adds a non-clickable title to the popup. 1062 Adds a non-clickable title to the popup.
805 1063
… …
853 $timer = $timer->start 1111 $timer = $timer->start
854 Start the timer. 1112 Start the timer.
855 1113
856 $timer = $timer->start ($tstamp) 1114 $timer = $timer->start ($tstamp)
857 Set the event trigger time to $tstamp and start the timer. 1115 Set the event trigger time to $tstamp and start the timer.
1116
1117 $timer = $timer->after ($delay)
1118 Like "start", but sets the expiry timer to c<urxvt::NOW + $delay>.
858 1119
859 $timer = $timer->stop 1120 $timer = $timer->stop
860 Stop the timer. 1121 Stop the timer.
861 1122
862 The "urxvt::iow" Class 1123 The "urxvt::iow" Class
… …
894 Start watching for requested events on the given handle. 1155 Start watching for requested events on the given handle.
895 1156
896 $iow = $iow->stop 1157 $iow = $iow->stop
897 Stop watching for events on the given filehandle. 1158 Stop watching for events on the given filehandle.
898 1159
1160 The "urxvt::iw" Class
1161 This class implements idle watchers, that get called automatically when
1162 the process is idle. They should return as fast as possible, after doing
1163 some useful work.
1164
1165 $iw = new urxvt::iw
1166 Create a new idle watcher object in stopped state.
1167
1168 $iw = $iw->cb (sub { my ($iw) = @_; ... })
1169 Set the callback to be called when the watcher triggers.
1170
1171 $timer = $timer->start
1172 Start the watcher.
1173
1174 $timer = $timer->stop
1175 Stop the watcher.
1176
1177 The "urxvt::pw" Class
1178 This class implements process watchers. They create an event whenever a
1179 process exits, after which they stop automatically.
1180
1181 my $pid = fork;
1182 ...
1183 $term->{pw} = urxvt::pw
1184 ->new
1185 ->start ($pid)
1186 ->cb (sub {
1187 my ($pw, $exit_status) = @_;
1188 ...
1189 });
1190
1191 $pw = new urxvt::pw
1192 Create a new process watcher in stopped state.
1193
1194 $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
1195 Set the callback to be called when the timer triggers.
1196
1197 $pw = $timer->start ($pid)
1198 Tells the wqtcher to start watching for process $pid.
1199
1200 $pw = $pw->stop
1201 Stop the watcher.
1202
899ENVIRONMENT 1203ENVIRONMENT
900 URXVT_PERL_VERBOSITY 1204 URXVT_PERL_VERBOSITY
901 This variable controls the verbosity level of the perl extension. Higher 1205 This variable controls the verbosity level of the perl extension. Higher
902 numbers indicate more verbose output. 1206 numbers indicate more verbose output.
903 1207

Diff Legend

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