ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/rxvt-unicode/doc/rxvtperl.3.txt
Revision: 1.15
Committed: Mon Jan 9 01:36:56 2006 UTC (18 years, 6 months ago) by root
Content type: text/plain
Branch: MAIN
Changes since 1.14: +31 -10 lines
Log Message:
*** empty log message ***

File Contents

# Content
1 NAME
2 rxvtperl - rxvt-unicode's embedded perl interpreter
3
4 SYNOPSIS
5 # create a file grab_test in $HOME:
6
7 sub on_sel_grab {
8 warn "you selected ", $_[0]->selection;
9 ()
10 }
11
12 # start a rxvt using it:
13
14 rxvt --perl-lib $HOME -pe grab_test
15
16 DESCRIPTION
17 Everytime a terminal object gets created, extension scripts specified
18 via the "perl" resource are loaded and associated with it.
19
20 Scripts are compiled in a 'use strict' and 'use utf8' environment, and
21 thus must be encoded as UTF-8.
22
23 Each script will only ever be loaded once, even in rxvtd, where scripts
24 will be shared (but not enabled) for all terminals.
25
26 Prepackaged Extensions
27 This section describes the extensiosn delivered with this version. You
28 can find them in /opt/rxvt/lib/urxvt/perl/.
29
30 You can activate them like this:
31
32 rxvt -pe <extensionname>
33
34 selection (enabled by default)
35 Intelligent selection. This extension tries to be more intelligent
36 when the user extends selections (double-click). Right now, it tries
37 to select urls and complete shell-quoted arguments, which is very
38 convenient, too, if your ls supports "--quoting-style=shell".
39
40 It also offers the following bindable event:
41
42 rot13
43 Rot-13 the selection when activated. Used via keyboard trigger:
44
45 URxvt.keysym.C-M-r: perl:selection:rot13
46
47 option-popup (enabled by default)
48 Binds a popup menu to Ctrl-Button2 that lets you toggle (some)
49 options at runtime.
50
51 selection-popup (enabled by default)
52 Binds a popup menu to Ctrl-Button3 that lets you convert the
53 selection text into various other formats/action.
54
55 digital-clock
56 Displays a digital clock using the built-in overlay.
57
58 mark-urls
59 Uses per-line display filtering ("on_line_update") to underline
60 urls.
61
62 block-graphics-to-ascii
63 A not very useful example of filtering all text output to the
64 terminal, by replacing all line-drawing characters (U+2500 ..
65 U+259F) by a similar-looking ascii character.
66
67 example-refresh-hooks
68 Displays a very simple digital clock in the upper right corner of
69 the window. Illustrates overwriting the refresh callbacks to create
70 your own overlays or changes.
71
72 General API Considerations
73 All objects (such as terminals, time watchers etc.) are typical
74 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
76 "_hook") are reserved for internal uses and MUST NOT be accessed or
77 modified).
78
79 When objects are destroyed on the C++ side, the perl object hashes are
80 emptied, so its best to store related objects such as time watchers and
81 the like inside the terminal object so they get destroyed as soon as the
82 terminal is destroyed.
83
84 Argument names also often indicate the type of a parameter. Here are
85 some hints on what they mean:
86
87 $text
88 Rxvt-unicodes special way of encoding text, where one "unicode"
89 character always represents one screen cell. See row_t for a
90 discussion of this format.
91
92 $string
93 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
95 specific encoding (often locale-specific) and binary data.
96
97 $octets
98 Either binary data or - more common - a text string encoded in a
99 locale-specific way.
100
101 Hooks
102 The following subroutines can be declared in extension files, and will
103 be called whenever the relevant event happens.
104
105 The first argument passed to them is an object private to each terminal
106 and extension package. You can call all "urxvt::term" methods on it, but
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
113 All of them must return a boolean value. If it is true, then the event
114 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++
116 code.
117
118 When in doubt, return a false value (preferably "()").
119
120 on_init $term
121 Called after a new terminal object has been initialized, but before
122 windows are created or the command gets run. Most methods are unsafe
123 to call or deliver senseless data, as terminal size and other
124 characteristics have not yet been determined. You can safely query
125 and change resources, though.
126
127 on_reset $term
128 Called after the screen is "reset" for any reason, such as resizing
129 or control sequences. Here is where you can react on changes to
130 size-related variables.
131
132 on_start $term
133 Called at the very end of initialisation of a new terminal, just
134 before returning to the mainloop.
135
136 on_sel_make $term, $eventtime
137 Called whenever a selection has been made by the user, but before
138 the selection text is copied, so changes to the beginning, end or
139 type of the selection will be honored.
140
141 Returning a true value aborts selection making by urxvt, in which
142 case you have to make a selection yourself by calling
143 "$term->selection_grab".
144
145 on_sel_grab $term, $eventtime
146 Called whenever a selection has been copied, but before the
147 selection is requested from the server. The selection text can be
148 queried and changed by calling "$term->selection".
149
150 Returning a true value aborts selection grabbing. It will still be
151 hilighted.
152
153 on_sel_extend $term
154 Called whenever the user tries to extend the selection (e.g. with a
155 double click) and is either supposed to return false (normal
156 operation), or should extend the selection itelf and return true to
157 suppress the built-in processing.
158
159 See the selection example extension.
160
161 on_view_change $term, $offset
162 Called whenever the view offset changes, i..e the user or program
163 scrolls. Offset 0 means display the normal terminal, positive values
164 show this many lines of scrollback.
165
166 on_scroll_back $term, $lines, $saved
167 Called whenever lines scroll out of the terminal area into the
168 scrollback buffer. $lines is the number of lines scrolled out and
169 may be larger than the scroll back buffer or the terminal.
170
171 It is called before lines are scrolled out (so rows 0 .. min ($lines
172 - 1, $nrow - 1) represent the lines to be scrolled out). $saved is
173 the total number of lines that will be in the scrollback buffer.
174
175 on_osc_seq $term, $string
176 Called whenever the ESC ] 777 ; string ST command sequence (OSC =
177 operating system command) is processed. Cursor position and other
178 state information is up-to-date when this happens. For
179 interoperability, the string should start with the extension name
180 and a colon, to distinguish it from commands for other extensions,
181 and this might be enforced in the future.
182
183 Be careful not ever to trust (in a security sense) the data you
184 receive, as its source can not easily be controleld (e-mail content,
185 messages from other users on the same system etc.).
186
187 on_add_lines $term, $string
188 Called whenever text is about to be output, with the text as
189 argument. You can filter/change and output the text yourself by
190 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
192 called for all text being output.
193
194 on_line_update $term, $row
195 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
197 lines that are being shown will be filtered, and, due to performance
198 reasons, not always immediately.
199
200 The row number is always the topmost row of the line if the line
201 spans multiple rows.
202
203 Please note that, if you change the line, then the hook might get
204 called later with the already-modified line (e.g. if unrelated parts
205 change), so you cannot just toggle rendition bits, but only set
206 them.
207
208 on_refresh_begin $term
209 Called just before the screen gets redrawn. Can be used for overlay
210 or similar effects by modify terminal contents in refresh_begin, and
211 restoring them in refresh_end. The built-in overlay and selection
212 display code is run after this hook, and takes precedence.
213
214 on_refresh_end $term
215 Called just after the screen gets redrawn. See "on_refresh_begin".
216
217 on_keyboard_command $term, $string
218 Called whenever the user presses a key combination that has a
219 "perl:string" action bound to it (see description of the keysym
220 resource in the rxvt(1) manpage).
221
222 on_focus_in $term
223 Called whenever the window gets the keyboard focus, before
224 rxvt-unicode does focus in processing.
225
226 on_focus_out $term
227 Called wheneever the window loses keyboard focus, before
228 rxvt-unicode does focus out processing.
229
230 on_key_press $term, $event, $octets
231 on_key_release $term, $event
232 on_button_press $term, $event
233 on_button_release $term, $event
234 on_motion_notify $term, $event
235 on_map_notify $term, $event
236 on_unmap_notify $term, $event
237 Called whenever the corresponding X event is received for the
238 terminal If the hook returns true, then the even will be ignored by
239 rxvt-unicode.
240
241 The event is a hash with most values as named by Xlib (see the
242 XEvent manpage), with the additional members "row" and "col", which
243 are the row and column under the mouse cursor.
244
245 "on_key_press" additionally receives the string rxvt-unicode would
246 output, if any, in locale-specific encoding.
247
248 subwindow.
249
250 Variables in the "urxvt" Package
251 $urxvt::TERM
252 The current terminal. This variable stores the current "urxvt::term"
253 object, whenever a callback/hook is executing.
254
255 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
265 Fatally aborts execution with the given error message. Avoid at all
266 costs! The only time this is acceptable is when the terminal process
267 starts up.
268
269 urxvt::warn $string
270 Calls "rxvt_warn" with the given string which should not include a
271 newline. The module also overwrites the "warn" builtin with a
272 function that calls this function.
273
274 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.
276
277 $time = urxvt::NOW
278 Returns the "current time" (as per the event loop).
279
280 urxvt::CurrentTime
281 urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask,
282 Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask,
283 Button5Mask, AnyModifier
284 Various constants for use in X calls and event processing.
285
286 RENDITION
287 Rendition bitsets contain information about colour, font, font styles
288 and similar information for each screen cell.
289
290 The following "macros" deal with changes in rendition sets. You should
291 never just create a bitset, you should always modify an existing one, as
292 they contain important information required for correct operation of
293 rxvt-unicode.
294
295 $rend = urxvt::DEFAULT_RSTYLE
296 Returns the default rendition, as used when the terminal is starting
297 up or being reset. Useful as a base to start when creating
298 renditions.
299
300 $rend = urxvt::OVERLAY_RSTYLE
301 Return the rendition mask used for overlays by default.
302
303 $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
304 Return the bit that enabled bold, italic, blink, reverse-video and
305 underline, respectively. To enable such a style, just logically OR
306 it into the bitset.
307
308 $foreground = urxvt::GET_BASEFG $rend
309 $background = urxvt::GET_BASEBG $rend
310 Return the foreground/background colour index, respectively.
311
312 $rend = urxvt::SET_FGCOLOR ($rend, $new_colour)
313 $rend = urxvt::SET_BGCOLOR ($rend, $new_colour)
314 Replace the foreground/background colour in the rendition mask with
315 the specified one.
316
317 $value = urxvt::GET_CUSTOM ($rend)
318 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
320 initially zero.
321
322 $rend = urxvt::SET_CUSTOM ($rend, $new_value)
323 Change the custom value.
324
325 The "urxvt::anyevent" Class
326 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
328 further work. The only exception is that you cannot wait on condition
329 variables, but non-blocking condvar use is ok. What this means is that
330 you cannot use blocking APIs, but the non-blocking variant should work.
331
332 The "urxvt::term" Class
333 $term->destroy
334 Destroy the terminal object (close the window, free resources etc.).
335
336 $isset = $term->option ($optval[, $set])
337 Returns true if the option specified by $optval is enabled, and
338 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
340 the hash.
341
342 Here is a a likely non-exhaustive list of option names, please see
343 the source file /src/optinc.h to see the actual list:
344
345 borderLess console cursorBlink cursorUnderline hold iconic insecure
346 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
347 pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating
348 scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer
349 secondaryScreen secondaryScroll skipBuiltinGlyphs transparent
350 tripleclickwords utmpInhibit visualBell
351
352 $value = $term->resource ($name[, $newval])
353 Returns the current resource value associated with a given name and
354 optionally sets a new value. Setting values is most useful in the
355 "init" hook. Unset resources are returned and accepted as "undef".
356
357 The new value must be properly encoded to a suitable character
358 encoding before passing it to this method. Similarly, the returned
359 value may need to be converted from the used encoding to text.
360
361 Resource names are as defined in src/rsinc.h. Colours can be
362 specified as resource names of the form "color+<index>", e.g.
363 "color+5". (will likely change).
364
365 Please note that resource strings will currently only be freed when
366 the terminal is destroyed, so changing options frequently will eat
367 memory.
368
369 Here is a a likely non-exhaustive list of resource names, not all of
370 which are supported in every build, please see the source file
371 /src/rsinc.h to see the actual list:
372
373 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
374 borderLess color cursorBlink cursorUnderline cutchars delete_key
375 display_name embed ext_bwidth fade font geometry hold iconName
376 imFont imLocale inputMethod insecure int_bwidth intensityStyles
377 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
378 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2
379 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
380 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
381 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
382 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
383 shade term_name title transparent transparent_all tripleclickwords
384 utmpInhibit visualBell
385
386 $rend = $term->rstyle ([$new_rstyle])
387 Return and optionally change the current rendition. Text that is
388 output by the terminal application will use this style.
389
390 ($row, $col) = $term->screen_cur ([$row, $col])
391 Return the current coordinates of the text cursor position and
392 optionally set it (which is usually bad as applications don't expect
393 that).
394
395 ($row, $col) = $term->selection_mark ([$row, $col])
396 ($row, $col) = $term->selection_beg ([$row, $col])
397 ($row, $col) = $term->selection_end ([$row, $col])
398 Return the current values of the selection mark, begin or end
399 positions, and optionally set them to new values.
400
401 $success = $term->selection_grab ($eventtime)
402 Try to request the primary selection from the server (for example,
403 as set by the next method).
404
405 $oldtext = $term->selection ([$newtext])
406 Return the current selection text and optionally replace it by
407 $newtext.
408
409 #=item $term->overlay ($x, $y, $text) # #Create a simple multi-line
410 overlay box. See the next method for details. # #=cut # #sub
411 urxvt::term::scr_overlay { # my ($self, $x, $y, $text) = @_; # # my
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
417 $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
418 Create a new (empty) overlay at the given position with the given
419 width/height. $rstyle defines the initial rendition style (default:
420 "OVERLAY_RSTYLE").
421
422 If $border is 2 (default), then a decorative border will be put
423 around the box.
424
425 If either $x or $y is negative, then this is counted from the
426 right/bottom side, respectively.
427
428 This method returns an urxvt::overlay object. The overlay will be
429 visible as long as the perl object is referenced.
430
431 The methods currently supported on "urxvt::overlay" objects are:
432
433 $overlay->set ($x, $y, $text, $rend)
434 Similar to "$term->ROW_t" and "$term->ROW_r" in that it puts
435 text in rxvt-unicode's special encoding and an array of
436 rendition values at a specific position inside the overlay.
437
438 $overlay->hide
439 If visible, hide the overlay, but do not destroy it.
440
441 $overlay->show
442 If hidden, display the overlay again.
443
444 $popup = $term->popup ($event)
445 Creates a new "urxvt::popup" object that implements a popup menu.
446 The $event *must* be the event causing the menu to pop up (a button
447 event, currently).
448
449 $cellwidth = $term->strwidth ($string)
450 Returns the number of screen-cells this string would need. Correctly
451 accounts for wide and combining characters.
452
453 $octets = $term->locale_encode ($string)
454 Convert the given text string into the corresponding locale
455 encoding.
456
457 $string = $term->locale_decode ($octets)
458 Convert the given locale-encoded octets into a perl string.
459
460 $term->scr_add_lines ($string)
461 Write the given text string to the screen, as if output by the
462 application running inside the terminal. It may not contain command
463 sequences (escape codes), but is free to use line feeds, carriage
464 returns and tabs. The string is a normal text string, not in
465 locale-dependent encoding.
466
467 Normally its not a good idea to use this function, as programs might
468 be confused by changes in cursor position or scrolling. Its useful
469 inside a "on_add_lines" hook, though.
470
471 $term->cmd_parse ($octets)
472 Similar to "scr_add_lines", but the argument must be in the
473 locale-specific encoding of the terminal and can contain command
474 sequences (escape codes) that will be interpreted.
475
476 $term->tt_write ($octets)
477 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
479 strings first to the locale-specific encoding using
480 "$term->locale_encode".
481
482 $windowid = $term->parent
483 Return the window id of the toplevel window.
484
485 $windowid = $term->vt
486 Return the window id of the terminal window.
487
488 $window_width = $term->width
489 $window_height = $term->height
490 $font_width = $term->fwidth
491 $font_height = $term->fheight
492 $font_ascent = $term->fbase
493 $terminal_rows = $term->nrow
494 $terminal_columns = $term->ncol
495 $has_focus = $term->focus
496 $is_mapped = $term->mapped
497 $max_scrollback = $term->saveLines
498 $nrow_plus_saveLines = $term->total_rows
499 $lines_in_scrollback = $term->nsaved
500 Return various integers describing terminal characteristics.
501
502 $modifiermask = $term->ModLevel3Mask
503 $modifiermask = $term->ModMetaMask
504 $modifiermask = $term->ModNumLockMask
505 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
507 applicable.
508
509 $view_start = $term->view_start ([$newvalue])
510 Returns the negative row number of the topmost line. Minimum value
511 is 0, which displays the normal terminal contents. Larger values
512 scroll this many lines into the scrollback buffer.
513
514 $term->want_refresh
515 Requests a screen refresh. At the next opportunity, rxvt-unicode
516 will compare the on-screen display with its stored representation.
517 If they differ, it redraws the differences.
518
519 Used after changing terminal contents to display them.
520
521 $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
522 Returns the text of the entire row with number $row_number. Row 0 is
523 the topmost terminal line, row "$term->$ncol-1" is the bottommost
524 terminal line. The scrollback buffer starts at line -1 and extends
525 to line "-$term->nsaved". Nothing will be returned if a nonexistent
526 line is requested.
527
528 If $new_text is specified, it will replace characters in the current
529 line, starting at column $start_col (default 0), which is useful to
530 replace only parts of a line. The font index in the rendition will
531 automatically be updated.
532
533 $text is in a special encoding: tabs and wide characters that use
534 more than one cell when displayed are padded with urxvt::NOCHAR
535 characters ("chr 65535"). Characters with combining characters and
536 other characters that do not fit into the normal tetx encoding will
537 be replaced with characters in the private use area.
538
539 You have to obey this encoding when changing text. The advantage is
540 that "substr" and similar functions work on screen cells and not on
541 characters.
542
543 The methods "$term->special_encode" and "$term->special_decode" can
544 be used to convert normal strings into this encoding and vice versa.
545
546 $rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])
547 Like "$term->ROW_t", but returns an arrayref with rendition bitsets.
548 Rendition bitsets contain information about colour, font, font
549 styles and similar information. See also "$term->ROW_t".
550
551 When setting rendition, the font mask will be ignored.
552
553 See the section on RENDITION, above.
554
555 $length = $term->ROW_l ($row_number[, $new_length])
556 Returns the number of screen cells that are in use ("the line
557 length"). Unlike the urxvt core, this returns "$term->ncol" if the
558 line is joined with the following one.
559
560 $bool = $term->is_longer ($row_number)
561 Returns true if the row is part of a multiple-row logical "line"
562 (i.e. joined with the following row), which means all characters are
563 in use and it is continued on the next row (and possibly a
564 continuation of the previous row(s)).
565
566 $line = $term->line ($row_number)
567 Create and return a new "urxvt::line" object that stores information
568 about the logical line that row $row_number is part of. It supports
569 the following methods:
570
571 $text = $line->t ([$new_text])
572 Returns or replaces the full text of the line, similar to
573 "ROW_t"
574
575 $rend = $line->r ([$new_rend])
576 Returns or replaces the full rendition array of the line,
577 similar to "ROW_r"
578
579 $length = $line->l
580 Returns the length of the line in cells, similar to "ROW_l".
581
582 $rownum = $line->beg
583 $rownum = $line->end
584 Return the row number of the first/last row of the line,
585 respectively.
586
587 $offset = $line->offset_of ($row, $col)
588 Returns the character offset of the given row|col pair within
589 the logical line.
590
591 ($row, $col) = $line->coord_of ($offset)
592 Translates a string offset into terminal coordinates again.
593
594 $text = $term->special_encode $string
595 Converts a perl string into the special encoding used by
596 rxvt-unicode, where one character corresponds to one screen cell.
597 See "$term->ROW_t" for details.
598
599 $string = $term->special_decode $text
600 Converts rxvt-unicodes text reprsentation into a perl string. See
601 "$term->ROW_t" for details.
602
603 $success = $term->grab_button ($button, $modifiermask)
604 Registers a synchronous button grab. See XGrabButton.
605
606 $success = $term->grab ($eventtime[, $sync])
607 Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
608 synchronous ($sync is true). Also remembers the grab timestampe.
609
610 $term->allow_events_async
611 Calls XAllowEvents with AsyncBoth for the most recent grab.
612
613 $term->allow_events_sync
614 Calls XAllowEvents with SyncBoth for the most recent grab.
615
616 $term->allow_events_replay
617 Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for
618 the most recent grab.
619
620 $term->ungrab
621 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
623 case as the session.
624
625 The "urxvt::popup" Class
626 The "urxvt::timer" Class
627 This class implements timer watchers/events. Time is represented as
628 a fractional number of seconds since the epoch. Example:
629
630 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
631 $term->{timer} = urxvt::timer
632 ->new
633 ->interval (1)
634 ->cb (sub {
635 $term->{overlay}->set (0, 0,
636 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
637 });
638
639 $timer = new urxvt::timer
640 Create a new timer object in started state. It is scheduled to
641 fire immediately.
642
643 $timer = $timer->cb (sub { my ($timer) = @_; ... })
644 Set the callback to be called when the timer triggers.
645
646 $tstamp = $timer->at
647 Return the time this watcher will fire next.
648
649 $timer = $timer->set ($tstamp)
650 Set the time the event is generated to $tstamp.
651
652 $timer = $timer->interval ($interval)
653 Normally (and when $interval is 0), the timer will automatically
654 stop after it has fired once. If $interval is non-zero, then the
655 timer is automatically rescheduled at the given intervals.
656
657 $timer = $timer->start
658 Start the timer.
659
660 $timer = $timer->start ($tstamp)
661 Set the event trigger time to $tstamp and start the timer.
662
663 $timer = $timer->stop
664 Stop the timer.
665
666 The "urxvt::iow" Class
667 This class implements io watchers/events. Example:
668
669 $term->{socket} = ...
670 $term->{iow} = urxvt::iow
671 ->new
672 ->fd (fileno $term->{socket})
673 ->events (1) # wait for read data
674 ->start
675 ->cb (sub {
676 my ($iow, $revents) = @_;
677 # $revents must be 1 here, no need to check
678 sysread $term->{socket}, my $buf, 8192
679 or end-of-file;
680 });
681
682 $iow = new urxvt::iow
683 Create a new io watcher object in stopped state.
684
685 $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
686 Set the callback to be called when io events are triggered.
687 $reventmask is a bitset as described in the "events" method.
688
689 $iow = $iow->fd ($fd)
690 Set the filedescriptor (not handle) to watch.
691
692 $iow = $iow->events ($eventmask)
693 Set the event mask to watch. Bit #0 (value 1) enables watching
694 for read data, Bit #1 (value 2) enables watching for write data.
695
696 $iow = $iow->start
697 Start watching for requested events on the given handle.
698
699 $iow = $iow->stop
700 Stop watching for events on the given filehandle.
701
702 ENVIRONMENT
703 URXVT_PERL_VERBOSITY
704 This variable controls the verbosity level of the perl extension.
705 Higher numbers indicate more verbose output.
706
707 == 0 - fatal messages
708 >= 3 - script loading and management
709 >=10 - all events received
710
711 AUTHOR
712 Marc Lehmann <pcg@goof.com>
713 http://software.schmorp.de/pkg/rxvt-unicode
714