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.26 by root, Fri Jan 13 01:09:37 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
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 searchable-scrollback<hotkey> (enabled by default)
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/^(\\S+):(\\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/^(S+):(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.
53 127
54 mark-urls 128 mark-urls
55 Uses per-line display filtering ("on_line_update") to underline 129 Uses per-line display filtering ("on_line_update") to underline urls
56 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.
57 133
58 block-graphics-to-ascii 134 block-graphics-to-ascii
59 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
60 terminal, by replacing all line-drawing characters (U+2500 .. 136 terminal, by replacing all line-drawing characters (U+2500 ..
61 U+259F) by a similar-looking ascii character. 137 U+259F) by a similar-looking ascii character.
62 138
139 digital-clock
140 Displays a digital clock using the built-in overlay.
141
63 example-refresh-hooks 142 example-refresh-hooks
64 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
65 the window. Illustrates overwriting the refresh callbacks to create 144 the window. Illustrates overwriting the refresh callbacks to create
66 your own overlays or changes. 145 your own overlays or changes.
67 146
147API DOCUMENTATION
68 General API Considerations 148 General API Considerations
69 All objects (such as terminals, time watchers etc.) are typical 149 All objects (such as terminals, time watchers etc.) are typical
70 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
71 like. All members starting with an underscore (such as "_ptr" or 151 like. All members starting with an underscore (such as "_ptr" or
72 "_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
… …
80 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
81 some hints on what they mean: 161 some hints on what they mean:
82 162
83 $text 163 $text
84 Rxvt-unicodes special way of encoding text, where one "unicode" 164 Rxvt-unicodes special way of encoding text, where one "unicode"
85 character always represents one screen cell. See row_t for a 165 character always represents one screen cell. See ROW_t for a
86 discussion of this format. 166 discussion of this format.
87 167
88 $string 168 $string
89 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
90 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
… …
92 172
93 $octets 173 $octets
94 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
95 locale-specific way. 175 locale-specific way.
96 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
97 Hooks 202 Hooks
98 The following subroutines can be declared in extension files, and will 203 The following subroutines can be declared in extension files, and will
99 be called whenever the relevant event happens. 204 be called whenever the relevant event happens.
100 205
101 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
102 and extension package. You can call all "urxvt::term" methods on it, but 207 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 208
109 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
110 counts as being *consumed*, and the invocation of other hooks is 210 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++ 211 skipped, and the relevant action might not be carried out by the C++
112 code. 212 code.
113 213
114 When in doubt, return a false value (preferably "()"). 214 *When in doubt, return a false value (preferably "()").*
115 215
116 on_init $term 216 on_init $term
117 Called after a new terminal object has been initialized, but before 217 Called after a new terminal object has been initialized, but before
118 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
119 to call or deliver senseless data, as terminal size and other 219 to call or deliver senseless data, as terminal size and other
… …
148 248
149 on_sel_extend $term 249 on_sel_extend $term
150 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
151 double click) and is either supposed to return false (normal 251 double click) and is either supposed to return false (normal
152 operation), or should extend the selection itelf and return true to 252 operation), or should extend the selection itelf and return true to
153 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.
154 257
155 See the selection example extension. 258 See the selection example extension.
156 259
157 on_view_change $term, $offset 260 on_view_change $term, $offset
158 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
… …
165 may be larger than the scroll back buffer or the terminal. 268 may be larger than the scroll back buffer or the terminal.
166 269
167 It is called before lines are scrolled out (so rows 0 .. min ($lines 270 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 271 - 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. 272 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 273
175 on_osc_seq $term, $string 274 on_osc_seq $term, $string
176 Called whenever the ESC ] 777 ; string ST command sequence (OSC = 275 Called whenever the ESC ] 777 ; string ST command sequence (OSC =
177 operating system command) is processed. Cursor position and other 276 operating system command) is processed. Cursor position and other
178 state information is up-to-date when this happens. For 277 state information is up-to-date when this happens. For
… …
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.
… …
225 328
226 on_focus_out $term 329 on_focus_out $term
227 Called wheneever the window loses keyboard focus, before 330 Called wheneever the window loses keyboard focus, before
228 rxvt-unicode does focus out processing. 331 rxvt-unicode does focus out processing.
229 332
230 on_key_press $term, $event, $octets 333 on_key_press $term, $event, $keysym, $octets
231 on_key_release $term, $event 334 on_key_release $term, $event, $keysym
232 on_button_press $term, $event 335 on_button_press $term, $event
233 on_button_release $term, $event 336 on_button_release $term, $event
234 on_motion_notify $term, $event 337 on_motion_notify $term, $event
235 on_map_notify $term, $event 338 on_map_notify $term, $event
236 on_unmap_notify $term, $event 339 on_unmap_notify $term, $event
… …
246 output, if any, in locale-specific encoding. 349 output, if any, in locale-specific encoding.
247 350
248 subwindow. 351 subwindow.
249 352
250 Variables in the "urxvt" Package 353 Variables in the "urxvt" Package
354 $urxvt::LIBDIR
355 The rxvt-unicode library directory, where, among other things, the
356 perl modules and scripts are stored.
357
358 $urxvt::RESCLASS, $urxvt::RESCLASS
359 The resource class and name rxvt-unicode uses to look up X
360 resources.
361
362 $urxvt::RXVTNAME
363 The basename of the installed binaries, usually "urxvt".
364
251 $urxvt::TERM 365 $urxvt::TERM
252 The current terminal. This variable stores the current "urxvt::term" 366 The current terminal. This variable stores the current "urxvt::term"
253 object, whenever a callback/hook is executing. 367 object, whenever a callback/hook is executing.
254 368
255 Functions in the "urxvt" Package 369 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 370 urxvt::fatal $errormessage
265 Fatally aborts execution with the given error message. Avoid at all 371 Fatally aborts execution with the given error message. Avoid at all
266 costs! The only time this is acceptable is when the terminal process 372 costs! The only time this is acceptable is when the terminal process
267 starts up. 373 starts up.
268 374
… …
271 newline. The module also overwrites the "warn" builtin with a 377 newline. The module also overwrites the "warn" builtin with a
272 function that calls this function. 378 function that calls this function.
273 379
274 Using this function has the advantage that its output ends up in the 380 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. 381 correct place, e.g. on stderr of the connecting urxvtc client.
382
383 Messages have a size limit of 1023 bytes currently.
384
385 $is_safe = urxvt::safe
386 Returns true when it is safe to do potentially unsafe things, such
387 as evaluating perl code specified by the user. This is true when
388 urxvt was started setuid or setgid.
276 389
277 $time = urxvt::NOW 390 $time = urxvt::NOW
278 Returns the "current time" (as per the event loop). 391 Returns the "current time" (as per the event loop).
279 392
280 urxvt::CurrentTime 393 urxvt::CurrentTime
… …
307 420
308 $foreground = urxvt::GET_BASEFG $rend 421 $foreground = urxvt::GET_BASEFG $rend
309 $background = urxvt::GET_BASEBG $rend 422 $background = urxvt::GET_BASEBG $rend
310 Return the foreground/background colour index, respectively. 423 Return the foreground/background colour index, respectively.
311 424
312 $rend = urxvt::SET_FGCOLOR ($rend, $new_colour) 425 $rend = urxvt::SET_FGCOLOR $rend, $new_colour
313 $rend = urxvt::SET_BGCOLOR ($rend, $new_colour) 426 $rend = urxvt::SET_BGCOLOR $rend, $new_colour
314 Replace the foreground/background colour in the rendition mask with 427 Replace the foreground/background colour in the rendition mask with
315 the specified one. 428 the specified one.
316 429
317 $value = urxvt::GET_CUSTOM ($rend) 430 $value = urxvt::GET_CUSTOM $rend
318 Return the "custom" value: Every rendition has 5 bits for use by 431 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 432 extensions. They can be set and changed as you like and are
320 initially zero. 433 initially zero.
321 434
322 $rend = urxvt::SET_CUSTOM ($rend, $new_value) 435 $rend = urxvt::SET_CUSTOM $rend, $new_value
323 Change the custom value. 436 Change the custom value.
324 437
325 The "urxvt::anyevent" Class 438 The "urxvt::anyevent" Class
326 The sole purpose of this class is to deliver an interface to the 439 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 440 "AnyEvent" module - any module using it will work inside urxvt without
328 further work. The only exception is that you cannot wait on condition 441 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 442 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. 443 is that you cannot use blocking APIs, but the non-blocking variant
444 should work.
331 445
332 The "urxvt::term" Class 446 The "urxvt::term" Class
447 $term = new urxvt::term $envhashref, $rxvtname, [arg...]
448 Creates a new terminal, very similar as if you had started it with
449 system "$rxvtname, arg...". $envhashref must be a reference to a
450 %ENV-like hash which defines the environment of the new terminal.
451
452 Croaks (and probably outputs an error message) if the new instance
453 couldn't be created. Returns "undef" if the new instance didn't
454 initialise perl, and the terminal object otherwise. The "init" and
455 "start" hooks will be called during this call.
456
333 $term->destroy 457 $term->destroy
334 Destroy the terminal object (close the window, free resources etc.). 458 Destroy the terminal object (close the window, free resources etc.).
459 Please note that rxvt will not exit as long as any event watchers
460 (timers, io watchers) are still active.
335 461
336 $isset = $term->option ($optval[, $set]) 462 $isset = $term->option ($optval[, $set])
337 Returns true if the option specified by $optval is enabled, and 463 Returns true if the option specified by $optval is enabled, and
338 optionally change it. All option values are stored by name in the 464 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 465 hash %urxvt::OPTION. Options not enabled in this binary are not in
… …
381 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 507 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
382 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 508 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
383 shade term_name title transparent transparent_all tripleclickwords 509 shade term_name title transparent transparent_all tripleclickwords
384 utmpInhibit visualBell 510 utmpInhibit visualBell
385 511
512 $value = $term->x_resource ($pattern)
513 Returns the X-Resource for the given pattern, excluding the program
514 or class name, i.e. "$term->x_resource ("boldFont")" should return
515 the same value as used by this instance of rxvt-unicode. Returns
516 "undef" if no resource with that pattern exists.
517
518 This method should only be called during the "on_start" hook, as
519 there is only one resource database per display, and later
520 invocations might return the wrong resources.
521
522 $success = $term->parse_keysym ($keysym_spec, $command_string)
523 Adds a keymap translation exactly as specified via a resource. See
524 the "keysym" resource in the rxvt(1) manpage.
525
386 $rend = $term->rstyle ([$new_rstyle]) 526 $rend = $term->rstyle ([$new_rstyle])
387 Return and optionally change the current rendition. Text that is 527 Return and optionally change the current rendition. Text that is
388 output by the terminal application will use this style. 528 output by the terminal application will use this style.
389 529
390 ($row, $col) = $term->screen_cur ([$row, $col]) 530 ($row, $col) = $term->screen_cur ([$row, $col])
… …
396 ($row, $col) = $term->selection_beg ([$row, $col]) 536 ($row, $col) = $term->selection_beg ([$row, $col])
397 ($row, $col) = $term->selection_end ([$row, $col]) 537 ($row, $col) = $term->selection_end ([$row, $col])
398 Return the current values of the selection mark, begin or end 538 Return the current values of the selection mark, begin or end
399 positions, and optionally set them to new values. 539 positions, and optionally set them to new values.
400 540
541 $term->selection_make ($eventtime[, $rectangular])
542 Tries to make a selection as set by "selection_beg" and
543 "selection_end". If $rectangular is true (default: false), a
544 rectangular selection will be made. This is the prefered function to
545 make a selection.
546
401 $success = $term->selection_grab ($eventtime) 547 $success = $term->selection_grab ($eventtime)
402 Try to request the primary selection from the server (for example, 548 Try to request the primary selection text from the server (for
403 as set by the next method). 549 example, as set by the next method). No visual feedback will be
550 given. This function is mostly useful from within "on_sel_grab"
551 hooks.
404 552
405 $oldtext = $term->selection ([$newtext]) 553 $oldtext = $term->selection ([$newtext])
406 Return the current selection text and optionally replace it by 554 Return the current selection text and optionally replace it by
407 $newtext. 555 $newtext.
408 556
409 #=item $term->overlay ($x, $y, $text) # #Create a simple multi-line 557 $term->overlay_simple ($x, $y, $text)
410 overlay box. See the next method for details. # #=cut # #sub 558 Create a simple multi-line overlay box. See the next method for
411 urxvt::term::scr_overlay { # my ($self, $x, $y, $text) = @_; # # my 559 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 560
417 $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 561 $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
418 Create a new (empty) overlay at the given position with the given 562 Create a new (empty) overlay at the given position with the given
419 width/height. $rstyle defines the initial rendition style (default: 563 width/height. $rstyle defines the initial rendition style (default:
420 "OVERLAY_RSTYLE"). 564 "OVERLAY_RSTYLE").
… …
454 Convert the given text string into the corresponding locale 598 Convert the given text string into the corresponding locale
455 encoding. 599 encoding.
456 600
457 $string = $term->locale_decode ($octets) 601 $string = $term->locale_decode ($octets)
458 Convert the given locale-encoded octets into a perl string. 602 Convert the given locale-encoded octets into a perl string.
603
604 $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
605 XORs the rendition values in the given span with the provided value
606 (default: "RS_RVid"), which *MUST NOT* contain font styles. Useful
607 in refresh hooks to provide effects similar to the selection.
608
609 $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[,
610 $rstyle2]])
611 Similar to "scr_xor_span", but xors a rectangle instead. Trailing
612 whitespace will additionally be xored with the $rstyle2, which
613 defaults to "RS_RVid | RS_Uline", which removes reverse video again
614 and underlines it instead. Both styles *MUST NOT* contain font
615 styles.
616
617 $term->scr_bell
618 Ring the bell!
459 619
460 $term->scr_add_lines ($string) 620 $term->scr_add_lines ($string)
461 Write the given text string to the screen, as if output by the 621 Write the given text string to the screen, as if output by the
462 application running inside the terminal. It may not contain command 622 application running inside the terminal. It may not contain command
463 sequences (escape codes), but is free to use line feeds, carriage 623 sequences (escape codes), but is free to use line feeds, carriage
… …
476 $term->tt_write ($octets) 636 $term->tt_write ($octets)
477 Write the octets given in $data to the tty (i.e. as program input). 637 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 638 To pass characters instead of octets, you should convert your
479 strings first to the locale-specific encoding using 639 strings first to the locale-specific encoding using
480 "$term->locale_encode". 640 "$term->locale_encode".
641
642 $old_events = $term->pty_ev_events ([$new_events])
643 Replaces the event mask of the pty watcher by the given event mask.
644 Can be used to suppress input and output handling to the pty/tty.
645 See the description of "urxvt::timer->events". Make sure to always
646 restore the previous value.
481 647
482 $windowid = $term->parent 648 $windowid = $term->parent
483 Return the window id of the toplevel window. 649 Return the window id of the toplevel window.
484 650
485 $windowid = $term->vt 651 $windowid = $term->vt
… …
497 $max_scrollback = $term->saveLines 663 $max_scrollback = $term->saveLines
498 $nrow_plus_saveLines = $term->total_rows 664 $nrow_plus_saveLines = $term->total_rows
499 $lines_in_scrollback = $term->nsaved 665 $lines_in_scrollback = $term->nsaved
500 Return various integers describing terminal characteristics. 666 Return various integers describing terminal characteristics.
501 667
668 $x_display = $term->display_id
669 Return the DISPLAY used by rxvt-unicode.
670
671 $lc_ctype = $term->locale
672 Returns the LC_CTYPE category string used by this rxvt-unicode.
673
674 $env = $term->env
675 Returns a copy of the environment in effect for the terminal as a
676 hashref similar to "\%ENV".
677
502 $modifiermask = $term->ModLevel3Mask 678 $modifiermask = $term->ModLevel3Mask
503 $modifiermask = $term->ModMetaMask 679 $modifiermask = $term->ModMetaMask
504 $modifiermask = $term->ModNumLockMask 680 $modifiermask = $term->ModNumLockMask
505 Return the modifier masks corresponding to the "ISO Level 3 Shift" 681 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 682 (often AltGr), the meta key (often Alt) and the num lock key, if
… …
584 Return the row number of the first/last row of the line, 760 Return the row number of the first/last row of the line,
585 respectively. 761 respectively.
586 762
587 $offset = $line->offset_of ($row, $col) 763 $offset = $line->offset_of ($row, $col)
588 Returns the character offset of the given row|col pair within 764 Returns the character offset of the given row|col pair within
589 the logical line. 765 the logical line. Works for rows outside the line, too, and
766 returns corresponding offsets outside the string.
590 767
591 ($row, $col) = $line->coord_of ($offset) 768 ($row, $col) = $line->coord_of ($offset)
592 Translates a string offset into terminal coordinates again. 769 Translates a string offset into terminal coordinates again.
593 770
594 ($row, $col) = $line->coord_of ($offset) =item $text =
595 $term->special_encode $string 771 $text = $term->special_encode $string
596 Converts a perl string into the special encoding used by 772 Converts a perl string into the special encoding used by
597 rxvt-unicode, where one character corresponds to one screen cell. 773 rxvt-unicode, where one character corresponds to one screen cell.
598 See "$term->ROW_t" for details. 774 See "$term->ROW_t" for details.
599 775
600 $string = $term->special_decode $text 776 $string = $term->special_decode $text
601 Converts rxvt-unicodes text reprsentation into a perl string. See 777 Converts rxvt-unicodes text reprsentation into a perl string. See
602 "$term->ROW_t" for details. 778 "$term->ROW_t" for details.
603 779
780 $success = $term->grab_button ($button, $modifiermask)
781 Registers a synchronous button grab. See the XGrabButton manpage.
782
783 $success = $term->grab ($eventtime[, $sync])
784 Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
785 synchronous ($sync is true). Also remembers the grab timestampe.
786
787 $term->allow_events_async
788 Calls XAllowEvents with AsyncBoth for the most recent grab.
789
790 $term->allow_events_sync
791 Calls XAllowEvents with SyncBoth for the most recent grab.
792
793 $term->allow_events_replay
794 Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for
795 the most recent grab.
796
797 $term->ungrab
798 Calls XUngrab for the most recent grab. Is called automatically on
799 evaluation errors, as it is better to lose the grab in the error
800 case as the session.
801
604 The "urxvt::popup" Class 802 The "urxvt::popup" Class
803 $popup->add_title ($title)
804 Adds a non-clickable title to the popup.
805
806 $popup->add_separator ([$sepchr])
807 Creates a separator, optionally using the character given as
808 $sepchr.
809
810 $popup->add_button ($text, $cb)
811 Adds a clickable button to the popup. $cb is called whenever it is
812 selected.
813
814 $popup->add_toggle ($text, $cb, $initial_value)
815 Adds a toggle/checkbox item to the popup. Teh callback gets called
816 whenever it gets toggled, with a boolean indicating its value as its
817 first argument.
818
819 $popup->show
820 Displays the popup (which is initially hidden).
821
605 The "urxvt::timer" Class 822 The "urxvt::timer" Class
606 This class implements timer watchers/events. Time is represented as 823 This class implements timer watchers/events. Time is represented as a
607 a fractional number of seconds since the epoch. Example: 824 fractional number of seconds since the epoch. Example:
608 825
609 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0); 826 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
610 $term->{timer} = urxvt::timer 827 $term->{timer} = urxvt::timer
611 ->new 828 ->new
612 ->interval (1) 829 ->interval (1)
613 ->cb (sub { 830 ->cb (sub {
614 $term->{overlay}->set (0, 0, 831 $term->{overlay}->set (0, 0,
615 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]); 832 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
616 }); 833 });
617 834
618 $timer = new urxvt::timer 835 $timer = new urxvt::timer
619 Create a new timer object in started state. It is scheduled to 836 Create a new timer object in started state. It is scheduled to fire
620 fire immediately. 837 immediately.
621 838
622 $timer = $timer->cb (sub { my ($timer) = @_; ... }) 839 $timer = $timer->cb (sub { my ($timer) = @_; ... })
623 Set the callback to be called when the timer triggers. 840 Set the callback to be called when the timer triggers.
624 841
625 $tstamp = $timer->at 842 $tstamp = $timer->at
626 Return the time this watcher will fire next. 843 Return the time this watcher will fire next.
627 844
628 $timer = $timer->set ($tstamp) 845 $timer = $timer->set ($tstamp)
629 Set the time the event is generated to $tstamp. 846 Set the time the event is generated to $tstamp.
630 847
631 $timer = $timer->interval ($interval) 848 $timer = $timer->interval ($interval)
632 Normally (and when $interval is 0), the timer will automatically 849 Normally (and when $interval is 0), the timer will automatically
633 stop after it has fired once. If $interval is non-zero, then the 850 stop after it has fired once. If $interval is non-zero, then the
634 timer is automatically rescheduled at the given intervals. 851 timer is automatically rescheduled at the given intervals.
635 852
636 $timer = $timer->start 853 $timer = $timer->start
637 Start the timer. 854 Start the timer.
638 855
639 $timer = $timer->start ($tstamp) 856 $timer = $timer->start ($tstamp)
640 Set the event trigger time to $tstamp and start the timer. 857 Set the event trigger time to $tstamp and start the timer.
641 858
642 $timer = $timer->stop 859 $timer = $timer->stop
643 Stop the timer. 860 Stop the timer.
644 861
645 The "urxvt::iow" Class 862 The "urxvt::iow" Class
646 This class implements io watchers/events. Example: 863 This class implements io watchers/events. Example:
647 864
648 $term->{socket} = ... 865 $term->{socket} = ...
649 $term->{iow} = urxvt::iow 866 $term->{iow} = urxvt::iow
650 ->new 867 ->new
651 ->fd (fileno $term->{socket}) 868 ->fd (fileno $term->{socket})
652 ->events (1) # wait for read data 869 ->events (urxvt::EVENT_READ)
653 ->start 870 ->start
654 ->cb (sub { 871 ->cb (sub {
655 my ($iow, $revents) = @_; 872 my ($iow, $revents) = @_;
656 # $revents must be 1 here, no need to check 873 # $revents must be 1 here, no need to check
657 sysread $term->{socket}, my $buf, 8192 874 sysread $term->{socket}, my $buf, 8192
658 or end-of-file; 875 or end-of-file;
659 }); 876 });
660 877
661 $iow = new urxvt::iow 878 $iow = new urxvt::iow
662 Create a new io watcher object in stopped state. 879 Create a new io watcher object in stopped state.
663 880
664 $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... }) 881 $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
665 Set the callback to be called when io events are triggered. 882 Set the callback to be called when io events are triggered.
666 $reventmask is a bitset as described in the "events" method. 883 $reventmask is a bitset as described in the "events" method.
667 884
668 $iow = $iow->fd ($fd) 885 $iow = $iow->fd ($fd)
669 Set the filedescriptor (not handle) to watch. 886 Set the filedescriptor (not handle) to watch.
670 887
671 $iow = $iow->events ($eventmask) 888 $iow = $iow->events ($eventmask)
672 Set the event mask to watch. Bit #0 (value 1) enables watching 889 Set the event mask to watch. The only allowed values are
673 for read data, Bit #1 (value 2) enables watching for write data. 890 "urxvt::EVENT_READ" and "urxvt::EVENT_WRITE", which might be ORed
891 together, or "urxvt::EVENT_NONE".
674 892
675 $iow = $iow->start 893 $iow = $iow->start
676 Start watching for requested events on the given handle. 894 Start watching for requested events on the given handle.
677 895
678 $iow = $iow->stop 896 $iow = $iow->stop
679 Stop watching for events on the given filehandle. 897 Stop watching for events on the given filehandle.
680 898
681ENVIRONMENT 899ENVIRONMENT
682 URXVT_PERL_VERBOSITY 900 URXVT_PERL_VERBOSITY
683 This variable controls the verbosity level of the perl extension. 901 This variable controls the verbosity level of the perl extension. Higher
684 Higher numbers indicate more verbose output. 902 numbers indicate more verbose output.
685 903
686 =0 - only fatal messages 904 == 0 - fatal messages
687 =3 - script loading and management 905 >= 3 - script loading and management
688 =10 - all events received 906 >=10 - all called hooks
907 >=11 - hook reutrn values
689 908
690AUTHOR 909AUTHOR
691 Marc Lehmann <pcg@goof.com> 910 Marc Lehmann <pcg@goof.com>
692 http://software.schmorp.de/pkg/rxvt-unicode 911 http://software.schmorp.de/pkg/rxvt-unicode
693 912

Diff Legend

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