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.14 by root, Sun Jan 8 06:35:38 2006 UTC vs.
Revision 1.31 by root, Thu Jan 19 19:26:31 2006 UTC

… …
21 thus must be encoded as UTF-8. 21 thus must be encoded as UTF-8.
22 22
23 Each script will only ever be loaded once, even in rxvtd, where scripts 23 Each script will only ever be loaded once, even in rxvtd, where scripts
24 will be shared (but not enabled) for all terminals. 24 will be shared (but not enabled) for all terminals.
25 25
26 Prepackaged Extensions 26PREPACKAGED EXTENSIONS
27 This section describes the extensiosn delivered with this version. You 27 This section describes the extensions delivered with this release. You
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 33
34 selection (enabled by default) 34 selection (enabled by default)
35 Intelligent selection. This extension tries to be more intelligent 35 (More) intelligent selection. This extension tries to be more
36 when the user extends selections (double-click). Right now, it tries 36 intelligent when the user extends selections (double-click and
37 to select urls and complete shell-quoted arguments, which is very 37 further clicks). Right now, it tries to select words, urls and
38 complete shell-quoted arguments, which is very convenient, too, if
38 convenient, too, if your ls supports "--quoting-style=shell". 39 your ls supports "--quoting-style=shell".
39 40
40 It also offers the following bindable event: 41 A double-click usually selects the word under the cursor, further
42 clicks will enlarge the selection.
43
44 The selection works by trying to match a number of regexes and
45 displaying them in increasing order of length. You can add your own
46 regexes by specifying resources of the form:
47
48 URxvt.selection.pattern-0: perl-regex
49 URxvt.selection.pattern-1: perl-regex
50 ...
51
52 The index number (0, 1...) must not have any holes, and each regex
53 must contain at least one pair of capturing parentheses, which will
54 be used for the match. For example, the followign adds a regex that
55 matches everything between two vertical bars:
56
57 URxvt.selection.pattern-0: \\|([^|]+)\\|
58
59 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.
61
62 This extension also offers following bindable keyboard commands:
41 63
42 rot13 64 rot13
43 Rot-13 the selection when activated. Used via keyboard trigger: 65 Rot-13 the selection when activated. Used via keyboard trigger:
44 66
45 URxvt.keysym.C-M-r: perl:selection:rot13 67 URxvt.keysym.C-M-r: perl:selection:rot13
46 68
47 option-popup (enabled by default) 69 option-popup (enabled by default)
48 Binds a popup menu to Ctrl-Button3 that lets you toggle (some) 70 Binds a popup menu to Ctrl-Button2 that lets you toggle (some)
49 options at runtime. 71 options at runtime.
50 72
51 digital-clock 73 selection-popup (enabled by default)
52 Displays a digital clock using the built-in overlay. 74 Binds a popup menu to Ctrl-Button3 that lets you convert the
75 selection text into various other formats/action (such as uri
76 unescaping, perl evalution, web-browser starting etc.), depending on
77 content.
78
79 Other extensions can extend this popup menu by pushing a code
80 reference onto "@{ $term-"{selection_popup_hook} }>, that is called
81 whenever the popup is displayed.
82
83 It's sole argument is the popup menu, which can be modified. The
84 selection is in $_, which can be used to decide wether to add
85 something or not. It should either return nothing or a string and a
86 code reference. The string will be used as button text and the code
87 reference will be called when the button gets activated and should
88 transform $_.
89
90 The following will add an entry "a to b" that transforms all "a"s in
91 the selection to "b"s, but only if the selection currently contains
92 any "a"s:
93
94 push @{ $self->{term}{selection_popup_hook} }, sub {
95 /a/ ? ("a to be" => sub { s/a/b/g }
96 : ()
97 };
98
99 searchable-scrollback<hotkey> (enabled by default)
100 Adds regex search functionality to the scrollback buffer, triggered
101 by a hotkey (default: "M-s"). While in search mode, normal terminal
102 input/output is suspended and a regex is displayed at the bottom of
103 the screen.
104
105 Inputting characters appends them to the regex and continues
106 incremental search. "BackSpace" removes a character from the regex,
107 "Up" and "Down" search upwards/downwards in the scrollback buffer,
108 "End" jumps to the bottom. "Escape" leaves search mode and returns
109 to the point where search was started, while "Enter" or "Return"
110 stay at the current position and additionally stores the first match
111 in the current line into the primary selection.
112
113 selection-autotransform
114 This selection allows you to do automatic transforms on a selection
115 whenever a selection is made.
116
117 It works by specifying perl snippets (most useful is a single "s///"
118 operator) that modify $_ as resources:
119
120 URxvt.selection-autotransform.0: transform
121 URxvt.selection-autotransform.1: transform
122 ...
123
124 For example, the following will transform selections of the form
125 "filename:number", often seen in compiler messages, into "vi
126 +$filename $word":
127
128 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
129
130 And this example matches the same,but replaces it with vi-commands
131 you can paste directly into your (vi :) editor:
132
133 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/
134
135 Of course, this can be modified to suit your needs and your editor
136 :)
137
138 To expand the example above to typical perl error messages ("XXX at
139 FILENAME line YYY."), you need a slightly more elaborate solution:
140
141 URxvt.selection.pattern-0: ( at .*? line \\d+[,.])
142 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/
143
144 The first line tells the selection code to treat the unchanging part
145 of every error message as a selection pattern, and the second line
146 transforms the message into vi commands to load the file.
53 147
54 mark-urls 148 mark-urls
55 Uses per-line display filtering ("on_line_update") to underline 149 Uses per-line display filtering ("on_line_update") to underline urls
56 urls. 150 and make them clickable. When middle-clicked, the program specified
151 in the resource "urlLauncher" (default "x-www-browser") will be
152 started with the URL as first argument.
153
154 automove-background
155 This is basically a one-line extension that dynamically changes the
156 background pixmap offset to the window position, in effect creating
157 the same effect as pseudo transparency with a custom pixmap. No
158 scaling is supported in this mode. Exmaple:
159
160 rxvt -pixmap background.xpm -pe automove-background
57 161
58 block-graphics-to-ascii 162 block-graphics-to-ascii
59 A not very useful example of filtering all text output to the 163 A not very useful example of filtering all text output to the
60 terminal, by replacing all line-drawing characters (U+2500 .. 164 terminal, by replacing all line-drawing characters (U+2500 ..
61 U+259F) by a similar-looking ascii character. 165 U+259F) by a similar-looking ascii character.
62 166
167 digital-clock
168 Displays a digital clock using the built-in overlay.
169
63 example-refresh-hooks 170 example-refresh-hooks
64 Displays a very simple digital clock in the upper right corner of 171 Displays a very simple digital clock in the upper right corner of
65 the window. Illustrates overwriting the refresh callbacks to create 172 the window. Illustrates overwriting the refresh callbacks to create
66 your own overlays or changes. 173 your own overlays or changes.
67 174
175 selection-pastebin
176 This is a little rarely useful extension that Uploads the selection
177 as textfile to a remote site (or does other things). (The
178 implementation is not currently secure for use in a multiuser
179 environment as it writes to /tmp directly.).
180
181 It listens to the "selection-pastebin:remote-pastebin" keyboard
182 command, i.e.
183
184 URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin
185
186 Pressing this combination runs a command with "%" replaced by the
187 name of the textfile. This command can be set via a resource:
188
189 URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
190
191 And the default is likely not useful to anybody but the few people
192 around here :)
193
194 The name of the textfile is the hex encoded md5 sum of the
195 selection, so the same content should lead to the same filename.
196
197 After a successful upload the selection will be replaced by the text
198 given in the "selection-pastebin-url" resource (again, the % is the
199 placeholder for the filename):
200
201 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
202
203API DOCUMENTATION
68 General API Considerations 204 General API Considerations
69 All objects (such as terminals, time watchers etc.) are typical 205 All objects (such as terminals, time watchers etc.) are typical
70 reference-to-hash objects. The hash can be used to store anything you 206 reference-to-hash objects. The hash can be used to store anything you
71 like. All members starting with an underscore (such as "_ptr" or 207 like. All members starting with an underscore (such as "_ptr" or
72 "_hook") are reserved for internal uses and MUST NOT be accessed or 208 "_hook") are reserved for internal uses and MUST NOT be accessed or
… …
80 Argument names also often indicate the type of a parameter. Here are 216 Argument names also often indicate the type of a parameter. Here are
81 some hints on what they mean: 217 some hints on what they mean:
82 218
83 $text 219 $text
84 Rxvt-unicodes special way of encoding text, where one "unicode" 220 Rxvt-unicodes special way of encoding text, where one "unicode"
85 character always represents one screen cell. See row_t for a 221 character always represents one screen cell. See ROW_t for a
86 discussion of this format. 222 discussion of this format.
87 223
88 $string 224 $string
89 A perl text string, with an emphasis on *text*. It can store all 225 A perl text string, with an emphasis on *text*. It can store all
90 unicode characters and is to be distinguished with text encoded in a 226 unicode characters and is to be distinguished with text encoded in a
… …
92 228
93 $octets 229 $octets
94 Either binary data or - more common - a text string encoded in a 230 Either binary data or - more common - a text string encoded in a
95 locale-specific way. 231 locale-specific way.
96 232
233 Extension Objects
234 Very perl extension is a perl class. A separate perl object is created
235 for each terminal and each extension and passed as the first parameter
236 to hooks. So extensions can use their $self object without having to
237 think about other extensions, with the exception of methods and members
238 that begin with an underscore character "_": these are reserved for
239 internal use.
240
241 Although it isn't a "urxvt::term" object, you can call all methods of
242 the "urxvt::term" class on this object.
243
244 It has the following methods and data members:
245
246 $urxvt_term = $self->{term}
247 Returns the "urxvt::term" object associated with this instance of
248 the extension. This member *must not* be changed in any way.
249
250 $self->enable ($hook_name => $cb, [$hook_name => $cb..])
251 Dynamically enable the given hooks (named without the "on_" prefix)
252 for this extension, replacing any previous hook. This is useful when
253 you want to overwrite time-critical hooks only temporarily.
254
255 $self->disable ($hook_name[, $hook_name..])
256 Dynamically disable the given hooks.
257
97 Hooks 258 Hooks
98 The following subroutines can be declared in extension files, and will 259 The following subroutines can be declared in extension files, and will
99 be called whenever the relevant event happens. 260 be called whenever the relevant event happens.
100 261
101 The first argument passed to them is an object private to each terminal 262 The first argument passed to them is an extension oject as described in
102 and extension package. You can call all "urxvt::term" methods on it, but 263 the in the "Extension Objects" section.
103 its not a real "urxvt::term" object. Instead, the real "urxvt::term"
104 object that is shared between all packages is stored in the "term"
105 member. It is, however, blessed intot he package of the extension
106 script, so for all practical purposes you can treat an extension script
107 as a class.
108 264
109 All of them must return a boolean value. If it is true, then the event 265 All of these hooks must return a boolean value. If it is true, then the
110 counts as being *consumed*, and the invocation of other hooks is 266 event counts as being *consumed*, and the invocation of other hooks is
111 skipped, and the relevant action might not be carried out by the C++ 267 skipped, and the relevant action might not be carried out by the C++
112 code. 268 code.
113 269
114 When in doubt, return a false value (preferably "()"). 270 *When in doubt, return a false value (preferably "()").*
115 271
116 on_init $term 272 on_init $term
117 Called after a new terminal object has been initialized, but before 273 Called after a new terminal object has been initialized, but before
118 windows are created or the command gets run. Most methods are unsafe 274 windows are created or the command gets run. Most methods are unsafe
119 to call or deliver senseless data, as terminal size and other 275 to call or deliver senseless data, as terminal size and other
… …
127 283
128 on_start $term 284 on_start $term
129 Called at the very end of initialisation of a new terminal, just 285 Called at the very end of initialisation of a new terminal, just
130 before returning to the mainloop. 286 before returning to the mainloop.
131 287
288 on_child_start $term, $pid
289 Called just after the child process has been "fork"ed.
290
291 on_child_exit $term, $status
292 Called just after the child process has exited. $status is the
293 status from "waitpid".
294
132 on_sel_make $term, $eventtime 295 on_sel_make $term, $eventtime
133 Called whenever a selection has been made by the user, but before 296 Called whenever a selection has been made by the user, but before
134 the selection text is copied, so changes to the beginning, end or 297 the selection text is copied, so changes to the beginning, end or
135 type of the selection will be honored. 298 type of the selection will be honored.
136 299
… …
148 311
149 on_sel_extend $term 312 on_sel_extend $term
150 Called whenever the user tries to extend the selection (e.g. with a 313 Called whenever the user tries to extend the selection (e.g. with a
151 double click) and is either supposed to return false (normal 314 double click) and is either supposed to return false (normal
152 operation), or should extend the selection itelf and return true to 315 operation), or should extend the selection itelf and return true to
153 suppress the built-in processing. 316 suppress the built-in processing. This can happen multiple times, as
317 long as the callback returns true, it will be called on every
318 further click by the user and is supposed to enlarge the selection
319 more and more, if possible.
154 320
155 See the selection example extension. 321 See the selection example extension.
156 322
157 on_view_change $term, $offset 323 on_view_change $term, $offset
158 Called whenever the view offset changes, i..e the user or program 324 Called whenever the view offset changes, i..e the user or program
… …
165 may be larger than the scroll back buffer or the terminal. 331 may be larger than the scroll back buffer or the terminal.
166 332
167 It is called before lines are scrolled out (so rows 0 .. min ($lines 333 It is called before lines are scrolled out (so rows 0 .. min ($lines
168 - 1, $nrow - 1) represent the lines to be scrolled out). $saved is 334 - 1, $nrow - 1) represent the lines to be scrolled out). $saved is
169 the total number of lines that will be in the scrollback buffer. 335 the total number of lines that will be in the scrollback buffer.
170
171 on_tty_activity $term *NYI*
172 Called whenever the program(s) running in the urxvt window send
173 output.
174 336
175 on_osc_seq $term, $string 337 on_osc_seq $term, $string
176 Called whenever the ESC ] 777 ; string ST command sequence (OSC = 338 Called whenever the ESC ] 777 ; string ST command sequence (OSC =
177 operating system command) is processed. Cursor position and other 339 operating system command) is processed. Cursor position and other
178 state information is up-to-date when this happens. For 340 state information is up-to-date when this happens. For
… …
189 argument. You can filter/change and output the text yourself by 351 argument. You can filter/change and output the text yourself by
190 returning a true value and calling "$term->scr_add_lines" yourself. 352 returning a true value and calling "$term->scr_add_lines" yourself.
191 Please note that this might be very slow, however, as your hook is 353 Please note that this might be very slow, however, as your hook is
192 called for all text being output. 354 called for all text being output.
193 355
356 on_tt_write $term, $octets
357 Called whenever some data is written to the tty/pty and can be used
358 to suppress or filter tty input.
359
194 on_line_update $term, $row 360 on_line_update $term, $row
195 Called whenever a line was updated or changed. Can be used to filter 361 Called whenever a line was updated or changed. Can be used to filter
196 screen output (e.g. underline urls or other useless stuff). Only 362 screen output (e.g. underline urls or other useless stuff). Only
197 lines that are being shown will be filtered, and, due to performance 363 lines that are being shown will be filtered, and, due to performance
198 reasons, not always immediately. 364 reasons, not always immediately.
… …
217 on_keyboard_command $term, $string 383 on_keyboard_command $term, $string
218 Called whenever the user presses a key combination that has a 384 Called whenever the user presses a key combination that has a
219 "perl:string" action bound to it (see description of the keysym 385 "perl:string" action bound to it (see description of the keysym
220 resource in the rxvt(1) manpage). 386 resource in the rxvt(1) manpage).
221 387
388 on_x_event $term, $event
389 Called on every X event received on the vt window (and possibly
390 other windows). Should only be used as a last resort. Most event
391 structure members are not passed.
392
222 on_focus_in $term 393 on_focus_in $term
223 Called whenever the window gets the keyboard focus, before 394 Called whenever the window gets the keyboard focus, before
224 rxvt-unicode does focus in processing. 395 rxvt-unicode does focus in processing.
225 396
226 on_focus_out $term 397 on_focus_out $term
227 Called wheneever the window loses keyboard focus, before 398 Called wheneever the window loses keyboard focus, before
228 rxvt-unicode does focus out processing. 399 rxvt-unicode does focus out processing.
229 400
401 on_configure_notify $term, $event
230 on_key_press $term, $event, $octets 402 on_key_press $term, $event, $keysym, $octets
231 on_key_release $term, $event 403 on_key_release $term, $event, $keysym
232 on_button_press $term, $event 404 on_button_press $term, $event
233 on_button_release $term, $event 405 on_button_release $term, $event
234 on_motion_notify $term, $event 406 on_motion_notify $term, $event
235 on_map_notify $term, $event 407 on_map_notify $term, $event
236 on_unmap_notify $term, $event 408 on_unmap_notify $term, $event
… …
246 output, if any, in locale-specific encoding. 418 output, if any, in locale-specific encoding.
247 419
248 subwindow. 420 subwindow.
249 421
250 Variables in the "urxvt" Package 422 Variables in the "urxvt" Package
423 $urxvt::LIBDIR
424 The rxvt-unicode library directory, where, among other things, the
425 perl modules and scripts are stored.
426
427 $urxvt::RESCLASS, $urxvt::RESCLASS
428 The resource class and name rxvt-unicode uses to look up X
429 resources.
430
431 $urxvt::RXVTNAME
432 The basename of the installed binaries, usually "urxvt".
433
251 $urxvt::TERM 434 $urxvt::TERM
252 The current terminal. This variable stores the current "urxvt::term" 435 The current terminal. This variable stores the current "urxvt::term"
253 object, whenever a callback/hook is executing. 436 object, whenever a callback/hook is executing.
254 437
255 Functions in the "urxvt" Package 438 Functions in the "urxvt" Package
256 $term = new urxvt [arg...]
257 Creates a new terminal, very similar as if you had started it with
258 "system $binfile, arg...". Croaks (and probably outputs an error
259 message) if the new instance couldn't be created. Returns "undef" if
260 the new instance didn't initialise perl, and the terminal object
261 otherwise. The "init" and "start" hooks will be called during the
262 call.
263
264 urxvt::fatal $errormessage 439 urxvt::fatal $errormessage
265 Fatally aborts execution with the given error message. Avoid at all 440 Fatally aborts execution with the given error message. Avoid at all
266 costs! The only time this is acceptable is when the terminal process 441 costs! The only time this is acceptable is when the terminal process
267 starts up. 442 starts up.
268 443
… …
272 function that calls this function. 447 function that calls this function.
273 448
274 Using this function has the advantage that its output ends up in the 449 Using this function has the advantage that its output ends up in the
275 correct place, e.g. on stderr of the connecting urxvtc client. 450 correct place, e.g. on stderr of the connecting urxvtc client.
276 451
452 Messages have a size limit of 1023 bytes currently.
453
277 $time = urxvt::NOW 454 $time = urxvt::NOW
278 Returns the "current time" (as per the event loop). 455 Returns the "current time" (as per the event loop).
279 456
280 urxvt::CurrentTime 457 urxvt::CurrentTime
281 urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, 458 urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask,
282 Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask, 459 Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask,
283 Button5Mask, AnyModifier 460 Button5Mask, AnyModifier
461 urxvt::NoEventMask, KeyPressMask, KeyReleaseMask, ButtonPressMask,
462 ButtonReleaseMask, EnterWindowMask, LeaveWindowMask, PointerMotionMask,
463 PointerMotionHintMask, Button1MotionMask, Button2MotionMask,
464 Button3MotionMask, Button4MotionMask, Button5MotionMask,
465 ButtonMotionMask, KeymapStateMask, ExposureMask, VisibilityChangeMask,
466 StructureNotifyMask, ResizeRedirectMask, SubstructureNotifyMask,
467 SubstructureRedirectMask, FocusChangeMask, PropertyChangeMask,
468 ColormapChangeMask, OwnerGrabButtonMask
469 urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify,
470 EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose,
471 GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify, DestroyNotify,
472 UnmapNotify, MapNotify, MapRequest, ReparentNotify, ConfigureNotify,
473 ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify,
474 CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest,
475 SelectionNotify, ColormapNotify, ClientMessage, MappingNotify
284 Various constants for use in X calls and event processing. 476 Various constants for use in X calls and event processing.
285 477
286 RENDITION 478 RENDITION
287 Rendition bitsets contain information about colour, font, font styles 479 Rendition bitsets contain information about colour, font, font styles
288 and similar information for each screen cell. 480 and similar information for each screen cell.
… …
307 499
308 $foreground = urxvt::GET_BASEFG $rend 500 $foreground = urxvt::GET_BASEFG $rend
309 $background = urxvt::GET_BASEBG $rend 501 $background = urxvt::GET_BASEBG $rend
310 Return the foreground/background colour index, respectively. 502 Return the foreground/background colour index, respectively.
311 503
312 $rend = urxvt::SET_FGCOLOR ($rend, $new_colour) 504 $rend = urxvt::SET_FGCOLOR $rend, $new_colour
313 $rend = urxvt::SET_BGCOLOR ($rend, $new_colour) 505 $rend = urxvt::SET_BGCOLOR $rend, $new_colour
314 Replace the foreground/background colour in the rendition mask with 506 Replace the foreground/background colour in the rendition mask with
315 the specified one. 507 the specified one.
316 508
317 $value = urxvt::GET_CUSTOM ($rend) 509 $value = urxvt::GET_CUSTOM $rend
318 Return the "custom" value: Every rendition has 5 bits for use by 510 Return the "custom" value: Every rendition has 5 bits for use by
319 extensions. They can be set and changed as you like and are 511 extensions. They can be set and changed as you like and are
320 initially zero. 512 initially zero.
321 513
322 $rend = urxvt::SET_CUSTOM ($rend, $new_value) 514 $rend = urxvt::SET_CUSTOM $rend, $new_value
323 Change the custom value. 515 Change the custom value.
324 516
325 The "urxvt::anyevent" Class 517 The "urxvt::anyevent" Class
326 The sole purpose of this class is to deliver an interface to the 518 The sole purpose of this class is to deliver an interface to the
327 "AnyEvent" module - any module using it will work inside urxvt without 519 "AnyEvent" module - any module using it will work inside urxvt without
328 further work. The only exception is that you cannot wait on condition 520 further programming. The only exception is that you cannot wait on
329 variables, but non-blocking condvar use is ok. What this means is that 521 condition variables, but non-blocking condvar use is ok. What this means
330 you cannot use blocking APIs, but the non-blocking variant should work. 522 is that you cannot use blocking APIs, but the non-blocking variant
523 should work.
331 524
332 The "urxvt::term" Class 525 The "urxvt::term" Class
526 $term = new urxvt::term $envhashref, $rxvtname, [arg...]
527 Creates a new terminal, very similar as if you had started it with
528 system "$rxvtname, arg...". $envhashref must be a reference to a
529 %ENV-like hash which defines the environment of the new terminal.
530
531 Croaks (and probably outputs an error message) if the new instance
532 couldn't be created. Returns "undef" if the new instance didn't
533 initialise perl, and the terminal object otherwise. The "init" and
534 "start" hooks will be called during this call.
535
333 $term->destroy 536 $term->destroy
334 Destroy the terminal object (close the window, free resources etc.). 537 Destroy the terminal object (close the window, free resources etc.).
538 Please note that rxvt will not exit as long as any event watchers
539 (timers, io watchers) are still active.
540
541 $term->exec_async ($cmd[, @args])
542 Works like the combination of the "fork"/"exec" builtins, which
543 executes ("starts") programs in the background. This function takes
544 care of setting the user environment before exec'ing the command
545 (e.g. "PATH") and should be preferred over explicit calls to "exec"
546 or "system".
547
548 Returns the pid of the subprocess or "undef" on error.
335 549
336 $isset = $term->option ($optval[, $set]) 550 $isset = $term->option ($optval[, $set])
337 Returns true if the option specified by $optval is enabled, and 551 Returns true if the option specified by $optval is enabled, and
338 optionally change it. All option values are stored by name in the 552 optionally change it. All option values are stored by name in the
339 hash %urxvt::OPTION. Options not enabled in this binary are not in 553 hash %urxvt::OPTION. Options not enabled in this binary are not in
… …
342 Here is a a likely non-exhaustive list of option names, please see 556 Here is a a likely non-exhaustive list of option names, please see
343 the source file /src/optinc.h to see the actual list: 557 the source file /src/optinc.h to see the actual list:
344 558
345 borderLess console cursorBlink cursorUnderline hold iconic insecure 559 borderLess console cursorBlink cursorUnderline hold iconic insecure
346 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 560 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
347 pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating 561 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
348 scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer 562 scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput
349 secondaryScreen secondaryScroll skipBuiltinGlyphs transparent 563 scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs
350 tripleclickwords utmpInhibit visualBell 564 transparent tripleclickwords utmpInhibit visualBell
351 565
352 $value = $term->resource ($name[, $newval]) 566 $value = $term->resource ($name[, $newval])
353 Returns the current resource value associated with a given name and 567 Returns the current resource value associated with a given name and
354 optionally sets a new value. Setting values is most useful in the 568 optionally sets a new value. Setting values is most useful in the
355 "init" hook. Unset resources are returned and accepted as "undef". 569 "init" hook. Unset resources are returned and accepted as "undef".
… …
372 586
373 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 587 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
374 borderLess color cursorBlink cursorUnderline cutchars delete_key 588 borderLess color cursorBlink cursorUnderline cutchars delete_key
375 display_name embed ext_bwidth fade font geometry hold iconName 589 display_name embed ext_bwidth fade font geometry hold iconName
376 imFont imLocale inputMethod insecure int_bwidth intensityStyles 590 imFont imLocale inputMethod insecure int_bwidth intensityStyles
377 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier 591 italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier
378 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2 592 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
379 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 593 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
380 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 594 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
381 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 595 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
382 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 596 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
597 secondaryScreen secondaryScroll selectstyle shade term_name title
383 shade term_name title transparent transparent_all tripleclickwords 598 transient_for transparent transparent_all tripleclickwords utmpInhibit
384 utmpInhibit visualBell 599 visualBell
600
601 $value = $term->x_resource ($pattern)
602 Returns the X-Resource for the given pattern, excluding the program
603 or class name, i.e. "$term->x_resource ("boldFont")" should return
604 the same value as used by this instance of rxvt-unicode. Returns
605 "undef" if no resource with that pattern exists.
606
607 This method should only be called during the "on_start" hook, as
608 there is only one resource database per display, and later
609 invocations might return the wrong resources.
610
611 $success = $term->parse_keysym ($keysym_spec, $command_string)
612 Adds a keymap translation exactly as specified via a resource. See
613 the "keysym" resource in the rxvt(1) manpage.
385 614
386 $rend = $term->rstyle ([$new_rstyle]) 615 $rend = $term->rstyle ([$new_rstyle])
387 Return and optionally change the current rendition. Text that is 616 Return and optionally change the current rendition. Text that is
388 output by the terminal application will use this style. 617 output by the terminal application will use this style.
389 618
… …
396 ($row, $col) = $term->selection_beg ([$row, $col]) 625 ($row, $col) = $term->selection_beg ([$row, $col])
397 ($row, $col) = $term->selection_end ([$row, $col]) 626 ($row, $col) = $term->selection_end ([$row, $col])
398 Return the current values of the selection mark, begin or end 627 Return the current values of the selection mark, begin or end
399 positions, and optionally set them to new values. 628 positions, and optionally set them to new values.
400 629
630 $term->selection_make ($eventtime[, $rectangular])
631 Tries to make a selection as set by "selection_beg" and
632 "selection_end". If $rectangular is true (default: false), a
633 rectangular selection will be made. This is the prefered function to
634 make a selection.
635
401 $success = $term->selection_grab ($eventtime) 636 $success = $term->selection_grab ($eventtime)
402 Try to request the primary selection from the server (for example, 637 Try to request the primary selection text from the server (for
403 as set by the next method). 638 example, as set by the next method). No visual feedback will be
639 given. This function is mostly useful from within "on_sel_grab"
640 hooks.
404 641
405 $oldtext = $term->selection ([$newtext]) 642 $oldtext = $term->selection ([$newtext])
406 Return the current selection text and optionally replace it by 643 Return the current selection text and optionally replace it by
407 $newtext. 644 $newtext.
408 645
409 #=item $term->overlay ($x, $y, $text) # #Create a simple multi-line 646 $term->overlay_simple ($x, $y, $text)
410 overlay box. See the next method for details. # #=cut # #sub 647 Create a simple multi-line overlay box. See the next method for
411 urxvt::term::scr_overlay { # my ($self, $x, $y, $text) = @_; # # my 648 details.
412 @lines = split /\n/, $text; # # my $w = 0; # for (map
413 $self->strwidth ($_), @lines) { # $w = $_ if $w < $_; # } # #
414 $self->scr_overlay_new ($x, $y, $w, scalar @lines); #
415 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; #}
416 649
417 $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 650 $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
418 Create a new (empty) overlay at the given position with the given 651 Create a new (empty) overlay at the given position with the given
419 width/height. $rstyle defines the initial rendition style (default: 652 width/height. $rstyle defines the initial rendition style (default:
420 "OVERLAY_RSTYLE"). 653 "OVERLAY_RSTYLE").
… …
454 Convert the given text string into the corresponding locale 687 Convert the given text string into the corresponding locale
455 encoding. 688 encoding.
456 689
457 $string = $term->locale_decode ($octets) 690 $string = $term->locale_decode ($octets)
458 Convert the given locale-encoded octets into a perl string. 691 Convert the given locale-encoded octets into a perl string.
692
693 $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
694 XORs the rendition values in the given span with the provided value
695 (default: "RS_RVid"), which *MUST NOT* contain font styles. Useful
696 in refresh hooks to provide effects similar to the selection.
697
698 $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[,
699 $rstyle2]])
700 Similar to "scr_xor_span", but xors a rectangle instead. Trailing
701 whitespace will additionally be xored with the $rstyle2, which
702 defaults to "RS_RVid | RS_Uline", which removes reverse video again
703 and underlines it instead. Both styles *MUST NOT* contain font
704 styles.
705
706 $term->scr_bell
707 Ring the bell!
459 708
460 $term->scr_add_lines ($string) 709 $term->scr_add_lines ($string)
461 Write the given text string to the screen, as if output by the 710 Write the given text string to the screen, as if output by the
462 application running inside the terminal. It may not contain command 711 application running inside the terminal. It may not contain command
463 sequences (escape codes), but is free to use line feeds, carriage 712 sequences (escape codes), but is free to use line feeds, carriage
… …
477 Write the octets given in $data to the tty (i.e. as program input). 726 Write the octets given in $data to the tty (i.e. as program input).
478 To pass characters instead of octets, you should convert your 727 To pass characters instead of octets, you should convert your
479 strings first to the locale-specific encoding using 728 strings first to the locale-specific encoding using
480 "$term->locale_encode". 729 "$term->locale_encode".
481 730
731 $old_events = $term->pty_ev_events ([$new_events])
732 Replaces the event mask of the pty watcher by the given event mask.
733 Can be used to suppress input and output handling to the pty/tty.
734 See the description of "urxvt::timer->events". Make sure to always
735 restore the previous value.
736
482 $windowid = $term->parent 737 $windowid = $term->parent
483 Return the window id of the toplevel window. 738 Return the window id of the toplevel window.
484 739
485 $windowid = $term->vt 740 $windowid = $term->vt
486 Return the window id of the terminal window. 741 Return the window id of the terminal window.
742
743 $term->vt_emask_add ($x_event_mask)
744 Adds the specified events to the vt event mask. Useful e.g. when you
745 want to receive pointer events all the times:
746
747 $term->vt_emask_add (urxvt::PointerMotionMask);
487 748
488 $window_width = $term->width 749 $window_width = $term->width
489 $window_height = $term->height 750 $window_height = $term->height
490 $font_width = $term->fwidth 751 $font_width = $term->fwidth
491 $font_height = $term->fheight 752 $font_height = $term->fheight
… …
494 $terminal_columns = $term->ncol 755 $terminal_columns = $term->ncol
495 $has_focus = $term->focus 756 $has_focus = $term->focus
496 $is_mapped = $term->mapped 757 $is_mapped = $term->mapped
497 $max_scrollback = $term->saveLines 758 $max_scrollback = $term->saveLines
498 $nrow_plus_saveLines = $term->total_rows 759 $nrow_plus_saveLines = $term->total_rows
499 $lines_in_scrollback = $term->nsaved 760 $topmost_scrollback_row = $term->top_row
500 Return various integers describing terminal characteristics. 761 Return various integers describing terminal characteristics.
762
763 $x_display = $term->display_id
764 Return the DISPLAY used by rxvt-unicode.
765
766 $lc_ctype = $term->locale
767 Returns the LC_CTYPE category string used by this rxvt-unicode.
768
769 $env = $term->env
770 Returns a copy of the environment in effect for the terminal as a
771 hashref similar to "\%ENV".
501 772
502 $modifiermask = $term->ModLevel3Mask 773 $modifiermask = $term->ModLevel3Mask
503 $modifiermask = $term->ModMetaMask 774 $modifiermask = $term->ModMetaMask
504 $modifiermask = $term->ModNumLockMask 775 $modifiermask = $term->ModNumLockMask
505 Return the modifier masks corresponding to the "ISO Level 3 Shift" 776 Return the modifier masks corresponding to the "ISO Level 3 Shift"
506 (often AltGr), the meta key (often Alt) and the num lock key, if 777 (often AltGr), the meta key (often Alt) and the num lock key, if
507 applicable. 778 applicable.
508 779
509 $view_start = $term->view_start ([$newvalue]) 780 $view_start = $term->view_start ([$newvalue])
510 Returns the negative row number of the topmost line. Minimum value 781 Returns the row number of the topmost displayed line. Maximum value
511 is 0, which displays the normal terminal contents. Larger values 782 is 0, which displays the normal terminal contents. Lower values
512 scroll this many lines into the scrollback buffer. 783 scroll this many lines into the scrollback buffer.
513 784
514 $term->want_refresh 785 $term->want_refresh
515 Requests a screen refresh. At the next opportunity, rxvt-unicode 786 Requests a screen refresh. At the next opportunity, rxvt-unicode
516 will compare the on-screen display with its stored representation. 787 will compare the on-screen display with its stored representation.
… …
584 Return the row number of the first/last row of the line, 855 Return the row number of the first/last row of the line,
585 respectively. 856 respectively.
586 857
587 $offset = $line->offset_of ($row, $col) 858 $offset = $line->offset_of ($row, $col)
588 Returns the character offset of the given row|col pair within 859 Returns the character offset of the given row|col pair within
589 the logical line. 860 the logical line. Works for rows outside the line, too, and
861 returns corresponding offsets outside the string.
590 862
591 ($row, $col) = $line->coord_of ($offset) 863 ($row, $col) = $line->coord_of ($offset)
592 Translates a string offset into terminal coordinates again. 864 Translates a string offset into terminal coordinates again.
593 865
594 ($row, $col) = $line->coord_of ($offset) =item $text =
595 $term->special_encode $string 866 $text = $term->special_encode $string
596 Converts a perl string into the special encoding used by 867 Converts a perl string into the special encoding used by
597 rxvt-unicode, where one character corresponds to one screen cell. 868 rxvt-unicode, where one character corresponds to one screen cell.
598 See "$term->ROW_t" for details. 869 See "$term->ROW_t" for details.
599 870
600 $string = $term->special_decode $text 871 $string = $term->special_decode $text
601 Converts rxvt-unicodes text reprsentation into a perl string. See 872 Converts rxvt-unicodes text reprsentation into a perl string. See
602 "$term->ROW_t" for details. 873 "$term->ROW_t" for details.
603 874
875 $success = $term->grab_button ($button, $modifiermask)
876 Registers a synchronous button grab. See the XGrabButton manpage.
877
878 $success = $term->grab ($eventtime[, $sync])
879 Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
880 synchronous ($sync is true). Also remembers the grab timestampe.
881
882 $term->allow_events_async
883 Calls XAllowEvents with AsyncBoth for the most recent grab.
884
885 $term->allow_events_sync
886 Calls XAllowEvents with SyncBoth for the most recent grab.
887
888 $term->allow_events_replay
889 Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for
890 the most recent grab.
891
892 $term->ungrab
893 Calls XUngrab for the most recent grab. Is called automatically on
894 evaluation errors, as it is better to lose the grab in the error
895 case as the session.
896
604 The "urxvt::popup" Class 897 The "urxvt::popup" Class
898 $popup->add_title ($title)
899 Adds a non-clickable title to the popup.
900
901 $popup->add_separator ([$sepchr])
902 Creates a separator, optionally using the character given as
903 $sepchr.
904
905 $popup->add_button ($text, $cb)
906 Adds a clickable button to the popup. $cb is called whenever it is
907 selected.
908
909 $popup->add_toggle ($text, $cb, $initial_value)
910 Adds a toggle/checkbox item to the popup. Teh callback gets called
911 whenever it gets toggled, with a boolean indicating its value as its
912 first argument.
913
914 $popup->show
915 Displays the popup (which is initially hidden).
916
605 The "urxvt::timer" Class 917 The "urxvt::timer" Class
606 This class implements timer watchers/events. Time is represented as 918 This class implements timer watchers/events. Time is represented as a
607 a fractional number of seconds since the epoch. Example: 919 fractional number of seconds since the epoch. Example:
608 920
609 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0); 921 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
610 $term->{timer} = urxvt::timer 922 $term->{timer} = urxvt::timer
611 ->new 923 ->new
612 ->interval (1) 924 ->interval (1)
613 ->cb (sub { 925 ->cb (sub {
614 $term->{overlay}->set (0, 0, 926 $term->{overlay}->set (0, 0,
615 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]); 927 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
616 }); 928 });
617 929
618 $timer = new urxvt::timer 930 $timer = new urxvt::timer
619 Create a new timer object in started state. It is scheduled to 931 Create a new timer object in started state. It is scheduled to fire
620 fire immediately. 932 immediately.
621 933
622 $timer = $timer->cb (sub { my ($timer) = @_; ... }) 934 $timer = $timer->cb (sub { my ($timer) = @_; ... })
623 Set the callback to be called when the timer triggers. 935 Set the callback to be called when the timer triggers.
624 936
625 $tstamp = $timer->at 937 $tstamp = $timer->at
626 Return the time this watcher will fire next. 938 Return the time this watcher will fire next.
627 939
628 $timer = $timer->set ($tstamp) 940 $timer = $timer->set ($tstamp)
629 Set the time the event is generated to $tstamp. 941 Set the time the event is generated to $tstamp.
630 942
631 $timer = $timer->interval ($interval) 943 $timer = $timer->interval ($interval)
632 Normally (and when $interval is 0), the timer will automatically 944 Normally (and when $interval is 0), the timer will automatically
633 stop after it has fired once. If $interval is non-zero, then the 945 stop after it has fired once. If $interval is non-zero, then the
634 timer is automatically rescheduled at the given intervals. 946 timer is automatically rescheduled at the given intervals.
635 947
636 $timer = $timer->start 948 $timer = $timer->start
637 Start the timer. 949 Start the timer.
638 950
639 $timer = $timer->start ($tstamp) 951 $timer = $timer->start ($tstamp)
640 Set the event trigger time to $tstamp and start the timer. 952 Set the event trigger time to $tstamp and start the timer.
641 953
954 $timer = $timer->after ($delay)
955 Like "start", but sets the expiry timer to c<urxvt::NOW + $delay>.
956
642 $timer = $timer->stop 957 $timer = $timer->stop
643 Stop the timer. 958 Stop the timer.
644 959
645 The "urxvt::iow" Class 960 The "urxvt::iow" Class
646 This class implements io watchers/events. Example: 961 This class implements io watchers/events. Example:
647 962
648 $term->{socket} = ... 963 $term->{socket} = ...
649 $term->{iow} = urxvt::iow 964 $term->{iow} = urxvt::iow
650 ->new 965 ->new
651 ->fd (fileno $term->{socket}) 966 ->fd (fileno $term->{socket})
652 ->events (1) # wait for read data 967 ->events (urxvt::EVENT_READ)
653 ->start 968 ->start
654 ->cb (sub { 969 ->cb (sub {
655 my ($iow, $revents) = @_; 970 my ($iow, $revents) = @_;
656 # $revents must be 1 here, no need to check 971 # $revents must be 1 here, no need to check
657 sysread $term->{socket}, my $buf, 8192 972 sysread $term->{socket}, my $buf, 8192
658 or end-of-file; 973 or end-of-file;
659 }); 974 });
660 975
661 $iow = new urxvt::iow 976 $iow = new urxvt::iow
662 Create a new io watcher object in stopped state. 977 Create a new io watcher object in stopped state.
663 978
664 $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... }) 979 $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
665 Set the callback to be called when io events are triggered. 980 Set the callback to be called when io events are triggered.
666 $reventmask is a bitset as described in the "events" method. 981 $reventmask is a bitset as described in the "events" method.
667 982
668 $iow = $iow->fd ($fd) 983 $iow = $iow->fd ($fd)
669 Set the filedescriptor (not handle) to watch. 984 Set the filedescriptor (not handle) to watch.
670 985
671 $iow = $iow->events ($eventmask) 986 $iow = $iow->events ($eventmask)
672 Set the event mask to watch. Bit #0 (value 1) enables watching 987 Set the event mask to watch. The only allowed values are
673 for read data, Bit #1 (value 2) enables watching for write data. 988 "urxvt::EVENT_READ" and "urxvt::EVENT_WRITE", which might be ORed
989 together, or "urxvt::EVENT_NONE".
674 990
675 $iow = $iow->start 991 $iow = $iow->start
676 Start watching for requested events on the given handle. 992 Start watching for requested events on the given handle.
677 993
678 $iow = $iow->stop 994 $iow = $iow->stop
679 Stop watching for events on the given filehandle. 995 Stop watching for events on the given filehandle.
680 996
681ENVIRONMENT 997ENVIRONMENT
682 URXVT_PERL_VERBOSITY 998 URXVT_PERL_VERBOSITY
683 This variable controls the verbosity level of the perl extension. 999 This variable controls the verbosity level of the perl extension. Higher
684 Higher numbers indicate more verbose output. 1000 numbers indicate more verbose output.
685 1001
686 =0 - only fatal messages 1002 == 0 - fatal messages
687 =3 - script loading and management 1003 >= 3 - script loading and management
688 =10 - all events received 1004 >=10 - all called hooks
1005 >=11 - hook reutrn values
689 1006
690AUTHOR 1007AUTHOR
691 Marc Lehmann <pcg@goof.com> 1008 Marc Lehmann <pcg@goof.com>
692 http://software.schmorp.de/pkg/rxvt-unicode 1009 http://software.schmorp.de/pkg/rxvt-unicode
693 1010

Diff Legend

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