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

Diff Legend

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