1urxvt(3) RXVT-UNICODE urxvt(3)
2
6 urxvtperl - rxvt-unicode's embedded perl interpreter
7
9 # create a file grab_test in $HOME:
10 sub on_sel_grab {
12 warn "you selected ", $_[0]->selection;
13 ()
14 }
15 # start a urxvt using it:
17 urxvt --perl-lib $HOME -pe grab_test
19
21 Every time a terminal object gets created, extension scripts specified
22 via the "perl" resource are loaded and associated with it.
23 Scripts are compiled in a 'use strict' and 'use utf8' environment, and
25 thus must be encoded as UTF-8.
26 Each script will only ever be loaded once, even in urxvtd, where
28 scripts will be shared (but not enabled) for all terminals.
29 You can disable the embedded perl interpreter by setting both "perl-
31 ext" and "perl-ext-common" resources to the empty string.
32
34 This section describes the extensions delivered with this release. You
35 can find them in /usr/lib64/urxvt/perl/.
36 You can activate them like this:
38 urxvt -pe <extensionname>
40 Or by adding them to the resource for extensions loaded by default:
42 URxvt.perl-ext-common: default,selection-autotransform
44 selection (enabled by default)
46 (More) intelligent selection. This extension tries to be more
47 intelligent when the user extends selections (double-click and
48 further clicks). Right now, it tries to select words, urls and
49 complete shell-quoted arguments, which is very convenient, too, if
50 your ls supports "--quoting-style=shell".
51 A double-click usually selects the word under the cursor, further
53 clicks will enlarge the selection.
54 The selection works by trying to match a number of regexes and
56 displaying them in increasing order of length. You can add your own
57 regexes by specifying resources of the form:
58 URxvt.selection.pattern-0: perl-regex
60 URxvt.selection.pattern-1: perl-regex
61 ...
62 The index number (0, 1...) must not have any holes, and each regex
64 must contain at least one pair of capturing parentheses, which will
65 be used for the match. For example, the following adds a regex that
66 matches everything between two vertical bars:
67 URxvt.selection.pattern-0: \\|([^|]+)\\|
69 Another example: Programs I use often output "absolute path: " at
71 the beginning of a line when they process multiple files. The
72 following pattern matches the filename (note, there is a single
73 space at the very end):
74 URxvt.selection.pattern-0: ^(/[^:]+):\
76 You can look at the source of the selection extension to see more
78 interesting uses, such as parsing a line from beginning to end.
79 This extension also offers following bindable keyboard commands:
81 rot13
83 Rot-13 the selection when activated. Used via keyboard trigger:
84 URxvt.keysym.C-M-r: perl:selection:rot13
86 option-popup (enabled by default)
88 Binds a popup menu to Ctrl-Button2 that lets you toggle (some)
89 options at runtime.
90 Other extensions can extend this popup menu by pushing a code
92 reference onto "@{ $term-"{option_popup_hook} }>, which gets called
93 whenever the popup is being displayed.
94 Its sole argument is the popup menu, which can be modified. It
96 should either return nothing or a string, the initial boolean value
97 and a code reference. The string will be used as button text and
98 the code reference will be called when the toggle changes, with the
99 new boolean value as first argument.
100 The following will add an entry "myoption" that changes
102 "$self->{myoption}":
103 push @{ $self->{term}{option_popup_hook} }, sub {
105 ("my option" => $myoption, sub { $self->{myoption} = $_[0] })
106 };
107 selection-popup (enabled by default)
109 Binds a popup menu to Ctrl-Button3 that lets you convert the
110 selection text into various other formats/action (such as uri
111 unescaping, perl evaluation, web-browser starting etc.), depending
112 on content.
113 Other extensions can extend this popup menu by pushing a code
115 reference onto "@{ $term-"{selection_popup_hook} }>, which gets
116 called whenever the popup is being displayed.
117 Its sole argument is the popup menu, which can be modified. The
119 selection is in $_, which can be used to decide whether to add
120 something or not. It should either return nothing or a string and
121 a code reference. The string will be used as button text and the
122 code reference will be called when the button gets activated and
123 should transform $_.
124 The following will add an entry "a to b" that transforms all "a"s
126 in the selection to "b"s, but only if the selection currently
127 contains any "a"s:
128 push @{ $self->{term}{selection_popup_hook} }, sub {
130 /a/ ? ("a to b" => sub { s/a/b/g }
131 : ()
132 };
133 searchable-scrollback<hotkey> (enabled by default)
135 Adds regex search functionality to the scrollback buffer, triggered
136 by a hotkey (default: "M-s"). While in search mode, normal terminal
137 input/output is suspended and a regex is displayed at the bottom of
138 the screen.
139 Inputting characters appends them to the regex and continues
141 incremental search. "BackSpace" removes a character from the regex,
142 "Up" and "Down" search upwards/downwards in the scrollback buffer,
143 "End" jumps to the bottom. "Escape" leaves search mode and returns
144 to the point where search was started, while "Enter" or "Return"
145 stay at the current position and additionally stores the first
146 match in the current line into the primary selection if the "Shift"
147 modifier is active.
148 The regex defaults to "(?i)", resulting in a case-insensitive
150 search. To get a case-sensitive search you can delete this prefix
151 using "BackSpace" or simply use an uppercase character which
152 removes the "(?i)" prefix.
153 See perlre for more info about perl regular expression syntax.
155 readline (enabled by default)
157 A support package that tries to make editing with readline easier.
158 At the moment, it reacts to clicking shift-left mouse button by
159 trying to move the text cursor to this position. It does so by
160 generating as many cursor-left or cursor-right keypresses as
161 required (this only works for programs that correctly support wide
162 characters).
163 To avoid too many false positives, this is only done when:
165 - the tty is in ICANON state.
167 - the text cursor is visible.
168 - the primary screen is currently being displayed.
169 - the mouse is on the same (multi-row-) line as the text cursor.
170 The normal selection mechanism isn't disabled, so quick successive
172 clicks might interfere with selection creation in harmless ways.
173 selection-autotransform
175 This selection allows you to do automatic transforms on a selection
176 whenever a selection is made.
177 It works by specifying perl snippets (most useful is a single
179 "s///" operator) that modify $_ as resources:
180 URxvt.selection-autotransform.0: transform
182 URxvt.selection-autotransform.1: transform
183 ...
184 For example, the following will transform selections of the form
186 "filename:number", often seen in compiler messages, into "vi
187 +$filename $word":
188 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
190 And this example matches the same,but replaces it with vi-commands
192 you can paste directly into your (vi :) editor:
193 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/
195 Of course, this can be modified to suit your needs and your editor
197 :)
198 To expand the example above to typical perl error messages ("XXX at
200 FILENAME line YYY."), you need a slightly more elaborate solution:
201 URxvt.selection.pattern-0: ( at .*? line \\d+[,.])
203 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/
204 The first line tells the selection code to treat the unchanging
206 part of every error message as a selection pattern, and the second
207 line transforms the message into vi commands to load the file.
208 tabbed
210 This transforms the terminal into a tabbar with additional
211 terminals, that is, it implements what is commonly referred to as
212 "tabbed terminal". The topmost line displays a "[NEW]" button,
213 which, when clicked, will add a new tab, followed by one button per
214 tab.
215 Clicking a button will activate that tab. Pressing Shift-Left and
217 Shift-Right will switch to the tab left or right of the current
218 one, while Shift-Down creates a new tab.
219 The tabbar itself can be configured similarly to a normal terminal,
221 but with a resource class of "URxvt.tabbed". In addition, it
222 supports the following four resources (shown with defaults):
223 URxvt.tabbed.tabbar-fg: <colour-index, default 3>
225 URxvt.tabbed.tabbar-bg: <colour-index, default 0>
226 URxvt.tabbed.tab-fg: <colour-index, default 0>
227 URxvt.tabbed.tab-bg: <colour-index, default 1>
228 See COLOR AND GRAPHICS in the urxvt(1) manpage for valid indices.
230 matcher
232 Uses per-line display filtering ("on_line_update") to underline
233 text matching a certain pattern and make it clickable. When clicked
234 with the mouse button specified in the "matcher.button" resource
235 (default 2, or middle), the program specified in the
236 "matcher.launcher" resource (default, the "urlLauncher" resource,
237 "sensible-browser") will be started with the matched text as first
238 argument. The default configuration is suitable for matching URLs
239 and launching a web browser, like the former "mark-urls" extension.
240 The default pattern to match URLs can be overridden with the
242 "matcher.pattern.0" resource, and additional patterns can be
243 specified with numbered patterns, in a manner similar to the
244 "selection" extension. The launcher can also be overridden on a
245 per-pattern basis.
246 It is possible to activate the most recently seen match from the
248 keyboard. Simply bind a keysym to "perl:matcher" as seen in the
249 example below.
250 Example configuration:
252 URxvt.perl-ext: default,matcher
254 URxvt.urlLauncher: sensible-browser
255 URxvt.keysym.C-Delete: perl:matcher
256 URxvt.matcher.button: 1
257 URxvt.matcher.pattern.1: \\bwww\\.[\\w-]+\\.[\\w./?&@#-]*[\\w/-]
258 URxvt.matcher.pattern.2: \\B(/\\S+?):(\\d+)(?=:|$)
259 URxvt.matcher.launcher.2: gvim +$2 $1
260 xim-onthespot
262 This (experimental) perl extension implements OnTheSpot editing. It
263 does not work perfectly, and some input methods don't seem to work
264 well with OnTheSpot editing in general, but it seems to work at
265 least for SCIM and kinput2.
266 You enable it by specifying this extension and a preedit style of
268 "OnTheSpot", i.e.:
269 urxvt -pt OnTheSpot -pe xim-onthespot
271 kuake<hotkey>
273 A very primitive quake-console-like extension. It was inspired by a
274 description of how the programs "kuake" and "yakuake" work:
275 Whenever the user presses a global accelerator key (by default
276 "F10"), the terminal will show or hide itself. Another press of the
277 accelerator key will hide or show it again.
278 Initially, the window will not be shown when using this extension.
280 This is useful if you need a single terminal that is not using any
282 desktop space most of the time but is quickly available at the
283 press of a key.
284 The accelerator key is grabbed regardless of any modifiers, so this
286 extension will actually grab a physical key just for this function.
287 If you want a quake-like animation, tell your window manager to do
289 so (fvwm can do it).
290 overlay-osc
292 This extension implements some OSC commands to display timed popups
293 on the screen - useful for status displays from within scripts. You
294 have to read the sources for more info.
295 block-graphics-to-ascii
297 A not very useful example of filtering all text output to the
298 terminal by replacing all line-drawing characters (U+2500 ..
299 U+259F) by a similar-looking ascii character.
300 digital-clock
302 Displays a digital clock using the built-in overlay.
303 remote-clipboard
305 Somewhat of a misnomer, this extension adds two menu entries to the
306 selection popup that allows one to run external commands to store
307 the selection somewhere and fetch it again.
308 We use it to implement a "distributed selection mechanism", which
310 just means that one command uploads the file to a remote server,
311 and another reads it.
312 The commands can be set using the "URxvt.remote-selection.store"
314 and "URxvt.remote-selection.fetch" resources. The first should read
315 the selection to store from STDIN (always in UTF-8), the second
316 should provide the selection data on STDOUT (also in UTF-8).
317 The defaults (which are likely useless to you) use rsh and cat:
319 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
321 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
322 selection-pastebin
324 This is a little rarely useful extension that uploads the selection
325 as textfile to a remote site (or does other things). (The
326 implementation is not currently secure for use in a multiuser
327 environment as it writes to /tmp directly.).
328 It listens to the "selection-pastebin:remote-pastebin" keyboard
330 command, i.e.
331 URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin
333 Pressing this combination runs a command with "%" replaced by the
335 name of the textfile. This command can be set via a resource:
336 URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
338 And the default is likely not useful to anybody but the few people
340 around here :)
341 The name of the textfile is the hex encoded md5 sum of the
343 selection, so the same content should lead to the same filename.
344 After a successful upload the selection will be replaced by the
346 text given in the "selection-pastebin-url" resource (again, the %
347 is the placeholder for the filename):
348 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
350 Note to xrdb users: xrdb uses the C preprocessor, which might
352 interpret the double "/" characters as comment start. Use
353 "\057\057" instead, which works regardless of whether xrdb is used
354 to parse the resource file or not.
355 macosx-clipboard and macosx-clipboard-native
357 These two modules implement an extended clipboard for Mac OS X.
358 They are used like this:
359 URxvt.perl-ext-common: default,macosx-clipboard
361 URxvt.keysym.M-c: perl:macosx-clipboard:copy
362 URxvt.keysym.M-v: perl:macosx-clipboard:paste
363 The difference between them is that the native variant requires a
365 perl from apple's devkit or so, and "macosx-clipboard" requires the
366 "Mac::Pasteboard" module, works with other perls, has fewer bugs,
367 is simpler etc. etc.
368 example-refresh-hooks
370 Displays a very simple digital clock in the upper right corner of
371 the window. Illustrates overwriting the refresh callbacks to create
372 your own overlays or changes.
373 confirm-paste
375 Displays a confirmation dialog when a paste containing at least a
376 full line is detected.
377
379 General API Considerations
380 All objects (such as terminals, time watchers etc.) are typical
381 reference-to-hash objects. The hash can be used to store anything you
382 like. All members starting with an underscore (such as "_ptr" or
383 "_hook") are reserved for internal uses and MUST NOT be accessed or
384 modified).
385 When objects are destroyed on the C++ side, the perl object hashes are
387 emptied, so its best to store related objects such as time watchers and
388 the like inside the terminal object so they get destroyed as soon as
389 the terminal is destroyed.
390 Argument names also often indicate the type of a parameter. Here are
392 some hints on what they mean:
393 $text
395 Rxvt-unicode's special way of encoding text, where one "unicode"
396 character always represents one screen cell. See ROW_t for a
397 discussion of this format.
398 $string
400 A perl text string, with an emphasis on text. It can store all
401 unicode characters and is to be distinguished with text encoded in
402 a specific encoding (often locale-specific) and binary data.
403 $octets
405 Either binary data or - more common - a text string encoded in a
406 locale-specific way.
407 Extension Objects
409 Every perl extension is a perl class. A separate perl object is created
410 for each terminal, and each terminal has its own set of extenion
411 objects, which are passed as the first parameter to hooks. So
412 extensions can use their $self object without having to think about
413 clashes with other extensions or other terminals, with the exception of
414 methods and members that begin with an underscore character "_": these
415 are reserved for internal use.
416 Although it isn't a "urxvt::term" object, you can call all methods of
418 the "urxvt::term" class on this object.
419 It has the following methods and data members:
421 $urxvt_term = $self->{term}
423 Returns the "urxvt::term" object associated with this instance of
424 the extension. This member must not be changed in any way.
425 $self->enable ($hook_name => $cb, [$hook_name => $cb..])
427 Dynamically enable the given hooks (named without the "on_" prefix)
428 for this extension, replacing any previous hook. This is useful
429 when you want to overwrite time-critical hooks only temporarily.
430 $self->disable ($hook_name[, $hook_name..])
432 Dynamically disable the given hooks.
433 Hooks
435 The following subroutines can be declared in extension files, and will
436 be called whenever the relevant event happens.
437 The first argument passed to them is an extension object as described
439 in the in the "Extension Objects" section.
440 All of these hooks must return a boolean value. If any of the called
442 hooks returns true, then the event counts as being consumed, and the
443 relevant action might not be carried out by the C++ code.
444 When in doubt, return a false value (preferably "()").
446 on_init $term
448 Called after a new terminal object has been initialized, but before
449 windows are created or the command gets run. Most methods are
450 unsafe to call or deliver senseless data, as terminal size and
451 other characteristics have not yet been determined. You can safely
452 query and change resources and options, though. For many purposes
453 the "on_start" hook is a better place.
454 on_start $term
456 Called at the very end of initialisation of a new terminal, just
457 before trying to map (display) the toplevel and returning to the
458 main loop.
459 on_destroy $term
461 Called whenever something tries to destroy terminal, when the
462 terminal is still fully functional (not for long, though).
463 on_reset $term
465 Called after the screen is "reset" for any reason, such as resizing
466 or control sequences. Here is where you can react on changes to
467 size-related variables.
468 on_child_start $term, $pid
470 Called just after the child process has been "fork"ed.
471 on_child_exit $term, $status
473 Called just after the child process has exited. $status is the
474 status from "waitpid".
475 on_sel_make $term, $eventtime
477 Called whenever a selection has been made by the user, but before
478 the selection text is copied, so changes to the beginning, end or
479 type of the selection will be honored.
480 Returning a true value aborts selection making by urxvt, in which
482 case you have to make a selection yourself by calling
483 "$term->selection_grab".
484 on_sel_grab $term, $eventtime
486 Called whenever a selection has been copied, but before the
487 selection is requested from the server. The selection text can be
488 queried and changed by calling "$term->selection".
489 Returning a true value aborts selection grabbing. It will still be
491 highlighted.
492 on_sel_extend $term
494 Called whenever the user tries to extend the selection (e.g. with a
495 double click) and is either supposed to return false (normal
496 operation), or should extend the selection itself and return true
497 to suppress the built-in processing. This can happen multiple
498 times, as long as the callback returns true, it will be called on
499 every further click by the user and is supposed to enlarge the
500 selection more and more, if possible.
501 See the selection example extension.
503 on_view_change $term, $offset
505 Called whenever the view offset changes, i.e. the user or program
506 scrolls. Offset 0 means display the normal terminal, positive
507 values show this many lines of scrollback.
508 on_scroll_back $term, $lines, $saved
510 Called whenever lines scroll out of the terminal area into the
511 scrollback buffer. $lines is the number of lines scrolled out and
512 may be larger than the scroll back buffer or the terminal.
513 It is called before lines are scrolled out (so rows 0 .. min
515 ($lines - 1, $nrow - 1) represent the lines to be scrolled out).
516 $saved is the total number of lines that will be in the scrollback
517 buffer.
518 on_osc_seq $term, $op, $args, $resp
520 Called on every OSC sequence and can be used to suppress it or
521 modify its behaviour. The default should be to return an empty
522 list. A true value suppresses execution of the request completely.
523 Make sure you don't get confused by recursive invocations when you
524 output an OSC sequence within this callback.
525 "on_osc_seq_perl" should be used for new behaviour.
527 on_osc_seq_perl $term, $args, $resp
529 Called whenever the ESC ] 777 ; string ST command sequence (OSC =
530 operating system command) is processed. Cursor position and other
531 state information is up-to-date when this happens. For
532 interoperability, the string should start with the extension name
533 (sans -osc) and a semicolon, to distinguish it from commands for
534 other extensions, and this might be enforced in the future.
535 For example, "overlay-osc" uses this:
537 sub on_osc_seq_perl {
539 my ($self, $osc, $resp) = @_;
540 return unless $osc =~ s/^overlay;//;
542 ... process remaining $osc string
544 }
545 Be careful not ever to trust (in a security sense) the data you
547 receive, as its source can not easily be controlled (e-mail
548 content, messages from other users on the same system etc.).
549 For responses, $resp contains the end-of-args separator used by the
551 sender.
552 on_add_lines $term, $string
554 Called whenever text is about to be output, with the text as
555 argument. You can filter/change and output the text yourself by
556 returning a true value and calling "$term->scr_add_lines" yourself.
557 Please note that this might be very slow, however, as your hook is
558 called for all text being output.
559 on_tt_write $term, $octets
561 Called whenever some data is written to the tty/pty and can be used
562 to suppress or filter tty input.
563 on_tt_paste $term, $octets
565 Called whenever text is about to be pasted, with the text as
566 argument. You can filter/change and paste the text yourself by
567 returning a true value and calling "$term->tt_paste" yourself.
568 $octets is locale-encoded.
569 on_line_update $term, $row
571 Called whenever a line was updated or changed. Can be used to
572 filter screen output (e.g. underline urls or other useless stuff).
573 Only lines that are being shown will be filtered, and, due to
574 performance reasons, not always immediately.
575 The row number is always the topmost row of the line if the line
577 spans multiple rows.
578 Please note that, if you change the line, then the hook might get
580 called later with the already-modified line (e.g. if unrelated
581 parts change), so you cannot just toggle rendition bits, but only
582 set them.
583 on_refresh_begin $term
585 Called just before the screen gets redrawn. Can be used for overlay
586 or similar effects by modifying the terminal contents in
587 refresh_begin, and restoring them in refresh_end. The built-in
588 overlay and selection display code is run after this hook, and
589 takes precedence.
590 on_refresh_end $term
592 Called just after the screen gets redrawn. See "on_refresh_begin".
593 on_user_command $term, $string
595 Called whenever a user-configured event is being activated (e.g.
596 via a "perl:string" action bound to a key, see description of the
597 keysym resource in the urxvt(1) manpage).
598 The event is simply the action string. This interface is assumed to
600 change slightly in the future.
601 on_resize_all_windows $term, $new_width, $new_height
603 Called just after the new window size has been calculated, but
604 before windows are actually being resized or hints are being set.
605 If this hook returns TRUE, setting of the window hints is being
606 skipped.
607 on_x_event $term, $event
609 Called on every X event received on the vt window (and possibly
610 other windows). Should only be used as a last resort. Most event
611 structure members are not passed.
612 on_root_event $term, $event
614 Like "on_x_event", but is called for events on the root window.
615 on_focus_in $term
617 Called whenever the window gets the keyboard focus, before rxvt-
618 unicode does focus in processing.
619 on_focus_out $term
621 Called whenever the window loses keyboard focus, before rxvt-
622 unicode does focus out processing.
623 on_configure_notify $term, $event
625 on_property_notify $term, $event
626 on_key_press $term, $event, $keysym, $octets
627 on_key_release $term, $event, $keysym
628 on_button_press $term, $event
629 on_button_release $term, $event
630 on_motion_notify $term, $event
631 on_map_notify $term, $event
632 on_unmap_notify $term, $event
633 Called whenever the corresponding X event is received for the
634 terminal. If the hook returns true, then the event will be ignored
635 by rxvt-unicode.
636 The event is a hash with most values as named by Xlib (see the
638 XEvent manpage), with the additional members "row" and "col", which
639 are the (real, not screen-based) row and column under the mouse
640 cursor.
641 "on_key_press" additionally receives the string rxvt-unicode would
643 output, if any, in locale-specific encoding.
644 subwindow.
646 on_client_message $term, $event
648 on_wm_protocols $term, $event
649 on_wm_delete_window $term, $event
650 Called when various types of ClientMessage events are received (all
651 with format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
652 on_bell $term
654 Called on receipt of a bell character.
655 Variables in the "urxvt" Package
657 $urxvt::LIBDIR
658 The rxvt-unicode library directory, where, among other things, the
659 perl modules and scripts are stored.
660 $urxvt::RESCLASS, $urxvt::RESCLASS
662 The resource class and name rxvt-unicode uses to look up X
663 resources.
664 $urxvt::RXVTNAME
666 The basename of the installed binaries, usually "urxvt".
667 $urxvt::TERM
669 The current terminal. This variable stores the current
670 "urxvt::term" object, whenever a callback/hook is executing.
671 @urxvt::TERM_INIT
673 All code references in this array will be called as methods of the
674 next newly created "urxvt::term" object (during the "on_init"
675 phase). The array gets cleared before the code references that were
676 in it are being executed, so references can push themselves onto it
677 again if they so desire.
678 This complements to the perl-eval command line option, but gets
680 executed first.
681 @urxvt::TERM_EXT
683 Works similar to @TERM_INIT, but contains perl package/class names,
684 which get registered as normal extensions after calling the hooks
685 in @TERM_INIT but before other extensions. Gets cleared just like
686 @TERM_INIT.
687 Functions in the "urxvt" Package
689 urxvt::fatal $errormessage
690 Fatally aborts execution with the given error message (which should
691 include a trailing newline). Avoid at all costs! The only time this
692 is acceptable (and useful) is in the init hook, where it prevents
693 the terminal from starting up.
694 urxvt::warn $string
696 Calls "rxvt_warn" with the given string which should include a
697 trailing newline. The module also overwrites the "warn" builtin
698 with a function that calls this function.
699 Using this function has the advantage that its output ends up in
701 the correct place, e.g. on stderr of the connecting urxvtc client.
702 Messages have a size limit of 1023 bytes currently.
704 @terms = urxvt::termlist
706 Returns all urxvt::term objects that exist in this process,
707 regardless of whether they are started, being destroyed etc., so be
708 careful. Only term objects that have perl extensions attached will
709 be returned (because there is no urxvt::term objet associated with
710 others).
711 $time = urxvt::NOW
713 Returns the "current time" (as per the event loop).
714 urxvt::CurrentTime
716 urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask,
717 Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask,
718 Button5Mask, AnyModifier
719 urxvt::NoEventMask, KeyPressMask, KeyReleaseMask, ButtonPressMask,
720 ButtonReleaseMask, EnterWindowMask, LeaveWindowMask, PointerMotionMask,
721 PointerMotionHintMask, Button1MotionMask, Button2MotionMask,
722 Button3MotionMask, Button4MotionMask, Button5MotionMask,
723 ButtonMotionMask, KeymapStateMask, ExposureMask, VisibilityChangeMask,
724 StructureNotifyMask, ResizeRedirectMask, SubstructureNotifyMask,
725 SubstructureRedirectMask, FocusChangeMask, PropertyChangeMask,
726 ColormapChangeMask, OwnerGrabButtonMask
727 urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify,
728 EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose,
729 GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify,
730 DestroyNotify, UnmapNotify, MapNotify, MapRequest, ReparentNotify,
731 ConfigureNotify, ConfigureRequest, GravityNotify, ResizeRequest,
732 CirculateNotify, CirculateRequest, PropertyNotify, SelectionClear,
733 SelectionRequest, SelectionNotify, ColormapNotify, ClientMessage,
734 MappingNotify
735 Various constants for use in X calls and event processing.
736 RENDITION
738 Rendition bitsets contain information about colour, font, font styles
739 and similar information for each screen cell.
740 The following "macros" deal with changes in rendition sets. You should
742 never just create a bitset, you should always modify an existing one,
743 as they contain important information required for correct operation of
744 rxvt-unicode.
745 $rend = urxvt::DEFAULT_RSTYLE
747 Returns the default rendition, as used when the terminal is
748 starting up or being reset. Useful as a base to start when creating
749 renditions.
750 $rend = urxvt::OVERLAY_RSTYLE
752 Return the rendition mask used for overlays by default.
753 $rendbit = urxvt::RS_Bold, urxvt::RS_Italic, urxvt::RS_Blink,
755 urxvt::RS_RVid, urxvt::RS_Uline
756 Return the bit that enabled bold, italic, blink, reverse-video and
757 underline, respectively. To enable such a style, just logically OR
758 it into the bitset.
759 $foreground = urxvt::GET_BASEFG $rend
761 $background = urxvt::GET_BASEBG $rend
762 Return the foreground/background colour index, respectively.
763 $rend = urxvt::SET_FGCOLOR $rend, $new_colour
765 $rend = urxvt::SET_BGCOLOR $rend, $new_colour
766 $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
767 Replace the foreground/background colour in the rendition mask with
768 the specified one.
769 $value = urxvt::GET_CUSTOM $rend
771 Return the "custom" value: Every rendition has 5 bits for use by
772 extensions. They can be set and changed as you like and are
773 initially zero.
774 $rend = urxvt::SET_CUSTOM $rend, $new_value
776 Change the custom value.
777 The "urxvt::anyevent" Class
779 The sole purpose of this class is to deliver an interface to the
780 "AnyEvent" module - any module using it will work inside urxvt without
781 further programming. The only exception is that you cannot wait on
782 condition variables, but non-blocking condvar use is ok. What this
783 means is that you cannot use blocking APIs, but the non-blocking
784 variant should work.
785 The "urxvt::term" Class
787 $term = new urxvt::term $envhashref, $rxvtname, [arg...]
788 Creates a new terminal, very similar as if you had started it with
789 system "$rxvtname, arg...". $envhashref must be a reference to a
790 %ENV-like hash which defines the environment of the new terminal.
791 Croaks (and probably outputs an error message) if the new instance
793 couldn't be created. Returns "undef" if the new instance didn't
794 initialise perl, and the terminal object otherwise. The "init" and
795 "start" hooks will be called before this call returns, and are free
796 to refer to global data (which is race free).
797 $term->destroy
799 Destroy the terminal object (close the window, free resources
800 etc.). Please note that urxvt will not exit as long as any event
801 watchers (timers, io watchers) are still active.
802 $term->exec_async ($cmd[, @args])
804 Works like the combination of the "fork"/"exec" builtins, which
805 executes ("starts") programs in the background. This function takes
806 care of setting the user environment before exec'ing the command
807 (e.g. "PATH") and should be preferred over explicit calls to "exec"
808 or "system".
809 Returns the pid of the subprocess or "undef" on error.
811 $isset = $term->option ($optval[, $set])
813 Returns true if the option specified by $optval is enabled, and
814 optionally change it. All option values are stored by name in the
815 hash %urxvt::OPTION. Options not enabled in this binary are not in
816 the hash.
817 Here is a likely non-exhaustive list of option names, please see
819 the source file /src/optinc.h to see the actual list:
820 borderLess console cursorBlink cursorUnderline hold iconic insecure
822 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
823 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
824 scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput
825 scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs
826 transparent tripleclickwords utmpInhibit visualBell
827 $value = $term->resource ($name[, $newval])
829 Returns the current resource value associated with a given name and
830 optionally sets a new value. Setting values is most useful in the
831 "init" hook. Unset resources are returned and accepted as "undef".
832 The new value must be properly encoded to a suitable character
834 encoding before passing it to this method. Similarly, the returned
835 value may need to be converted from the used encoding to text.
836 Resource names are as defined in src/rsinc.h. Colours can be
838 specified as resource names of the form "color+<index>", e.g.
839 "color+5". (will likely change).
840 Please note that resource strings will currently only be freed when
842 the terminal is destroyed, so changing options frequently will eat
843 memory.
844 Here is a likely non-exhaustive list of resource names, not all of
846 which are supported in every build, please see the source file
847 /src/rsinc.h to see the actual list:
848 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
850 borderLess chdir color cursorBlink cursorUnderline cutchars delete_key
851 display_name embed ext_bwidth fade font geometry hold iconName
852 imFont imLocale inputMethod insecure int_bwidth intensityStyles
853 italicFont jumpScroll lineSpace letterSpace loginShell mapAlert meta8
854 modifier mouseWheelScrollPage name override_redirect pastableTabs path
855 perl_eval perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
856 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
857 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
858 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
859 secondaryScreen secondaryScroll shade term_name title
860 transient_for transparent transparent_all tripleclickwords utmpInhibit
861 visualBell
862 $value = $term->x_resource ($pattern)
864 Returns the X-Resource for the given pattern, excluding the program
865 or class name, i.e. "$term->x_resource ("boldFont")" should return
866 the same value as used by this instance of rxvt-unicode. Returns
867 "undef" if no resource with that pattern exists.
868 This method should only be called during the "on_start" hook, as
870 there is only one resource database per display, and later
871 invocations might return the wrong resources.
872 $success = $term->parse_keysym ($keysym_spec, $command_string)
874 Adds a keymap translation exactly as specified via a resource. See
875 the "keysym" resource in the urxvt(1) manpage.
876 $rend = $term->rstyle ([$new_rstyle])
878 Return and optionally change the current rendition. Text that is
879 output by the terminal application will use this style.
880 ($row, $col) = $term->screen_cur ([$row, $col])
882 Return the current coordinates of the text cursor position and
883 optionally set it (which is usually bad as applications don't
884 expect that).
885 ($row, $col) = $term->selection_mark ([$row, $col])
887 ($row, $col) = $term->selection_beg ([$row, $col])
888 ($row, $col) = $term->selection_end ([$row, $col])
889 Return the current values of the selection mark, begin or end
890 positions.
891 When arguments are given, then the selection coordinates are set to
893 $row and $col, and the selection screen is set to the current
894 screen.
895 $screen = $term->selection_screen ([$screen])
897 Returns the current selection screen, and then optionally sets it.
898 $term->selection_make ($eventtime[, $rectangular])
900 Tries to make a selection as set by "selection_beg" and
901 "selection_end". If $rectangular is true (default: false), a
902 rectangular selection will be made. This is the preferred function
903 to make a selection.
904 $success = $term->selection_grab ($eventtime[, $clipboard])
906 Try to acquire ownership of the primary (clipboard if $clipboard is
907 true) selection from the server. The corresponding text can be set
908 with the next method. No visual feedback will be given. This
909 function is mostly useful from within "on_sel_grab" hooks.
910 $oldtext = $term->selection ([$newtext, $clipboard])
912 Return the current selection (clipboard if $clipboard is true) text
913 and optionally replace it by $newtext.
914 $term->selection_clear ([$clipboard])
916 Revoke ownership of the primary (clipboard if $clipboard is true)
917 selection.
918 $term->overlay_simple ($x, $y, $text)
920 Create a simple multi-line overlay box. See the next method for
921 details.
922 $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
924 Create a new (empty) overlay at the given position with the given
925 width/height. $rstyle defines the initial rendition style (default:
926 "OVERLAY_RSTYLE").
927 If $border is 2 (default), then a decorative border will be put
929 around the box.
930 If either $x or $y is negative, then this is counted from the
932 right/bottom side, respectively.
933 This method returns an urxvt::overlay object. The overlay will be
935 visible as long as the perl object is referenced.
936 The methods currently supported on "urxvt::overlay" objects are:
938 $overlay->set ($x, $y, $text[, $rend])
940 Similar to "$term->ROW_t" and "$term->ROW_r" in that it puts
941 text in rxvt-unicode's special encoding and an array of
942 rendition values at a specific position inside the overlay.
943 If $rend is missing, then the rendition will not be changed.
945 $overlay->hide
947 If visible, hide the overlay, but do not destroy it.
948 $overlay->show
950 If hidden, display the overlay again.
951 $popup = $term->popup ($event)
953 Creates a new "urxvt::popup" object that implements a popup menu.
954 The $event must be the event causing the menu to pop up (a button
955 event, currently).
956 $cellwidth = $term->strwidth ($string)
958 Returns the number of screen-cells this string would need.
959 Correctly accounts for wide and combining characters.
960 $octets = $term->locale_encode ($string)
962 Convert the given text string into the corresponding locale
963 encoding.
964 $string = $term->locale_decode ($octets)
966 Convert the given locale-encoded octets into a perl string.
967 $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
969 XORs the rendition values in the given span with the provided value
970 (default: "RS_RVid"), which MUST NOT contain font styles. Useful in
971 refresh hooks to provide effects similar to the selection.
972 $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[,
974 $rstyle1[, $rstyle2]])
975 Similar to "scr_xor_span", but xors a rectangle instead. Trailing
976 whitespace will additionally be xored with the $rstyle2, which
977 defaults to "RS_RVid | RS_Uline", which removes reverse video again
978 and underlines it instead. Both styles MUST NOT contain font
979 styles.
980 $term->scr_bell
982 Ring the bell!
983 $term->scr_add_lines ($string)
985 Write the given text string to the screen, as if output by the
986 application running inside the terminal. It may not contain command
987 sequences (escape codes), but is free to use line feeds, carriage
988 returns and tabs. The string is a normal text string, not in
989 locale-dependent encoding.
990 Normally its not a good idea to use this function, as programs
992 might be confused by changes in cursor position or scrolling. Its
993 useful inside a "on_add_lines" hook, though.
994 $term->scr_change_screen ($screen)
996 Switch to given screen - 0 primary, 1 secondary.
997 $term->cmd_parse ($octets)
999 Similar to "scr_add_lines", but the argument must be in the locale-
1000 specific encoding of the terminal and can contain command sequences
1001 (escape codes) that will be interpreted.
1002 $term->tt_write ($octets)
1004 Write the octets given in $octets to the tty (i.e. as program
1005 input). To pass characters instead of octets, you should convert
1006 your strings first to the locale-specific encoding using
1007 "$term->locale_encode".
1008 $term->tt_paste ($octets)
1010 Write the octets given in $octets to the tty as a paste, converting
1011 NL to CR and bracketing the data with control sequences if
1012 bracketed paste mode is set.
1013 $old_events = $term->pty_ev_events ([$new_events])
1015 Replaces the event mask of the pty watcher by the given event mask.
1016 Can be used to suppress input and output handling to the pty/tty.
1017 See the description of "urxvt::timer->events". Make sure to always
1018 restore the previous value.
1019 $fd = $term->pty_fd
1021 Returns the master file descriptor for the pty in use, or "-1" if
1022 no pty is used.
1023 $windowid = $term->parent
1025 Return the window id of the toplevel window.
1026 $windowid = $term->vt
1028 Return the window id of the terminal window.
1029 $term->vt_emask_add ($x_event_mask)
1031 Adds the specified events to the vt event mask. Useful e.g. when
1032 you want to receive pointer events all the times:
1033 $term->vt_emask_add (urxvt::PointerMotionMask);
1035 $term->focus_in
1037 $term->focus_out
1038 $term->key_press ($state, $keycode[, $time])
1039 $term->key_release ($state, $keycode[, $time])
1040 Deliver various fake events to to terminal.
1041 $window_width = $term->width
1043 $window_height = $term->height
1044 $font_width = $term->fwidth
1045 $font_height = $term->fheight
1046 $font_ascent = $term->fbase
1047 $terminal_rows = $term->nrow
1048 $terminal_columns = $term->ncol
1049 $has_focus = $term->focus
1050 $is_mapped = $term->mapped
1051 $max_scrollback = $term->saveLines
1052 $nrow_plus_saveLines = $term->total_rows
1053 $topmost_scrollback_row = $term->top_row
1054 Return various integers describing terminal characteristics.
1055 $x_display = $term->display_id
1057 Return the DISPLAY used by rxvt-unicode.
1058 $lc_ctype = $term->locale
1060 Returns the LC_CTYPE category string used by this rxvt-unicode.
1061 $env = $term->env
1063 Returns a copy of the environment in effect for the terminal as a
1064 hashref similar to "\%ENV".
1065 @envv = $term->envv
1067 Returns the environment as array of strings of the form
1068 "VAR=VALUE".
1069 @argv = $term->argv
1071 Return the argument vector as this terminal, similar to @ARGV, but
1072 includes the program name as first element.
1073 $modifiermask = $term->ModLevel3Mask
1075 $modifiermask = $term->ModMetaMask
1076 $modifiermask = $term->ModNumLockMask
1077 Return the modifier masks corresponding to the "ISO Level 3 Shift"
1078 (often AltGr), the meta key (often Alt) and the num lock key, if
1079 applicable.
1080 $screen = $term->current_screen
1082 Returns the currently displayed screen (0 primary, 1 secondary).
1083 $cursor_is_hidden = $term->hidden_cursor
1085 Returns whether the cursor is currently hidden or not.
1086 $view_start = $term->view_start ([$newvalue])
1088 Returns the row number of the topmost displayed line. Maximum value
1089 is 0, which displays the normal terminal contents. Lower values
1090 scroll this many lines into the scrollback buffer.
1091 $term->want_refresh
1093 Requests a screen refresh. At the next opportunity, rxvt-unicode
1094 will compare the on-screen display with its stored representation.
1095 If they differ, it redraws the differences.
1096 Used after changing terminal contents to display them.
1098 $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
1100 Returns the text of the entire row with number $row_number. Row
1101 "$term->top_row" is the topmost terminal line, row "$term->nrow-1"
1102 is the bottommost terminal line. Nothing will be returned if a
1103 nonexistent line is requested.
1104 If $new_text is specified, it will replace characters in the
1106 current line, starting at column $start_col (default 0), which is
1107 useful to replace only parts of a line. The font index in the
1108 rendition will automatically be updated.
1109 $text is in a special encoding: tabs and wide characters that use
1111 more than one cell when displayed are padded with $urxvt::NOCHAR
1112 (chr 65535) characters. Characters with combining characters and
1113 other characters that do not fit into the normal text encoding will
1114 be replaced with characters in the private use area.
1115 You have to obey this encoding when changing text. The advantage is
1117 that "substr" and similar functions work on screen cells and not on
1118 characters.
1119 The methods "$term->special_encode" and "$term->special_decode" can
1121 be used to convert normal strings into this encoding and vice
1122 versa.
1123 $rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])
1125 Like "$term->ROW_t", but returns an arrayref with rendition
1126 bitsets. Rendition bitsets contain information about colour, font,
1127 font styles and similar information. See also "$term->ROW_t".
1128 When setting rendition, the font mask will be ignored.
1130 See the section on RENDITION, above.
1132 $length = $term->ROW_l ($row_number[, $new_length])
1134 Returns the number of screen cells that are in use ("the line
1135 length"). Unlike the urxvt core, this returns "$term->ncol" if the
1136 line is joined with the following one.
1137 $bool = $term->is_longer ($row_number)
1139 Returns true if the row is part of a multiple-row logical "line"
1140 (i.e. joined with the following row), which means all characters
1141 are in use and it is continued on the next row (and possibly a
1142 continuation of the previous row(s)).
1143 $line = $term->line ($row_number)
1145 Create and return a new "urxvt::line" object that stores
1146 information about the logical line that row $row_number is part of.
1147 It supports the following methods:
1148 $text = $line->t ([$new_text])
1150 Returns or replaces the full text of the line, similar to
1151 "ROW_t"
1152 $rend = $line->r ([$new_rend])
1154 Returns or replaces the full rendition array of the line,
1155 similar to "ROW_r"
1156 $length = $line->l
1158 Returns the length of the line in cells, similar to "ROW_l".
1159 $rownum = $line->beg
1161 $rownum = $line->end
1162 Return the row number of the first/last row of the line,
1163 respectively.
1164 $offset = $line->offset_of ($row, $col)
1166 Returns the character offset of the given row|col pair within
1167 the logical line. Works for rows outside the line, too, and
1168 returns corresponding offsets outside the string.
1169 ($row, $col) = $line->coord_of ($offset)
1171 Translates a string offset into terminal coordinates again.
1172 $text = $term->special_encode $string
1174 Converts a perl string into the special encoding used by rxvt-
1175 unicode, where one character corresponds to one screen cell. See
1176 "$term->ROW_t" for details.
1177 $string = $term->special_decode $text
1179 Converts rxvt-unicodes text representation into a perl string. See
1180 "$term->ROW_t" for details.
1181 $success = $term->grab_button ($button, $modifiermask[, $window =
1183 $term->vt])
1184 $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1185 Register/unregister a synchronous button grab. See the XGrabButton
1186 manpage.
1187 $success = $term->grab ($eventtime[, $sync])
1189 Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1190 synchronous ($sync is true). Also remembers the grab timestamp.
1191 $term->allow_events_async
1193 Calls XAllowEvents with AsyncBoth for the most recent grab.
1194 $term->allow_events_sync
1196 Calls XAllowEvents with SyncBoth for the most recent grab.
1197 $term->allow_events_replay
1199 Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for
1200 the most recent grab.
1201 $term->ungrab
1203 Calls XUngrabPointer and XUngrabKeyboard for the most recent grab.
1204 Is called automatically on evaluation errors, as it is better to
1205 lose the grab in the error case as the session.
1206 $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
1208 $atom_name = $term->XGetAtomName ($atom)
1209 @atoms = $term->XListProperties ($window)
1210 ($type,$format,$octets) = $term->XGetWindowProperty ($window,
1211 $property)
1212 $term->XChangeProperty ($window, $property, $type, $format, $octets)
1213 $term->XDeleteProperty ($window, $property)
1214 $window = $term->DefaultRootWindow
1215 $term->XReparentWindow ($window, $parent, [$x, $y])
1216 $term->XMapWindow ($window)
1217 $term->XUnmapWindow ($window)
1218 $term->XMoveResizeWindow ($window, $x, $y, $width, $height)
1219 ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x,
1220 $y)
1221 $term->XChangeInput ($window, $add_events[, $del_events])
1222 Various X or X-related functions. The $term object only serves as
1223 the source of the display, otherwise those functions map more-or-
1224 less directly onto the X functions of the same name.
1225 The "urxvt::popup" Class
1227 $popup->add_title ($title)
1228 Adds a non-clickable title to the popup.
1229 $popup->add_separator ([$sepchr])
1231 Creates a separator, optionally using the character given as
1232 $sepchr.
1233 $popup->add_button ($text, $cb)
1235 Adds a clickable button to the popup. $cb is called whenever it is
1236 selected.
1237 $popup->add_toggle ($text, $initial_value, $cb)
1239 Adds a toggle/checkbox item to the popup. The callback gets called
1240 whenever it gets toggled, with a boolean indicating its new value
1241 as its first argument.
1242 $popup->show
1244 Displays the popup (which is initially hidden).
1245 The "urxvt::timer" Class
1247 This class implements timer watchers/events. Time is represented as a
1248 fractional number of seconds since the epoch. Example:
1249 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
1251 $term->{timer} = urxvt::timer
1252 ->new
1253 ->interval (1)
1254 ->cb (sub {
1255 $term->{overlay}->set (0, 0,
1256 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
1257 });
1258 $timer = new urxvt::timer
1260 Create a new timer object in started state. It is scheduled to fire
1261 immediately.
1262 $timer = $timer->cb (sub { my ($timer) = @_; ... })
1264 Set the callback to be called when the timer triggers.
1265 $timer = $timer->set ($tstamp[, $interval])
1267 Set the time the event is generated to $tstamp (and optionally
1268 specifies a new $interval).
1269 $timer = $timer->interval ($interval)
1271 By default (and when $interval is 0), the timer will automatically
1272 stop after it has fired once. If $interval is non-zero, then the
1273 timer is automatically rescheduled at the given intervals.
1274 $timer = $timer->start
1276 Start the timer.
1277 $timer = $timer->start ($tstamp[, $interval])
1279 Set the event trigger time to $tstamp and start the timer.
1280 Optionally also replaces the interval.
1281 $timer = $timer->after ($delay[, $interval])
1283 Like "start", but sets the expiry timer to c<urxvt::NOW + $delay>.
1284 $timer = $timer->stop
1286 Stop the timer.
1287 The "urxvt::iow" Class
1289 This class implements io watchers/events. Example:
1290 $term->{socket} = ...
1292 $term->{iow} = urxvt::iow
1293 ->new
1294 ->fd (fileno $term->{socket})
1295 ->events (urxvt::EV_READ)
1296 ->start
1297 ->cb (sub {
1298 my ($iow, $revents) = @_;
1299 # $revents must be 1 here, no need to check
1300 sysread $term->{socket}, my $buf, 8192
1301 or end-of-file;
1302 });
1303 $iow = new urxvt::iow
1305 Create a new io watcher object in stopped state.
1306 $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
1308 Set the callback to be called when io events are triggered.
1309 $reventmask is a bitset as described in the "events" method.
1310 $iow = $iow->fd ($fd)
1312 Set the file descriptor (not handle) to watch.
1313 $iow = $iow->events ($eventmask)
1315 Set the event mask to watch. The only allowed values are
1316 "urxvt::EV_READ" and "urxvt::EV_WRITE", which might be ORed
1317 together, or "urxvt::EV_NONE".
1318 $iow = $iow->start
1320 Start watching for requested events on the given handle.
1321 $iow = $iow->stop
1323 Stop watching for events on the given file handle.
1324 The "urxvt::iw" Class
1326 This class implements idle watchers, that get called automatically when
1327 the process is idle. They should return as fast as possible, after
1328 doing some useful work.
1329 $iw = new urxvt::iw
1331 Create a new idle watcher object in stopped state.
1332 $iw = $iw->cb (sub { my ($iw) = @_; ... })
1334 Set the callback to be called when the watcher triggers.
1335 $timer = $timer->start
1337 Start the watcher.
1338 $timer = $timer->stop
1340 Stop the watcher.
1341 The "urxvt::pw" Class
1343 This class implements process watchers. They create an event whenever a
1344 process exits, after which they stop automatically.
1345 my $pid = fork;
1347 ...
1348 $term->{pw} = urxvt::pw
1349 ->new
1350 ->start ($pid)
1351 ->cb (sub {
1352 my ($pw, $exit_status) = @_;
1353 ...
1354 });
1355 $pw = new urxvt::pw
1357 Create a new process watcher in stopped state.
1358 $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
1360 Set the callback to be called when the timer triggers.
1361 $pw = $timer->start ($pid)
1363 Tells the watcher to start watching for process $pid.
1364 $pw = $pw->stop
1366 Stop the watcher.
1367
1369 URXVT_PERL_VERBOSITY
1370 This variable controls the verbosity level of the perl extension.
1371 Higher numbers indicate more verbose output.
1372 == 0 - fatal messages
1374 >= 3 - script loading and management
1375 >=10 - all called hooks
1376 >=11 - hook return values
1377
1379 Marc Lehmann <schmorp@schmorp.de>
1380 http://software.schmorp.de/pkg/rxvt-unicode
13819.12 2011-06-29 urxvt(3)