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.15 by root, Mon Jan 9 01:36:56 2006 UTC vs.
Revision 1.28 by root, Mon Jan 16 06:37:51 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
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
40 It also offers the following bindable event: 62 This extension also offers the following bindable keyboard command:
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
… …
48 Binds a popup menu to Ctrl-Button2 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 selection-popup (enabled by default) 73 selection-popup (enabled by default)
52 Binds a popup menu to Ctrl-Button3 that lets you convert the 74 Binds a popup menu to Ctrl-Button3 that lets you convert the
53 selection text into various other formats/action. 75 selection text into various other formats/action (such as uri
76 unescaping, perl evalution, web-browser starting etc.), depending on
77 content.
54 78
55 digital-clock 79 searchable-scrollback<hotkey> (enabled by default)
56 Displays a digital clock using the built-in overlay. 80 Adds regex search functionality to the scrollback buffer, triggered
81 by a hotkey (default: "M-s"). While in search mode, normal terminal
82 input/output is suspended and a regex is displayed at the bottom of
83 the screen.
84
85 Inputting characters appends them to the regex and continues
86 incremental search. "BackSpace" removes a character from the regex,
87 "Up" and "Down" search upwards/downwards in the scrollback buffer,
88 "End" jumps to the bottom. "Escape" leaves search mode and returns
89 to the point where search was started, while "Enter" or "Return"
90 stay at the current position and additionally stores the first match
91 in the current line into the primary selection.
92
93 selection-autotransform
94 This selection allows you to do automatic transforms on a selection
95 whenever a selection is made.
96
97 It works by specifying perl snippets (most useful is a single "s///"
98 operator) that modify $_ as resources:
99
100 URxvt.selection-autotransform.0: transform
101 URxvt.selection-autotransform.1: transform
102 ...
103
104 For example, the following will transform selections of the form
105 "filename:number", often seen in compiler messages, into "vi
106 +$filename $word":
107
108 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
109
110 And this example matches the same,but replaces it with vi-commands
111 you can paste directly into your (vi :) editor:
112
113 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/\\x1b:e \\Q$1\\E\\x0d:$2\\x0d/
114
115 Of course, this can be modified to suit your needs and your editor
116 :)
117
118 To expand the example above to typical perl error messages ("XXX at
119 FILENAME line YYY."), you need a slightly more elaborate solution:
120
121 URxvt.selection.pattern-0: ( at .*? line \\d+\\.)
122 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)\\.$/\x1b:e \\Q$1\E\\x0d:$2\\x0d/
123
124 The first line tells the selection code to treat the unchanging part
125 of every error message as a selection pattern, and the second line
126 transforms the message into vi commands to load the file.
57 127
58 mark-urls 128 mark-urls
59 Uses per-line display filtering ("on_line_update") to underline 129 Uses per-line display filtering ("on_line_update") to underline urls
60 urls. 130 and make them clickable. When middle-clicked, the program specified
131 in the resource "urlLauncher" (default "x-www-browser") will be
132 started with the URL as first argument.
61 133
62 block-graphics-to-ascii 134 block-graphics-to-ascii
63 A not very useful example of filtering all text output to the 135 A not very useful example of filtering all text output to the
64 terminal, by replacing all line-drawing characters (U+2500 .. 136 terminal, by replacing all line-drawing characters (U+2500 ..
65 U+259F) by a similar-looking ascii character. 137 U+259F) by a similar-looking ascii character.
66 138
139 digital-clock
140 Displays a digital clock using the built-in overlay.
141
67 example-refresh-hooks 142 example-refresh-hooks
68 Displays a very simple digital clock in the upper right corner of 143 Displays a very simple digital clock in the upper right corner of
69 the window. Illustrates overwriting the refresh callbacks to create 144 the window. Illustrates overwriting the refresh callbacks to create
70 your own overlays or changes. 145 your own overlays or changes.
71 146
147API DOCUMENTATION
72 General API Considerations 148 General API Considerations
73 All objects (such as terminals, time watchers etc.) are typical 149 All objects (such as terminals, time watchers etc.) are typical
74 reference-to-hash objects. The hash can be used to store anything you 150 reference-to-hash objects. The hash can be used to store anything you
75 like. All members starting with an underscore (such as "_ptr" or 151 like. All members starting with an underscore (such as "_ptr" or
76 "_hook") are reserved for internal uses and MUST NOT be accessed or 152 "_hook") are reserved for internal uses and MUST NOT be accessed or
… …
84 Argument names also often indicate the type of a parameter. Here are 160 Argument names also often indicate the type of a parameter. Here are
85 some hints on what they mean: 161 some hints on what they mean:
86 162
87 $text 163 $text
88 Rxvt-unicodes special way of encoding text, where one "unicode" 164 Rxvt-unicodes special way of encoding text, where one "unicode"
89 character always represents one screen cell. See row_t for a 165 character always represents one screen cell. See ROW_t for a
90 discussion of this format. 166 discussion of this format.
91 167
92 $string 168 $string
93 A perl text string, with an emphasis on *text*. It can store all 169 A perl text string, with an emphasis on *text*. It can store all
94 unicode characters and is to be distinguished with text encoded in a 170 unicode characters and is to be distinguished with text encoded in a
… …
96 172
97 $octets 173 $octets
98 Either binary data or - more common - a text string encoded in a 174 Either binary data or - more common - a text string encoded in a
99 locale-specific way. 175 locale-specific way.
100 176
177 Extension Objects
178 Very perl extension is a perl class. A separate perl object is created
179 for each terminal and each extension and passed as the first parameter
180 to hooks. So extensions can use their $self object without having to
181 think about other extensions, with the exception of methods and members
182 that begin with an underscore character "_": these are reserved for
183 internal use.
184
185 Although it isn't a "urxvt::term" object, you can call all methods of
186 the "urxvt::term" class on this object.
187
188 It has the following methods and data members:
189
190 $urxvt_term = $self->{term}
191 Returns the "urxvt::term" object associated with this instance of
192 the extension. This member *must not* be changed in any way.
193
194 $self->enable ($hook_name => $cb, [$hook_name => $cb..])
195 Dynamically enable the given hooks (named without the "on_" prefix)
196 for this extension, replacing any previous hook. This is useful when
197 you want to overwrite time-critical hooks only temporarily.
198
199 $self->disable ($hook_name[, $hook_name..])
200 Dynamically disable the given hooks.
201
101 Hooks 202 Hooks
102 The following subroutines can be declared in extension files, and will 203 The following subroutines can be declared in extension files, and will
103 be called whenever the relevant event happens. 204 be called whenever the relevant event happens.
104 205
105 The first argument passed to them is an object private to each terminal 206 The first argument passed to them is an extension oject as described in
106 and extension package. You can call all "urxvt::term" methods on it, but 207 the in the "Extension Objects" section.
107 its not a real "urxvt::term" object. Instead, the real "urxvt::term"
108 object that is shared between all packages is stored in the "term"
109 member. It is, however, blessed intot he package of the extension
110 script, so for all practical purposes you can treat an extension script
111 as a class.
112 208
113 All of them must return a boolean value. If it is true, then the event 209 All of these hooks must return a boolean value. If it is true, then the
114 counts as being *consumed*, and the invocation of other hooks is 210 event counts as being *consumed*, and the invocation of other hooks is
115 skipped, and the relevant action might not be carried out by the C++ 211 skipped, and the relevant action might not be carried out by the C++
116 code. 212 code.
117 213
118 When in doubt, return a false value (preferably "()"). 214 *When in doubt, return a false value (preferably "()").*
119 215
120 on_init $term 216 on_init $term
121 Called after a new terminal object has been initialized, but before 217 Called after a new terminal object has been initialized, but before
122 windows are created or the command gets run. Most methods are unsafe 218 windows are created or the command gets run. Most methods are unsafe
123 to call or deliver senseless data, as terminal size and other 219 to call or deliver senseless data, as terminal size and other
… …
152 248
153 on_sel_extend $term 249 on_sel_extend $term
154 Called whenever the user tries to extend the selection (e.g. with a 250 Called whenever the user tries to extend the selection (e.g. with a
155 double click) and is either supposed to return false (normal 251 double click) and is either supposed to return false (normal
156 operation), or should extend the selection itelf and return true to 252 operation), or should extend the selection itelf and return true to
157 suppress the built-in processing. 253 suppress the built-in processing. This can happen multiple times, as
254 long as the callback returns true, it will be called on every
255 further click by the user and is supposed to enlarge the selection
256 more and more, if possible.
158 257
159 See the selection example extension. 258 See the selection example extension.
160 259
161 on_view_change $term, $offset 260 on_view_change $term, $offset
162 Called whenever the view offset changes, i..e the user or program 261 Called whenever the view offset changes, i..e the user or program
… …
189 argument. You can filter/change and output the text yourself by 288 argument. You can filter/change and output the text yourself by
190 returning a true value and calling "$term->scr_add_lines" yourself. 289 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 290 Please note that this might be very slow, however, as your hook is
192 called for all text being output. 291 called for all text being output.
193 292
293 on_tt_write $term, $octets
294 Called whenever some data is written to the tty/pty and can be used
295 to suppress or filter tty input.
296
194 on_line_update $term, $row 297 on_line_update $term, $row
195 Called whenever a line was updated or changed. Can be used to filter 298 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 299 screen output (e.g. underline urls or other useless stuff). Only
197 lines that are being shown will be filtered, and, due to performance 300 lines that are being shown will be filtered, and, due to performance
198 reasons, not always immediately. 301 reasons, not always immediately.
… …
217 on_keyboard_command $term, $string 320 on_keyboard_command $term, $string
218 Called whenever the user presses a key combination that has a 321 Called whenever the user presses a key combination that has a
219 "perl:string" action bound to it (see description of the keysym 322 "perl:string" action bound to it (see description of the keysym
220 resource in the rxvt(1) manpage). 323 resource in the rxvt(1) manpage).
221 324
325 on_x_event $term, $event
326 Called on every X event received on the vt window (and possibly
327 other windows). Should only be used as a last resort. Most event
328 structure members are not passed.
329
222 on_focus_in $term 330 on_focus_in $term
223 Called whenever the window gets the keyboard focus, before 331 Called whenever the window gets the keyboard focus, before
224 rxvt-unicode does focus in processing. 332 rxvt-unicode does focus in processing.
225 333
226 on_focus_out $term 334 on_focus_out $term
227 Called wheneever the window loses keyboard focus, before 335 Called wheneever the window loses keyboard focus, before
228 rxvt-unicode does focus out processing. 336 rxvt-unicode does focus out processing.
229 337
230 on_key_press $term, $event, $octets 338 on_key_press $term, $event, $keysym, $octets
231 on_key_release $term, $event 339 on_key_release $term, $event, $keysym
232 on_button_press $term, $event 340 on_button_press $term, $event
233 on_button_release $term, $event 341 on_button_release $term, $event
234 on_motion_notify $term, $event 342 on_motion_notify $term, $event
235 on_map_notify $term, $event 343 on_map_notify $term, $event
236 on_unmap_notify $term, $event 344 on_unmap_notify $term, $event
… …
246 output, if any, in locale-specific encoding. 354 output, if any, in locale-specific encoding.
247 355
248 subwindow. 356 subwindow.
249 357
250 Variables in the "urxvt" Package 358 Variables in the "urxvt" Package
359 $urxvt::LIBDIR
360 The rxvt-unicode library directory, where, among other things, the
361 perl modules and scripts are stored.
362
363 $urxvt::RESCLASS, $urxvt::RESCLASS
364 The resource class and name rxvt-unicode uses to look up X
365 resources.
366
367 $urxvt::RXVTNAME
368 The basename of the installed binaries, usually "urxvt".
369
251 $urxvt::TERM 370 $urxvt::TERM
252 The current terminal. This variable stores the current "urxvt::term" 371 The current terminal. This variable stores the current "urxvt::term"
253 object, whenever a callback/hook is executing. 372 object, whenever a callback/hook is executing.
254 373
255 Functions in the "urxvt" Package 374 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 375 urxvt::fatal $errormessage
265 Fatally aborts execution with the given error message. Avoid at all 376 Fatally aborts execution with the given error message. Avoid at all
266 costs! The only time this is acceptable is when the terminal process 377 costs! The only time this is acceptable is when the terminal process
267 starts up. 378 starts up.
268 379
… …
272 function that calls this function. 383 function that calls this function.
273 384
274 Using this function has the advantage that its output ends up in the 385 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. 386 correct place, e.g. on stderr of the connecting urxvtc client.
276 387
388 Messages have a size limit of 1023 bytes currently.
389
390 $is_safe = urxvt::safe
391 Returns true when it is safe to do potentially unsafe things, such
392 as evaluating perl code specified by the user. This is true when
393 urxvt was started setuid or setgid.
394
277 $time = urxvt::NOW 395 $time = urxvt::NOW
278 Returns the "current time" (as per the event loop). 396 Returns the "current time" (as per the event loop).
279 397
280 urxvt::CurrentTime 398 urxvt::CurrentTime
281 urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, 399 urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask,
282 Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask, 400 Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask,
283 Button5Mask, AnyModifier 401 Button5Mask, AnyModifier
402 urxvt::NoEventMask, KeyPressMask, KeyReleaseMask, ButtonPressMask,
403 ButtonReleaseMask, EnterWindowMask, LeaveWindowMask, PointerMotionMask,
404 PointerMotionHintMask, Button1MotionMask, Button2MotionMask,
405 Button3MotionMask, Button4MotionMask, Button5MotionMask,
406 ButtonMotionMask, KeymapStateMask, ExposureMask, VisibilityChangeMask,
407 StructureNotifyMask, ResizeRedirectMask, SubstructureNotifyMask,
408 SubstructureRedirectMask, FocusChangeMask, PropertyChangeMask,
409 ColormapChangeMask, OwnerGrabButtonMask
410 urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify,
411 EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose,
412 GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify, DestroyNotify,
413 UnmapNotify, MapNotify, MapRequest, ReparentNotify, ConfigureNotify,
414 ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify,
415 CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest,
416 SelectionNotify, ColormapNotify, ClientMessage, MappingNotify
284 Various constants for use in X calls and event processing. 417 Various constants for use in X calls and event processing.
285 418
286 RENDITION 419 RENDITION
287 Rendition bitsets contain information about colour, font, font styles 420 Rendition bitsets contain information about colour, font, font styles
288 and similar information for each screen cell. 421 and similar information for each screen cell.
… …
307 440
308 $foreground = urxvt::GET_BASEFG $rend 441 $foreground = urxvt::GET_BASEFG $rend
309 $background = urxvt::GET_BASEBG $rend 442 $background = urxvt::GET_BASEBG $rend
310 Return the foreground/background colour index, respectively. 443 Return the foreground/background colour index, respectively.
311 444
312 $rend = urxvt::SET_FGCOLOR ($rend, $new_colour) 445 $rend = urxvt::SET_FGCOLOR $rend, $new_colour
313 $rend = urxvt::SET_BGCOLOR ($rend, $new_colour) 446 $rend = urxvt::SET_BGCOLOR $rend, $new_colour
314 Replace the foreground/background colour in the rendition mask with 447 Replace the foreground/background colour in the rendition mask with
315 the specified one. 448 the specified one.
316 449
317 $value = urxvt::GET_CUSTOM ($rend) 450 $value = urxvt::GET_CUSTOM $rend
318 Return the "custom" value: Every rendition has 5 bits for use by 451 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 452 extensions. They can be set and changed as you like and are
320 initially zero. 453 initially zero.
321 454
322 $rend = urxvt::SET_CUSTOM ($rend, $new_value) 455 $rend = urxvt::SET_CUSTOM $rend, $new_value
323 Change the custom value. 456 Change the custom value.
324 457
325 The "urxvt::anyevent" Class 458 The "urxvt::anyevent" Class
326 The sole purpose of this class is to deliver an interface to the 459 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 460 "AnyEvent" module - any module using it will work inside urxvt without
328 further work. The only exception is that you cannot wait on condition 461 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 462 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. 463 is that you cannot use blocking APIs, but the non-blocking variant
464 should work.
331 465
332 The "urxvt::term" Class 466 The "urxvt::term" Class
467 $term = new urxvt::term $envhashref, $rxvtname, [arg...]
468 Creates a new terminal, very similar as if you had started it with
469 system "$rxvtname, arg...". $envhashref must be a reference to a
470 %ENV-like hash which defines the environment of the new terminal.
471
472 Croaks (and probably outputs an error message) if the new instance
473 couldn't be created. Returns "undef" if the new instance didn't
474 initialise perl, and the terminal object otherwise. The "init" and
475 "start" hooks will be called during this call.
476
333 $term->destroy 477 $term->destroy
334 Destroy the terminal object (close the window, free resources etc.). 478 Destroy the terminal object (close the window, free resources etc.).
479 Please note that rxvt will not exit as long as any event watchers
480 (timers, io watchers) are still active.
335 481
336 $isset = $term->option ($optval[, $set]) 482 $isset = $term->option ($optval[, $set])
337 Returns true if the option specified by $optval is enabled, and 483 Returns true if the option specified by $optval is enabled, and
338 optionally change it. All option values are stored by name in the 484 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 485 hash %urxvt::OPTION. Options not enabled in this binary are not in
… …
381 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 527 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
382 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 528 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
383 shade term_name title transparent transparent_all tripleclickwords 529 shade term_name title transparent transparent_all tripleclickwords
384 utmpInhibit visualBell 530 utmpInhibit visualBell
385 531
532 $value = $term->x_resource ($pattern)
533 Returns the X-Resource for the given pattern, excluding the program
534 or class name, i.e. "$term->x_resource ("boldFont")" should return
535 the same value as used by this instance of rxvt-unicode. Returns
536 "undef" if no resource with that pattern exists.
537
538 This method should only be called during the "on_start" hook, as
539 there is only one resource database per display, and later
540 invocations might return the wrong resources.
541
542 $success = $term->parse_keysym ($keysym_spec, $command_string)
543 Adds a keymap translation exactly as specified via a resource. See
544 the "keysym" resource in the rxvt(1) manpage.
545
386 $rend = $term->rstyle ([$new_rstyle]) 546 $rend = $term->rstyle ([$new_rstyle])
387 Return and optionally change the current rendition. Text that is 547 Return and optionally change the current rendition. Text that is
388 output by the terminal application will use this style. 548 output by the terminal application will use this style.
389 549
390 ($row, $col) = $term->screen_cur ([$row, $col]) 550 ($row, $col) = $term->screen_cur ([$row, $col])
… …
396 ($row, $col) = $term->selection_beg ([$row, $col]) 556 ($row, $col) = $term->selection_beg ([$row, $col])
397 ($row, $col) = $term->selection_end ([$row, $col]) 557 ($row, $col) = $term->selection_end ([$row, $col])
398 Return the current values of the selection mark, begin or end 558 Return the current values of the selection mark, begin or end
399 positions, and optionally set them to new values. 559 positions, and optionally set them to new values.
400 560
561 $term->selection_make ($eventtime[, $rectangular])
562 Tries to make a selection as set by "selection_beg" and
563 "selection_end". If $rectangular is true (default: false), a
564 rectangular selection will be made. This is the prefered function to
565 make a selection.
566
401 $success = $term->selection_grab ($eventtime) 567 $success = $term->selection_grab ($eventtime)
402 Try to request the primary selection from the server (for example, 568 Try to request the primary selection text from the server (for
403 as set by the next method). 569 example, as set by the next method). No visual feedback will be
570 given. This function is mostly useful from within "on_sel_grab"
571 hooks.
404 572
405 $oldtext = $term->selection ([$newtext]) 573 $oldtext = $term->selection ([$newtext])
406 Return the current selection text and optionally replace it by 574 Return the current selection text and optionally replace it by
407 $newtext. 575 $newtext.
408 576
409 #=item $term->overlay ($x, $y, $text) # #Create a simple multi-line 577 $term->overlay_simple ($x, $y, $text)
410 overlay box. See the next method for details. # #=cut # #sub 578 Create a simple multi-line overlay box. See the next method for
411 urxvt::term::scr_overlay { # my ($self, $x, $y, $text) = @_; # # my 579 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 580
417 $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 581 $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
418 Create a new (empty) overlay at the given position with the given 582 Create a new (empty) overlay at the given position with the given
419 width/height. $rstyle defines the initial rendition style (default: 583 width/height. $rstyle defines the initial rendition style (default:
420 "OVERLAY_RSTYLE"). 584 "OVERLAY_RSTYLE").
… …
454 Convert the given text string into the corresponding locale 618 Convert the given text string into the corresponding locale
455 encoding. 619 encoding.
456 620
457 $string = $term->locale_decode ($octets) 621 $string = $term->locale_decode ($octets)
458 Convert the given locale-encoded octets into a perl string. 622 Convert the given locale-encoded octets into a perl string.
623
624 $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
625 XORs the rendition values in the given span with the provided value
626 (default: "RS_RVid"), which *MUST NOT* contain font styles. Useful
627 in refresh hooks to provide effects similar to the selection.
628
629 $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[,
630 $rstyle2]])
631 Similar to "scr_xor_span", but xors a rectangle instead. Trailing
632 whitespace will additionally be xored with the $rstyle2, which
633 defaults to "RS_RVid | RS_Uline", which removes reverse video again
634 and underlines it instead. Both styles *MUST NOT* contain font
635 styles.
636
637 $term->scr_bell
638 Ring the bell!
459 639
460 $term->scr_add_lines ($string) 640 $term->scr_add_lines ($string)
461 Write the given text string to the screen, as if output by the 641 Write the given text string to the screen, as if output by the
462 application running inside the terminal. It may not contain command 642 application running inside the terminal. It may not contain command
463 sequences (escape codes), but is free to use line feeds, carriage 643 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). 657 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 658 To pass characters instead of octets, you should convert your
479 strings first to the locale-specific encoding using 659 strings first to the locale-specific encoding using
480 "$term->locale_encode". 660 "$term->locale_encode".
481 661
662 $old_events = $term->pty_ev_events ([$new_events])
663 Replaces the event mask of the pty watcher by the given event mask.
664 Can be used to suppress input and output handling to the pty/tty.
665 See the description of "urxvt::timer->events". Make sure to always
666 restore the previous value.
667
482 $windowid = $term->parent 668 $windowid = $term->parent
483 Return the window id of the toplevel window. 669 Return the window id of the toplevel window.
484 670
485 $windowid = $term->vt 671 $windowid = $term->vt
486 Return the window id of the terminal window. 672 Return the window id of the terminal window.
673
674 $term->vt_emask_add ($x_event_mask)
675 Adds the specified events to the vt event mask. Useful e.g. when you
676 want to receive pointer events all the times:
677
678 $term->vt_emask_add (urxvt::PointerMotionMask);
487 679
488 $window_width = $term->width 680 $window_width = $term->width
489 $window_height = $term->height 681 $window_height = $term->height
490 $font_width = $term->fwidth 682 $font_width = $term->fwidth
491 $font_height = $term->fheight 683 $font_height = $term->fheight
… …
494 $terminal_columns = $term->ncol 686 $terminal_columns = $term->ncol
495 $has_focus = $term->focus 687 $has_focus = $term->focus
496 $is_mapped = $term->mapped 688 $is_mapped = $term->mapped
497 $max_scrollback = $term->saveLines 689 $max_scrollback = $term->saveLines
498 $nrow_plus_saveLines = $term->total_rows 690 $nrow_plus_saveLines = $term->total_rows
499 $lines_in_scrollback = $term->nsaved 691 $topmost_scrollback_row = $term->top_row
500 Return various integers describing terminal characteristics. 692 Return various integers describing terminal characteristics.
693
694 $x_display = $term->display_id
695 Return the DISPLAY used by rxvt-unicode.
696
697 $lc_ctype = $term->locale
698 Returns the LC_CTYPE category string used by this rxvt-unicode.
699
700 $env = $term->env
701 Returns a copy of the environment in effect for the terminal as a
702 hashref similar to "\%ENV".
501 703
502 $modifiermask = $term->ModLevel3Mask 704 $modifiermask = $term->ModLevel3Mask
503 $modifiermask = $term->ModMetaMask 705 $modifiermask = $term->ModMetaMask
504 $modifiermask = $term->ModNumLockMask 706 $modifiermask = $term->ModNumLockMask
505 Return the modifier masks corresponding to the "ISO Level 3 Shift" 707 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 708 (often AltGr), the meta key (often Alt) and the num lock key, if
507 applicable. 709 applicable.
508 710
509 $view_start = $term->view_start ([$newvalue]) 711 $view_start = $term->view_start ([$newvalue])
510 Returns the negative row number of the topmost line. Minimum value 712 Returns the row number of the topmost displayed line. Maximum value
511 is 0, which displays the normal terminal contents. Larger values 713 is 0, which displays the normal terminal contents. Lower values
512 scroll this many lines into the scrollback buffer. 714 scroll this many lines into the scrollback buffer.
513 715
514 $term->want_refresh 716 $term->want_refresh
515 Requests a screen refresh. At the next opportunity, rxvt-unicode 717 Requests a screen refresh. At the next opportunity, rxvt-unicode
516 will compare the on-screen display with its stored representation. 718 will compare the on-screen display with its stored representation.
… …
584 Return the row number of the first/last row of the line, 786 Return the row number of the first/last row of the line,
585 respectively. 787 respectively.
586 788
587 $offset = $line->offset_of ($row, $col) 789 $offset = $line->offset_of ($row, $col)
588 Returns the character offset of the given row|col pair within 790 Returns the character offset of the given row|col pair within
589 the logical line. 791 the logical line. Works for rows outside the line, too, and
792 returns corresponding offsets outside the string.
590 793
591 ($row, $col) = $line->coord_of ($offset) 794 ($row, $col) = $line->coord_of ($offset)
592 Translates a string offset into terminal coordinates again. 795 Translates a string offset into terminal coordinates again.
593 796
594 $text = $term->special_encode $string 797 $text = $term->special_encode $string
… …
599 $string = $term->special_decode $text 802 $string = $term->special_decode $text
600 Converts rxvt-unicodes text reprsentation into a perl string. See 803 Converts rxvt-unicodes text reprsentation into a perl string. See
601 "$term->ROW_t" for details. 804 "$term->ROW_t" for details.
602 805
603 $success = $term->grab_button ($button, $modifiermask) 806 $success = $term->grab_button ($button, $modifiermask)
604 Registers a synchronous button grab. See XGrabButton. 807 Registers a synchronous button grab. See the XGrabButton manpage.
605 808
606 $success = $term->grab ($eventtime[, $sync]) 809 $success = $term->grab ($eventtime[, $sync])
607 Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 810 Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
608 synchronous ($sync is true). Also remembers the grab timestampe. 811 synchronous ($sync is true). Also remembers the grab timestampe.
609 812
… …
621 Calls XUngrab for the most recent grab. Is called automatically on 824 Calls XUngrab for the most recent grab. Is called automatically on
622 evaluation errors, as it is better to lose the grab in the error 825 evaluation errors, as it is better to lose the grab in the error
623 case as the session. 826 case as the session.
624 827
625 The "urxvt::popup" Class 828 The "urxvt::popup" Class
829 $popup->add_title ($title)
830 Adds a non-clickable title to the popup.
831
832 $popup->add_separator ([$sepchr])
833 Creates a separator, optionally using the character given as
834 $sepchr.
835
836 $popup->add_button ($text, $cb)
837 Adds a clickable button to the popup. $cb is called whenever it is
838 selected.
839
840 $popup->add_toggle ($text, $cb, $initial_value)
841 Adds a toggle/checkbox item to the popup. Teh callback gets called
842 whenever it gets toggled, with a boolean indicating its value as its
843 first argument.
844
845 $popup->show
846 Displays the popup (which is initially hidden).
847
626 The "urxvt::timer" Class 848 The "urxvt::timer" Class
627 This class implements timer watchers/events. Time is represented as 849 This class implements timer watchers/events. Time is represented as a
628 a fractional number of seconds since the epoch. Example: 850 fractional number of seconds since the epoch. Example:
629 851
630 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0); 852 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
631 $term->{timer} = urxvt::timer 853 $term->{timer} = urxvt::timer
632 ->new 854 ->new
633 ->interval (1) 855 ->interval (1)
634 ->cb (sub { 856 ->cb (sub {
635 $term->{overlay}->set (0, 0, 857 $term->{overlay}->set (0, 0,
636 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]); 858 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
637 }); 859 });
638 860
639 $timer = new urxvt::timer 861 $timer = new urxvt::timer
640 Create a new timer object in started state. It is scheduled to 862 Create a new timer object in started state. It is scheduled to fire
641 fire immediately. 863 immediately.
642 864
643 $timer = $timer->cb (sub { my ($timer) = @_; ... }) 865 $timer = $timer->cb (sub { my ($timer) = @_; ... })
644 Set the callback to be called when the timer triggers. 866 Set the callback to be called when the timer triggers.
645 867
646 $tstamp = $timer->at 868 $tstamp = $timer->at
647 Return the time this watcher will fire next. 869 Return the time this watcher will fire next.
648 870
649 $timer = $timer->set ($tstamp) 871 $timer = $timer->set ($tstamp)
650 Set the time the event is generated to $tstamp. 872 Set the time the event is generated to $tstamp.
651 873
652 $timer = $timer->interval ($interval) 874 $timer = $timer->interval ($interval)
653 Normally (and when $interval is 0), the timer will automatically 875 Normally (and when $interval is 0), the timer will automatically
654 stop after it has fired once. If $interval is non-zero, then the 876 stop after it has fired once. If $interval is non-zero, then the
655 timer is automatically rescheduled at the given intervals. 877 timer is automatically rescheduled at the given intervals.
656 878
657 $timer = $timer->start 879 $timer = $timer->start
658 Start the timer. 880 Start the timer.
659 881
660 $timer = $timer->start ($tstamp) 882 $timer = $timer->start ($tstamp)
661 Set the event trigger time to $tstamp and start the timer. 883 Set the event trigger time to $tstamp and start the timer.
662 884
663 $timer = $timer->stop 885 $timer = $timer->stop
664 Stop the timer. 886 Stop the timer.
665 887
666 The "urxvt::iow" Class 888 The "urxvt::iow" Class
667 This class implements io watchers/events. Example: 889 This class implements io watchers/events. Example:
668 890
669 $term->{socket} = ... 891 $term->{socket} = ...
670 $term->{iow} = urxvt::iow 892 $term->{iow} = urxvt::iow
671 ->new 893 ->new
672 ->fd (fileno $term->{socket}) 894 ->fd (fileno $term->{socket})
673 ->events (1) # wait for read data 895 ->events (urxvt::EVENT_READ)
674 ->start 896 ->start
675 ->cb (sub { 897 ->cb (sub {
676 my ($iow, $revents) = @_; 898 my ($iow, $revents) = @_;
677 # $revents must be 1 here, no need to check 899 # $revents must be 1 here, no need to check
678 sysread $term->{socket}, my $buf, 8192 900 sysread $term->{socket}, my $buf, 8192
679 or end-of-file; 901 or end-of-file;
680 }); 902 });
681 903
682 $iow = new urxvt::iow 904 $iow = new urxvt::iow
683 Create a new io watcher object in stopped state. 905 Create a new io watcher object in stopped state.
684 906
685 $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... }) 907 $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
686 Set the callback to be called when io events are triggered. 908 Set the callback to be called when io events are triggered.
687 $reventmask is a bitset as described in the "events" method. 909 $reventmask is a bitset as described in the "events" method.
688 910
689 $iow = $iow->fd ($fd) 911 $iow = $iow->fd ($fd)
690 Set the filedescriptor (not handle) to watch. 912 Set the filedescriptor (not handle) to watch.
691 913
692 $iow = $iow->events ($eventmask) 914 $iow = $iow->events ($eventmask)
693 Set the event mask to watch. Bit #0 (value 1) enables watching 915 Set the event mask to watch. The only allowed values are
694 for read data, Bit #1 (value 2) enables watching for write data. 916 "urxvt::EVENT_READ" and "urxvt::EVENT_WRITE", which might be ORed
917 together, or "urxvt::EVENT_NONE".
695 918
696 $iow = $iow->start 919 $iow = $iow->start
697 Start watching for requested events on the given handle. 920 Start watching for requested events on the given handle.
698 921
699 $iow = $iow->stop 922 $iow = $iow->stop
700 Stop watching for events on the given filehandle. 923 Stop watching for events on the given filehandle.
701 924
702ENVIRONMENT 925ENVIRONMENT
703 URXVT_PERL_VERBOSITY 926 URXVT_PERL_VERBOSITY
704 This variable controls the verbosity level of the perl extension. 927 This variable controls the verbosity level of the perl extension. Higher
705 Higher numbers indicate more verbose output. 928 numbers indicate more verbose output.
706 929
707 == 0 - fatal messages 930 == 0 - fatal messages
708 >= 3 - script loading and management 931 >= 3 - script loading and management
709 >=10 - all events received 932 >=10 - all called hooks
933 >=11 - hook reutrn values
710 934
711AUTHOR 935AUTHOR
712 Marc Lehmann <pcg@goof.com> 936 Marc Lehmann <pcg@goof.com>
713 http://software.schmorp.de/pkg/rxvt-unicode 937 http://software.schmorp.de/pkg/rxvt-unicode
714 938

Diff Legend

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