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.22 by root, Wed Jan 11 02:13:56 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). Right
37 to select urls and complete shell-quoted arguments, which is very 37 now, it tries to select urls and complete shell-quoted arguments,
38 convenient, too, if your ls supports "--quoting-style=shell". 38 which is very convenient, too, if your ls supports
39 "--quoting-style=shell".
39 40
40 It also offers the following bindable event: 41 It also offers the following bindable keyboard command:
41 42
42 rot13 43 rot13
43 Rot-13 the selection when activated. Used via keyboard trigger: 44 Rot-13 the selection when activated. Used via keyboard trigger:
44 45
45 URxvt.keysym.C-M-r: perl:selection:rot13 46 URxvt.keysym.C-M-r: perl:selection:rot13
46 47
47 option-popup (enabled by default) 48 option-popup (enabled by default)
48 Binds a popup menu to Ctrl-Button3 that lets you toggle (some) 49 Binds a popup menu to Ctrl-Button2 that lets you toggle (some)
49 options at runtime. 50 options at runtime.
51
52 selection-popup (enabled by default)
53 Binds a popup menu to Ctrl-Button3 that lets you convert the
54 selection text into various other formats/action (such as uri
55 unescaping, perl evalution, web-browser starting etc.), depending on
56 content.
57
58 searchable-scrollback<hotkey> (enabled by default)
59 Adds regex search functionality to the scrollback buffer, triggered
60 by a hotkey (default: "M-s"). When in search mode, normal terminal
61 input/output is suspended.
62
63 "/" starts an incremental regex search, "n" searches further, "p" or
64 "N" jump to the previous match, "G" jumps to the bottom and clears
65 the history, "enter" leaves search mode at the current position and
66 "escape" returns to the original position.
50 67
51 digital-clock 68 digital-clock
52 Displays a digital clock using the built-in overlay. 69 Displays a digital clock using the built-in overlay.
53 70
54 mark-urls 71 mark-urls
55 Uses per-line display filtering ("on_line_update") to underline 72 Uses per-line display filtering ("on_line_update") to underline urls
56 urls. 73 and make them clickable. When clicked, the program specified in the
74 resource "urlLauncher" (default "x-www-browser") will be started.
57 75
58 block-graphics-to-ascii 76 block-graphics-to-ascii
59 A not very useful example of filtering all text output to the 77 A not very useful example of filtering all text output to the
60 terminal, by replacing all line-drawing characters (U+2500 .. 78 terminal, by replacing all line-drawing characters (U+2500 ..
61 U+259F) by a similar-looking ascii character. 79 U+259F) by a similar-looking ascii character.
… …
63 example-refresh-hooks 81 example-refresh-hooks
64 Displays a very simple digital clock in the upper right corner of 82 Displays a very simple digital clock in the upper right corner of
65 the window. Illustrates overwriting the refresh callbacks to create 83 the window. Illustrates overwriting the refresh callbacks to create
66 your own overlays or changes. 84 your own overlays or changes.
67 85
86API DOCUMENTATION
68 General API Considerations 87 General API Considerations
69 All objects (such as terminals, time watchers etc.) are typical 88 All objects (such as terminals, time watchers etc.) are typical
70 reference-to-hash objects. The hash can be used to store anything you 89 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 90 like. All members starting with an underscore (such as "_ptr" or
72 "_hook") are reserved for internal uses and MUST NOT be accessed or 91 "_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 99 Argument names also often indicate the type of a parameter. Here are
81 some hints on what they mean: 100 some hints on what they mean:
82 101
83 $text 102 $text
84 Rxvt-unicodes special way of encoding text, where one "unicode" 103 Rxvt-unicodes special way of encoding text, where one "unicode"
85 character always represents one screen cell. See row_t for a 104 character always represents one screen cell. See ROW_t for a
86 discussion of this format. 105 discussion of this format.
87 106
88 $string 107 $string
89 A perl text string, with an emphasis on *text*. It can store all 108 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 109 unicode characters and is to be distinguished with text encoded in a
… …
92 111
93 $octets 112 $octets
94 Either binary data or - more common - a text string encoded in a 113 Either binary data or - more common - a text string encoded in a
95 locale-specific way. 114 locale-specific way.
96 115
116 Extension Objects
117 Very perl extension is a perl class. A separate perl object is created
118 for each terminal and each extension and passed as the first parameter
119 to hooks. So extensions can use their $self object without having to
120 think about other extensions, with the exception of methods and members
121 that begin with an underscore character "_": these are reserved for
122 internal use.
123
124 Although it isn't a "urxvt::term" object, you can call all methods of
125 the "urxvt::term" class on this object.
126
127 It has the following methods and data members:
128
129 $urxvt_term = $self->{term}
130 Returns the "urxvt::term" object associated with this instance of
131 the extension. This member *must not* be changed in any way.
132
133 $self->enable ($hook_name => $cb, [$hook_name => $cb..])
134 Dynamically enable the given hooks (named without the "on_" prefix)
135 for this extension, replacing any previous hook. This is useful when
136 you want to overwrite time-critical hooks only temporarily.
137
138 $self->disable ($hook_name[, $hook_name..])
139 Dynamically disable the given hooks.
140
97 Hooks 141 Hooks
98 The following subroutines can be declared in extension files, and will 142 The following subroutines can be declared in extension files, and will
99 be called whenever the relevant event happens. 143 be called whenever the relevant event happens.
100 144
101 The first argument passed to them is an object private to each terminal 145 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 146 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 147
109 All of them must return a boolean value. If it is true, then the event 148 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 149 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++ 150 skipped, and the relevant action might not be carried out by the C++
112 code. 151 code.
113 152
114 When in doubt, return a false value (preferably "()"). 153 *When in doubt, return a false value (preferably "()").*
115 154
116 on_init $term 155 on_init $term
117 Called after a new terminal object has been initialized, but before 156 Called after a new terminal object has been initialized, but before
118 windows are created or the command gets run. Most methods are unsafe 157 windows are created or the command gets run. Most methods are unsafe
119 to call or deliver senseless data, as terminal size and other 158 to call or deliver senseless data, as terminal size and other
… …
165 may be larger than the scroll back buffer or the terminal. 204 may be larger than the scroll back buffer or the terminal.
166 205
167 It is called before lines are scrolled out (so rows 0 .. min ($lines 206 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 207 - 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. 208 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 209
175 on_osc_seq $term, $string 210 on_osc_seq $term, $string
176 Called whenever the ESC ] 777 ; string ST command sequence (OSC = 211 Called whenever the ESC ] 777 ; string ST command sequence (OSC =
177 operating system command) is processed. Cursor position and other 212 operating system command) is processed. Cursor position and other
178 state information is up-to-date when this happens. For 213 state information is up-to-date when this happens. For
… …
189 argument. You can filter/change and output the text yourself by 224 argument. You can filter/change and output the text yourself by
190 returning a true value and calling "$term->scr_add_lines" yourself. 225 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 226 Please note that this might be very slow, however, as your hook is
192 called for all text being output. 227 called for all text being output.
193 228
229 on_tt_write $term, $octets
230 Called whenever some data is written to the tty/pty and can be used
231 to suppress or filter tty input.
232
194 on_line_update $term, $row 233 on_line_update $term, $row
195 Called whenever a line was updated or changed. Can be used to filter 234 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 235 screen output (e.g. underline urls or other useless stuff). Only
197 lines that are being shown will be filtered, and, due to performance 236 lines that are being shown will be filtered, and, due to performance
198 reasons, not always immediately. 237 reasons, not always immediately.
… …
225 264
226 on_focus_out $term 265 on_focus_out $term
227 Called wheneever the window loses keyboard focus, before 266 Called wheneever the window loses keyboard focus, before
228 rxvt-unicode does focus out processing. 267 rxvt-unicode does focus out processing.
229 268
230 on_key_press $term, $event, $octets 269 on_key_press $term, $event, $keysym, $octets
231 on_key_release $term, $event 270 on_key_release $term, $event, $keysym
232 on_button_press $term, $event 271 on_button_press $term, $event
233 on_button_release $term, $event 272 on_button_release $term, $event
234 on_motion_notify $term, $event 273 on_motion_notify $term, $event
235 on_map_notify $term, $event 274 on_map_notify $term, $event
236 on_unmap_notify $term, $event 275 on_unmap_notify $term, $event
… …
246 output, if any, in locale-specific encoding. 285 output, if any, in locale-specific encoding.
247 286
248 subwindow. 287 subwindow.
249 288
250 Variables in the "urxvt" Package 289 Variables in the "urxvt" Package
290 $urxvt::LIBDIR
291 The rxvt-unicode library directory, where, among other things, the
292 perl modules and scripts are stored.
293
294 $urxvt::RESCLASS, $urxvt::RESCLASS
295 The resource class and name rxvt-unicode uses to look up X
296 resources.
297
298 $urxvt::RXVTNAME
299 The basename of the installed binaries, usually "urxvt".
300
251 $urxvt::TERM 301 $urxvt::TERM
252 The current terminal. This variable stores the current "urxvt::term" 302 The current terminal. This variable stores the current "urxvt::term"
253 object, whenever a callback/hook is executing. 303 object, whenever a callback/hook is executing.
254 304
255 Functions in the "urxvt" Package 305 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 306 urxvt::fatal $errormessage
265 Fatally aborts execution with the given error message. Avoid at all 307 Fatally aborts execution with the given error message. Avoid at all
266 costs! The only time this is acceptable is when the terminal process 308 costs! The only time this is acceptable is when the terminal process
267 starts up. 309 starts up.
268 310
… …
271 newline. The module also overwrites the "warn" builtin with a 313 newline. The module also overwrites the "warn" builtin with a
272 function that calls this function. 314 function that calls this function.
273 315
274 Using this function has the advantage that its output ends up in the 316 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. 317 correct place, e.g. on stderr of the connecting urxvtc client.
318
319 Messages have a size limit of 1023 bytes currently.
320
321 $is_safe = urxvt::safe
322 Returns true when it is safe to do potentially unsafe things, such
323 as evaluating perl code specified by the user. This is true when
324 urxvt was started setuid or setgid.
276 325
277 $time = urxvt::NOW 326 $time = urxvt::NOW
278 Returns the "current time" (as per the event loop). 327 Returns the "current time" (as per the event loop).
279 328
280 urxvt::CurrentTime 329 urxvt::CurrentTime
… …
307 356
308 $foreground = urxvt::GET_BASEFG $rend 357 $foreground = urxvt::GET_BASEFG $rend
309 $background = urxvt::GET_BASEBG $rend 358 $background = urxvt::GET_BASEBG $rend
310 Return the foreground/background colour index, respectively. 359 Return the foreground/background colour index, respectively.
311 360
312 $rend = urxvt::SET_FGCOLOR ($rend, $new_colour) 361 $rend = urxvt::SET_FGCOLOR $rend, $new_colour
313 $rend = urxvt::SET_BGCOLOR ($rend, $new_colour) 362 $rend = urxvt::SET_BGCOLOR $rend, $new_colour
314 Replace the foreground/background colour in the rendition mask with 363 Replace the foreground/background colour in the rendition mask with
315 the specified one. 364 the specified one.
316 365
317 $value = urxvt::GET_CUSTOM ($rend) 366 $value = urxvt::GET_CUSTOM $rend
318 Return the "custom" value: Every rendition has 5 bits for use by 367 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 368 extensions. They can be set and changed as you like and are
320 initially zero. 369 initially zero.
321 370
322 $rend = urxvt::SET_CUSTOM ($rend, $new_value) 371 $rend = urxvt::SET_CUSTOM $rend, $new_value
323 Change the custom value. 372 Change the custom value.
324 373
325 The "urxvt::anyevent" Class 374 The "urxvt::anyevent" Class
326 The sole purpose of this class is to deliver an interface to the 375 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 376 "AnyEvent" module - any module using it will work inside urxvt without
328 further work. The only exception is that you cannot wait on condition 377 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 378 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. 379 is that you cannot use blocking APIs, but the non-blocking variant
380 should work.
331 381
332 The "urxvt::term" Class 382 The "urxvt::term" Class
383 $term = new urxvt::term $envhashref, $rxvtname, [arg...]
384 Creates a new terminal, very similar as if you had started it with
385 system "$rxvtname, arg...". $envhashref must be a reference to a
386 %ENV-like hash which defines the environment of the new terminal.
387
388 Croaks (and probably outputs an error message) if the new instance
389 couldn't be created. Returns "undef" if the new instance didn't
390 initialise perl, and the terminal object otherwise. The "init" and
391 "start" hooks will be called during this call.
392
333 $term->destroy 393 $term->destroy
334 Destroy the terminal object (close the window, free resources etc.). 394 Destroy the terminal object (close the window, free resources etc.).
395 Please note that rxvt will not exit as long as any event watchers
396 (timers, io watchers) are still active.
335 397
336 $isset = $term->option ($optval[, $set]) 398 $isset = $term->option ($optval[, $set])
337 Returns true if the option specified by $optval is enabled, and 399 Returns true if the option specified by $optval is enabled, and
338 optionally change it. All option values are stored by name in the 400 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 401 hash %urxvt::OPTION. Options not enabled in this binary are not in
… …
381 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 443 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
382 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 444 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
383 shade term_name title transparent transparent_all tripleclickwords 445 shade term_name title transparent transparent_all tripleclickwords
384 utmpInhibit visualBell 446 utmpInhibit visualBell
385 447
448 $value = $term->x_resource ($pattern)
449 Returns the X-Resource for the given pattern, excluding the program
450 or class name, i.e. "$term->x_resource ("boldFont")" should return
451 the same value as used by this instance of rxvt-unicode. Returns
452 "undef" if no resource with that pattern exists.
453
454 This method should only be called during the "on_start" hook, as
455 there is only one resource database per display, and later
456 invocations might return the wrong resources.
457
458 $success = $term->parse_keysym ($keysym_spec, $command_string)
459 Adds a keymap translation exactly as specified via a resource. See
460 the "keysym" resource in the rxvt(1) manpage.
461
386 $rend = $term->rstyle ([$new_rstyle]) 462 $rend = $term->rstyle ([$new_rstyle])
387 Return and optionally change the current rendition. Text that is 463 Return and optionally change the current rendition. Text that is
388 output by the terminal application will use this style. 464 output by the terminal application will use this style.
389 465
390 ($row, $col) = $term->screen_cur ([$row, $col]) 466 ($row, $col) = $term->screen_cur ([$row, $col])
… …
404 480
405 $oldtext = $term->selection ([$newtext]) 481 $oldtext = $term->selection ([$newtext])
406 Return the current selection text and optionally replace it by 482 Return the current selection text and optionally replace it by
407 $newtext. 483 $newtext.
408 484
409 #=item $term->overlay ($x, $y, $text) # #Create a simple multi-line 485 $term->overlay_simple ($x, $y, $text)
410 overlay box. See the next method for details. # #=cut # #sub 486 Create a simple multi-line overlay box. See the next method for
411 urxvt::term::scr_overlay { # my ($self, $x, $y, $text) = @_; # # my 487 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 488
417 $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 489 $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
418 Create a new (empty) overlay at the given position with the given 490 Create a new (empty) overlay at the given position with the given
419 width/height. $rstyle defines the initial rendition style (default: 491 width/height. $rstyle defines the initial rendition style (default:
420 "OVERLAY_RSTYLE"). 492 "OVERLAY_RSTYLE").
… …
454 Convert the given text string into the corresponding locale 526 Convert the given text string into the corresponding locale
455 encoding. 527 encoding.
456 528
457 $string = $term->locale_decode ($octets) 529 $string = $term->locale_decode ($octets)
458 Convert the given locale-encoded octets into a perl string. 530 Convert the given locale-encoded octets into a perl string.
531
532 $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
533 XORs the rendition values in the given span with the provided value
534 (default: "RS_RVid"). Useful in refresh hooks to provide effects
535 similar to the selection.
536
537 $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[,
538 $rstyle2]])
539 Similar to "scr_xor_span", but xors a rectangle instead. Trailing
540 whitespace will additionally be xored with the $rstyle2, which
541 defaults to "RS_RVid | RS_Uline", which removes reverse video again
542 and underlines it instead.
543
544 $term->scr_bell
545 Ring the bell!
459 546
460 $term->scr_add_lines ($string) 547 $term->scr_add_lines ($string)
461 Write the given text string to the screen, as if output by the 548 Write the given text string to the screen, as if output by the
462 application running inside the terminal. It may not contain command 549 application running inside the terminal. It may not contain command
463 sequences (escape codes), but is free to use line feeds, carriage 550 sequences (escape codes), but is free to use line feeds, carriage
… …
476 $term->tt_write ($octets) 563 $term->tt_write ($octets)
477 Write the octets given in $data to the tty (i.e. as program input). 564 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 565 To pass characters instead of octets, you should convert your
479 strings first to the locale-specific encoding using 566 strings first to the locale-specific encoding using
480 "$term->locale_encode". 567 "$term->locale_encode".
568
569 $old_events = $term->pty_ev_events ([$new_events])
570 Replaces the event mask of the pty watcher by the given event mask.
571 Can be used to suppress input and output handling to the pty/tty.
572 See the description of "urxvt::timer->events". Make sure to always
573 restore the previous value.
481 574
482 $windowid = $term->parent 575 $windowid = $term->parent
483 Return the window id of the toplevel window. 576 Return the window id of the toplevel window.
484 577
485 $windowid = $term->vt 578 $windowid = $term->vt
… …
497 $max_scrollback = $term->saveLines 590 $max_scrollback = $term->saveLines
498 $nrow_plus_saveLines = $term->total_rows 591 $nrow_plus_saveLines = $term->total_rows
499 $lines_in_scrollback = $term->nsaved 592 $lines_in_scrollback = $term->nsaved
500 Return various integers describing terminal characteristics. 593 Return various integers describing terminal characteristics.
501 594
595 $x_display = $term->display_id
596 Return the DISPLAY used by rxvt-unicode.
597
598 $lc_ctype = $term->locale
599 Returns the LC_CTYPE category string used by this rxvt-unicode.
600
601 $env = $term->env
602 Returns a copy of the environment in effect for the terminal as a
603 hashref similar to "\%ENV".
604
502 $modifiermask = $term->ModLevel3Mask 605 $modifiermask = $term->ModLevel3Mask
503 $modifiermask = $term->ModMetaMask 606 $modifiermask = $term->ModMetaMask
504 $modifiermask = $term->ModNumLockMask 607 $modifiermask = $term->ModNumLockMask
505 Return the modifier masks corresponding to the "ISO Level 3 Shift" 608 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 609 (often AltGr), the meta key (often Alt) and the num lock key, if
… …
589 the logical line. 692 the logical line.
590 693
591 ($row, $col) = $line->coord_of ($offset) 694 ($row, $col) = $line->coord_of ($offset)
592 Translates a string offset into terminal coordinates again. 695 Translates a string offset into terminal coordinates again.
593 696
594 ($row, $col) = $line->coord_of ($offset) =item $text =
595 $term->special_encode $string 697 $text = $term->special_encode $string
596 Converts a perl string into the special encoding used by 698 Converts a perl string into the special encoding used by
597 rxvt-unicode, where one character corresponds to one screen cell. 699 rxvt-unicode, where one character corresponds to one screen cell.
598 See "$term->ROW_t" for details. 700 See "$term->ROW_t" for details.
599 701
600 $string = $term->special_decode $text 702 $string = $term->special_decode $text
601 Converts rxvt-unicodes text reprsentation into a perl string. See 703 Converts rxvt-unicodes text reprsentation into a perl string. See
602 "$term->ROW_t" for details. 704 "$term->ROW_t" for details.
603 705
706 $success = $term->grab_button ($button, $modifiermask)
707 Registers a synchronous button grab. See the XGrabButton manpage.
708
709 $success = $term->grab ($eventtime[, $sync])
710 Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
711 synchronous ($sync is true). Also remembers the grab timestampe.
712
713 $term->allow_events_async
714 Calls XAllowEvents with AsyncBoth for the most recent grab.
715
716 $term->allow_events_sync
717 Calls XAllowEvents with SyncBoth for the most recent grab.
718
719 $term->allow_events_replay
720 Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for
721 the most recent grab.
722
723 $term->ungrab
724 Calls XUngrab for the most recent grab. Is called automatically on
725 evaluation errors, as it is better to lose the grab in the error
726 case as the session.
727
604 The "urxvt::popup" Class 728 The "urxvt::popup" Class
729 $popup->add_title ($title)
730 Adds a non-clickable title to the popup.
731
732 $popup->add_separator ([$sepchr])
733 Creates a separator, optionally using the character given as
734 $sepchr.
735
736 $popup->add_button ($text, $cb)
737 Adds a clickable button to the popup. $cb is called whenever it is
738 selected.
739
740 $popup->add_toggle ($text, $cb, $initial_value)
741 Adds a toggle/checkbox item to the popup. Teh callback gets called
742 whenever it gets toggled, with a boolean indicating its value as its
743 first argument.
744
745 $popup->show
746 Displays the popup (which is initially hidden).
747
605 The "urxvt::timer" Class 748 The "urxvt::timer" Class
606 This class implements timer watchers/events. Time is represented as 749 This class implements timer watchers/events. Time is represented as a
607 a fractional number of seconds since the epoch. Example: 750 fractional number of seconds since the epoch. Example:
608 751
609 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0); 752 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
610 $term->{timer} = urxvt::timer 753 $term->{timer} = urxvt::timer
611 ->new 754 ->new
612 ->interval (1) 755 ->interval (1)
613 ->cb (sub { 756 ->cb (sub {
614 $term->{overlay}->set (0, 0, 757 $term->{overlay}->set (0, 0,
615 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]); 758 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
616 }); 759 });
617 760
618 $timer = new urxvt::timer 761 $timer = new urxvt::timer
619 Create a new timer object in started state. It is scheduled to 762 Create a new timer object in started state. It is scheduled to fire
620 fire immediately. 763 immediately.
621 764
622 $timer = $timer->cb (sub { my ($timer) = @_; ... }) 765 $timer = $timer->cb (sub { my ($timer) = @_; ... })
623 Set the callback to be called when the timer triggers. 766 Set the callback to be called when the timer triggers.
624 767
625 $tstamp = $timer->at 768 $tstamp = $timer->at
626 Return the time this watcher will fire next. 769 Return the time this watcher will fire next.
627 770
628 $timer = $timer->set ($tstamp) 771 $timer = $timer->set ($tstamp)
629 Set the time the event is generated to $tstamp. 772 Set the time the event is generated to $tstamp.
630 773
631 $timer = $timer->interval ($interval) 774 $timer = $timer->interval ($interval)
632 Normally (and when $interval is 0), the timer will automatically 775 Normally (and when $interval is 0), the timer will automatically
633 stop after it has fired once. If $interval is non-zero, then the 776 stop after it has fired once. If $interval is non-zero, then the
634 timer is automatically rescheduled at the given intervals. 777 timer is automatically rescheduled at the given intervals.
635 778
636 $timer = $timer->start 779 $timer = $timer->start
637 Start the timer. 780 Start the timer.
638 781
639 $timer = $timer->start ($tstamp) 782 $timer = $timer->start ($tstamp)
640 Set the event trigger time to $tstamp and start the timer. 783 Set the event trigger time to $tstamp and start the timer.
641 784
642 $timer = $timer->stop 785 $timer = $timer->stop
643 Stop the timer. 786 Stop the timer.
644 787
645 The "urxvt::iow" Class 788 The "urxvt::iow" Class
646 This class implements io watchers/events. Example: 789 This class implements io watchers/events. Example:
647 790
648 $term->{socket} = ... 791 $term->{socket} = ...
649 $term->{iow} = urxvt::iow 792 $term->{iow} = urxvt::iow
650 ->new 793 ->new
651 ->fd (fileno $term->{socket}) 794 ->fd (fileno $term->{socket})
652 ->events (1) # wait for read data 795 ->events (urxvt::EVENT_READ)
653 ->start 796 ->start
654 ->cb (sub { 797 ->cb (sub {
655 my ($iow, $revents) = @_; 798 my ($iow, $revents) = @_;
656 # $revents must be 1 here, no need to check 799 # $revents must be 1 here, no need to check
657 sysread $term->{socket}, my $buf, 8192 800 sysread $term->{socket}, my $buf, 8192
658 or end-of-file; 801 or end-of-file;
659 }); 802 });
660 803
661 $iow = new urxvt::iow 804 $iow = new urxvt::iow
662 Create a new io watcher object in stopped state. 805 Create a new io watcher object in stopped state.
663 806
664 $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... }) 807 $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
665 Set the callback to be called when io events are triggered. 808 Set the callback to be called when io events are triggered.
666 $reventmask is a bitset as described in the "events" method. 809 $reventmask is a bitset as described in the "events" method.
667 810
668 $iow = $iow->fd ($fd) 811 $iow = $iow->fd ($fd)
669 Set the filedescriptor (not handle) to watch. 812 Set the filedescriptor (not handle) to watch.
670 813
671 $iow = $iow->events ($eventmask) 814 $iow = $iow->events ($eventmask)
672 Set the event mask to watch. Bit #0 (value 1) enables watching 815 Set the event mask to watch. The only allowed values are
673 for read data, Bit #1 (value 2) enables watching for write data. 816 "urxvt::EVENT_READ" and "urxvt::EVENT_WRITE", which might be ORed
817 together, or "urxvt::EVENT_NONE".
674 818
675 $iow = $iow->start 819 $iow = $iow->start
676 Start watching for requested events on the given handle. 820 Start watching for requested events on the given handle.
677 821
678 $iow = $iow->stop 822 $iow = $iow->stop
679 Stop watching for events on the given filehandle. 823 Stop watching for events on the given filehandle.
680 824
681ENVIRONMENT 825ENVIRONMENT
682 URXVT_PERL_VERBOSITY 826 URXVT_PERL_VERBOSITY
683 This variable controls the verbosity level of the perl extension. 827 This variable controls the verbosity level of the perl extension. Higher
684 Higher numbers indicate more verbose output. 828 numbers indicate more verbose output.
685 829
686 =0 - only fatal messages 830 == 0 - fatal messages
687 =3 - script loading and management 831 >= 3 - script loading and management
688 =10 - all events received 832 >=10 - all events received
689 833
690AUTHOR 834AUTHOR
691 Marc Lehmann <pcg@goof.com> 835 Marc Lehmann <pcg@goof.com>
692 http://software.schmorp.de/pkg/rxvt-unicode 836 http://software.schmorp.de/pkg/rxvt-unicode
693 837

Diff Legend

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