1urxvt-ml(3) RXVT-UNICODE urxvt-ml(3)
2
6 urxvt-mlperl - 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-ml using it:
17 urxvt-ml --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 urxvt-mld, 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-ml -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-ml(1) manpage for valid
230 indices.
231 matcher
233 Uses per-line display filtering ("on_line_update") to underline
234 text matching a certain pattern and make it clickable. When clicked
235 with the mouse button specified in the "matcher.button" resource
236 (default 2, or middle), the program specified in the
237 "matcher.launcher" resource (default, the "urlLauncher" resource,
238 "sensible-browser") will be started with the matched text as first
239 argument. The default configuration is suitable for matching URLs
240 and launching a web browser, like the former "mark-urls" extension.
241 The default pattern to match URLs can be overridden with the
243 "matcher.pattern.0" resource, and additional patterns can be
244 specified with numbered patterns, in a manner similar to the
245 "selection" extension. The launcher can also be overridden on a
246 per-pattern basis.
247 It is possible to activate the most recently seen match from the
249 keyboard. Simply bind a keysym to "perl:matcher" as seen in the
250 example below.
251 Example configuration:
253 URxvt.perl-ext: default,matcher
255 URxvt.urlLauncher: sensible-browser
256 URxvt.keysym.C-Delete: perl:matcher
257 URxvt.matcher.button: 1
258 URxvt.matcher.pattern.1: \\bwww\\.[\\w-]+\\.[\\w./?&@#-]*[\\w/-]
259 URxvt.matcher.pattern.2: \\B(/\\S+?):(\\d+)(?=:|$)
260 URxvt.matcher.launcher.2: gvim +$2 $1
261 xim-onthespot
263 This (experimental) perl extension implements OnTheSpot editing. It
264 does not work perfectly, and some input methods don't seem to work
265 well with OnTheSpot editing in general, but it seems to work at
266 least for SCIM and kinput2.
267 You enable it by specifying this extension and a preedit style of
269 "OnTheSpot", i.e.:
270 urxvt-ml -pt OnTheSpot -pe xim-onthespot
272 kuake<hotkey>
274 A very primitive quake-console-like extension. It was inspired by a
275 description of how the programs "kuake" and "yakuake" work:
276 Whenever the user presses a global accelerator key (by default
277 "F10"), the terminal will show or hide itself. Another press of the
278 accelerator key will hide or show it again.
279 Initially, the window will not be shown when using this extension.
281 This is useful if you need a single terminal that is not using any
283 desktop space most of the time but is quickly available at the
284 press of a key.
285 The accelerator key is grabbed regardless of any modifiers, so this
287 extension will actually grab a physical key just for this function.
288 If you want a quake-like animation, tell your window manager to do
290 so (fvwm can do it).
291 overlay-osc
293 This extension implements some OSC commands to display timed popups
294 on the screen - useful for status displays from within scripts. You
295 have to read the sources for more info.
296 block-graphics-to-ascii
298 A not very useful example of filtering all text output to the
299 terminal by replacing all line-drawing characters (U+2500 ..
300 U+259F) by a similar-looking ascii character.
301 digital-clock
303 Displays a digital clock using the built-in overlay.
304 remote-clipboard
306 Somewhat of a misnomer, this extension adds two menu entries to the
307 selection popup that allows one to run external commands to store
308 the selection somewhere and fetch it again.
309 We use it to implement a "distributed selection mechanism", which
311 just means that one command uploads the file to a remote server,
312 and another reads it.
313 The commands can be set using the "URxvt.remote-selection.store"
315 and "URxvt.remote-selection.fetch" resources. The first should read
316 the selection to store from STDIN (always in UTF-8), the second
317 should provide the selection data on STDOUT (also in UTF-8).
318 The defaults (which are likely useless to you) use rsh and cat:
320 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
322 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
323 selection-pastebin
325 This is a little rarely useful extension that uploads the selection
326 as textfile to a remote site (or does other things). (The
327 implementation is not currently secure for use in a multiuser
328 environment as it writes to /tmp directly.).
329 It listens to the "selection-pastebin:remote-pastebin" keyboard
331 command, i.e.
332 URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin
334 Pressing this combination runs a command with "%" replaced by the
336 name of the textfile. This command can be set via a resource:
337 URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
339 And the default is likely not useful to anybody but the few people
341 around here :)
342 The name of the textfile is the hex encoded md5 sum of the
344 selection, so the same content should lead to the same filename.
345 After a successful upload the selection will be replaced by the
347 text given in the "selection-pastebin-url" resource (again, the %
348 is the placeholder for the filename):
349 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
351 Note to xrdb users: xrdb uses the C preprocessor, which might
353 interpret the double "/" characters as comment start. Use
354 "\057\057" instead, which works regardless of whether xrdb is used
355 to parse the resource file or not.
356 macosx-clipboard and macosx-clipboard-native
358 These two modules implement an extended clipboard for Mac OS X.
359 They are used like this:
360 URxvt.perl-ext-common: default,macosx-clipboard
362 URxvt.keysym.M-c: perl:macosx-clipboard:copy
363 URxvt.keysym.M-v: perl:macosx-clipboard:paste
364 The difference between them is that the native variant requires a
366 perl from apple's devkit or so, and "macosx-clipboard" requires the
367 "Mac::Pasteboard" module, works with other perls, has fewer bugs,
368 is simpler etc. etc.
369 example-refresh-hooks
371 Displays a very simple digital clock in the upper right corner of
372 the window. Illustrates overwriting the refresh callbacks to create
373 your own overlays or changes.
374 confirm-paste
376 Displays a confirmation dialog when a paste containing at least a
377 full line is detected.
378
380 General API Considerations
381 All objects (such as terminals, time watchers etc.) are typical
382 reference-to-hash objects. The hash can be used to store anything you
383 like. All members starting with an underscore (such as "_ptr" or
384 "_hook") are reserved for internal uses and MUST NOT be accessed or
385 modified).
386 When objects are destroyed on the C++ side, the perl object hashes are
388 emptied, so its best to store related objects such as time watchers and
389 the like inside the terminal object so they get destroyed as soon as
390 the terminal is destroyed.
391 Argument names also often indicate the type of a parameter. Here are
393 some hints on what they mean:
394 $text
396 Rxvt-unicode's special way of encoding text, where one "unicode"
397 character always represents one screen cell. See ROW_t for a
398 discussion of this format.
399 $string
401 A perl text string, with an emphasis on text. It can store all
402 unicode characters and is to be distinguished with text encoded in
403 a specific encoding (often locale-specific) and binary data.
404 $octets
406 Either binary data or - more common - a text string encoded in a
407 locale-specific way.
408 Extension Objects
410 Every perl extension is a perl class. A separate perl object is created
411 for each terminal, and each terminal has its own set of extenion
412 objects, which are passed as the first parameter to hooks. So
413 extensions can use their $self object without having to think about
414 clashes with other extensions or other terminals, with the exception of
415 methods and members that begin with an underscore character "_": these
416 are reserved for internal use.
417 Although it isn't a "urxvt::term" object, you can call all methods of
419 the "urxvt::term" class on this object.
420 It has the following methods and data members:
422 $urxvt_term = $self->{term}
424 Returns the "urxvt::term" object associated with this instance of
425 the extension. This member must not be changed in any way.
426 $self->enable ($hook_name => $cb, [$hook_name => $cb..])
428 Dynamically enable the given hooks (named without the "on_" prefix)
429 for this extension, replacing any previous hook. This is useful
430 when you want to overwrite time-critical hooks only temporarily.
431 $self->disable ($hook_name[, $hook_name..])
433 Dynamically disable the given hooks.
434 Hooks
436 The following subroutines can be declared in extension files, and will
437 be called whenever the relevant event happens.
438 The first argument passed to them is an extension object as described
440 in the in the "Extension Objects" section.
441 All of these hooks must return a boolean value. If any of the called
443 hooks returns true, then the event counts as being consumed, and the
444 relevant action might not be carried out by the C++ code.
445 When in doubt, return a false value (preferably "()").
447 on_init $term
449 Called after a new terminal object has been initialized, but before
450 windows are created or the command gets run. Most methods are
451 unsafe to call or deliver senseless data, as terminal size and
452 other characteristics have not yet been determined. You can safely
453 query and change resources and options, though. For many purposes
454 the "on_start" hook is a better place.
455 on_start $term
457 Called at the very end of initialisation of a new terminal, just
458 before trying to map (display) the toplevel and returning to the
459 main loop.
460 on_destroy $term
462 Called whenever something tries to destroy terminal, when the
463 terminal is still fully functional (not for long, though).
464 on_reset $term
466 Called after the screen is "reset" for any reason, such as resizing
467 or control sequences. Here is where you can react on changes to
468 size-related variables.
469 on_child_start $term, $pid
471 Called just after the child process has been "fork"ed.
472 on_child_exit $term, $status
474 Called just after the child process has exited. $status is the
475 status from "waitpid".
476 on_sel_make $term, $eventtime
478 Called whenever a selection has been made by the user, but before
479 the selection text is copied, so changes to the beginning, end or
480 type of the selection will be honored.
481 Returning a true value aborts selection making by urxvt, in which
483 case you have to make a selection yourself by calling
484 "$term->selection_grab".
485 on_sel_grab $term, $eventtime
487 Called whenever a selection has been copied, but before the
488 selection is requested from the server. The selection text can be
489 queried and changed by calling "$term->selection".
490 Returning a true value aborts selection grabbing. It will still be
492 highlighted.
493 on_sel_extend $term
495 Called whenever the user tries to extend the selection (e.g. with a
496 double click) and is either supposed to return false (normal
497 operation), or should extend the selection itself and return true
498 to suppress the built-in processing. This can happen multiple
499 times, as long as the callback returns true, it will be called on
500 every further click by the user and is supposed to enlarge the
501 selection more and more, if possible.
502 See the selection example extension.
504 on_view_change $term, $offset
506 Called whenever the view offset changes, i.e. the user or program
507 scrolls. Offset 0 means display the normal terminal, positive
508 values show this many lines of scrollback.
509 on_scroll_back $term, $lines, $saved
511 Called whenever lines scroll out of the terminal area into the
512 scrollback buffer. $lines is the number of lines scrolled out and
513 may be larger than the scroll back buffer or the terminal.
514 It is called before lines are scrolled out (so rows 0 .. min
516 ($lines - 1, $nrow - 1) represent the lines to be scrolled out).
517 $saved is the total number of lines that will be in the scrollback
518 buffer.
519 on_osc_seq $term, $op, $args, $resp
521 Called on every OSC sequence and can be used to suppress it or
522 modify its behaviour. The default should be to return an empty
523 list. A true value suppresses execution of the request completely.
524 Make sure you don't get confused by recursive invocations when you
525 output an OSC sequence within this callback.
526 "on_osc_seq_perl" should be used for new behaviour.
528 on_osc_seq_perl $term, $args, $resp
530 Called whenever the ESC ] 777 ; string ST command sequence (OSC =
531 operating system command) is processed. Cursor position and other
532 state information is up-to-date when this happens. For
533 interoperability, the string should start with the extension name
534 (sans -osc) and a semicolon, to distinguish it from commands for
535 other extensions, and this might be enforced in the future.
536 For example, "overlay-osc" uses this:
538 sub on_osc_seq_perl {
540 my ($self, $osc, $resp) = @_;
541 return unless $osc =~ s/^overlay;//;
543 ... process remaining $osc string
545 }
546 Be careful not ever to trust (in a security sense) the data you
548 receive, as its source can not easily be controlled (e-mail
549 content, messages from other users on the same system etc.).
550 For responses, $resp contains the end-of-args separator used by the
552 sender.
553 on_add_lines $term, $string
555 Called whenever text is about to be output, with the text as
556 argument. You can filter/change and output the text yourself by
557 returning a true value and calling "$term->scr_add_lines" yourself.
558 Please note that this might be very slow, however, as your hook is
559 called for all text being output.
560 on_tt_write $term, $octets
562 Called whenever some data is written to the tty/pty and can be used
563 to suppress or filter tty input.
564 on_tt_paste $term, $octets
566 Called whenever text is about to be pasted, with the text as
567 argument. You can filter/change and paste the text yourself by
568 returning a true value and calling "$term->tt_paste" yourself.
569 $octets is locale-encoded.
570 on_line_update $term, $row
572 Called whenever a line was updated or changed. Can be used to
573 filter screen output (e.g. underline urls or other useless stuff).
574 Only lines that are being shown will be filtered, and, due to
575 performance reasons, not always immediately.
576 The row number is always the topmost row of the line if the line
578 spans multiple rows.
579 Please note that, if you change the line, then the hook might get
581 called later with the already-modified line (e.g. if unrelated
582 parts change), so you cannot just toggle rendition bits, but only
583 set them.
584 on_refresh_begin $term
586 Called just before the screen gets redrawn. Can be used for overlay
587 or similar effects by modifying the terminal contents in
588 refresh_begin, and restoring them in refresh_end. The built-in
589 overlay and selection display code is run after this hook, and
590 takes precedence.
591 on_refresh_end $term
593 Called just after the screen gets redrawn. See "on_refresh_begin".
594 on_user_command $term, $string
596 Called whenever a user-configured event is being activated (e.g.
597 via a "perl:string" action bound to a key, see description of the
598 keysym resource in the urxvt-ml(1) manpage).
599 The event is simply the action string. This interface is assumed to
601 change slightly in the future.
602 on_resize_all_windows $term, $new_width, $new_height
604 Called just after the new window size has been calculated, but
605 before windows are actually being resized or hints are being set.
606 If this hook returns TRUE, setting of the window hints is being
607 skipped.
608 on_x_event $term, $event
610 Called on every X event received on the vt window (and possibly
611 other windows). Should only be used as a last resort. Most event
612 structure members are not passed.
613 on_root_event $term, $event
615 Like "on_x_event", but is called for events on the root window.
616 on_focus_in $term
618 Called whenever the window gets the keyboard focus, before rxvt-
619 unicode does focus in processing.
620 on_focus_out $term
622 Called whenever the window loses keyboard focus, before rxvt-
623 unicode does focus out processing.
624 on_configure_notify $term, $event
626 on_property_notify $term, $event
627 on_key_press $term, $event, $keysym, $octets
628 on_key_release $term, $event, $keysym
629 on_button_press $term, $event
630 on_button_release $term, $event
631 on_motion_notify $term, $event
632 on_map_notify $term, $event
633 on_unmap_notify $term, $event
634 Called whenever the corresponding X event is received for the
635 terminal. If the hook returns true, then the event will be ignored
636 by rxvt-unicode.
637 The event is a hash with most values as named by Xlib (see the
639 XEvent manpage), with the additional members "row" and "col", which
640 are the (real, not screen-based) row and column under the mouse
641 cursor.
642 "on_key_press" additionally receives the string rxvt-unicode would
644 output, if any, in locale-specific encoding.
645 subwindow.
647 on_client_message $term, $event
649 on_wm_protocols $term, $event
650 on_wm_delete_window $term, $event
651 Called when various types of ClientMessage events are received (all
652 with format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
653 on_bell $term
655 Called on receipt of a bell character.
656 Variables in the "urxvt" Package
658 $urxvt::LIBDIR
659 The rxvt-unicode library directory, where, among other things, the
660 perl modules and scripts are stored.
661 $urxvt::RESCLASS, $urxvt::RESCLASS
663 The resource class and name rxvt-unicode uses to look up X
664 resources.
665 $urxvt::RXVTNAME
667 The basename of the installed binaries, usually "urxvt".
668 $urxvt::TERM
670 The current terminal. This variable stores the current
671 "urxvt::term" object, whenever a callback/hook is executing.
672 @urxvt::TERM_INIT
674 All code references in this array will be called as methods of the
675 next newly created "urxvt::term" object (during the "on_init"
676 phase). The array gets cleared before the code references that were
677 in it are being executed, so references can push themselves onto it
678 again if they so desire.
679 This complements to the perl-eval command line option, but gets
681 executed first.
682 @urxvt::TERM_EXT
684 Works similar to @TERM_INIT, but contains perl package/class names,
685 which get registered as normal extensions after calling the hooks
686 in @TERM_INIT but before other extensions. Gets cleared just like
687 @TERM_INIT.
688 Functions in the "urxvt" Package
690 urxvt::fatal $errormessage
691 Fatally aborts execution with the given error message (which should
692 include a trailing newline). Avoid at all costs! The only time this
693 is acceptable (and useful) is in the init hook, where it prevents
694 the terminal from starting up.
695 urxvt::warn $string
697 Calls "rxvt_warn" with the given string which should include a
698 trailing newline. The module also overwrites the "warn" builtin
699 with a function that calls this function.
700 Using this function has the advantage that its output ends up in
702 the correct place, e.g. on stderr of the connecting urxvtc client.
703 Messages have a size limit of 1023 bytes currently.
705 @terms = urxvt::termlist
707 Returns all urxvt::term objects that exist in this process,
708 regardless of whether they are started, being destroyed etc., so be
709 careful. Only term objects that have perl extensions attached will
710 be returned (because there is no urxvt::term objet associated with
711 others).
712 $time = urxvt::NOW
714 Returns the "current time" (as per the event loop).
715 urxvt::CurrentTime
717 urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask,
718 Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask,
719 Button5Mask, AnyModifier
720 urxvt::NoEventMask, KeyPressMask, KeyReleaseMask, ButtonPressMask,
721 ButtonReleaseMask, EnterWindowMask, LeaveWindowMask, PointerMotionMask,
722 PointerMotionHintMask, Button1MotionMask, Button2MotionMask,
723 Button3MotionMask, Button4MotionMask, Button5MotionMask,
724 ButtonMotionMask, KeymapStateMask, ExposureMask, VisibilityChangeMask,
725 StructureNotifyMask, ResizeRedirectMask, SubstructureNotifyMask,
726 SubstructureRedirectMask, FocusChangeMask, PropertyChangeMask,
727 ColormapChangeMask, OwnerGrabButtonMask
728 urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify,
729 EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose,
730 GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify,
731 DestroyNotify, UnmapNotify, MapNotify, MapRequest, ReparentNotify,
732 ConfigureNotify, ConfigureRequest, GravityNotify, ResizeRequest,
733 CirculateNotify, CirculateRequest, PropertyNotify, SelectionClear,
734 SelectionRequest, SelectionNotify, ColormapNotify, ClientMessage,
735 MappingNotify
736 Various constants for use in X calls and event processing.
737 RENDITION
739 Rendition bitsets contain information about colour, font, font styles
740 and similar information for each screen cell.
741 The following "macros" deal with changes in rendition sets. You should
743 never just create a bitset, you should always modify an existing one,
744 as they contain important information required for correct operation of
745 rxvt-unicode.
746 $rend = urxvt::DEFAULT_RSTYLE
748 Returns the default rendition, as used when the terminal is
749 starting up or being reset. Useful as a base to start when creating
750 renditions.
751 $rend = urxvt::OVERLAY_RSTYLE
753 Return the rendition mask used for overlays by default.
754 $rendbit = urxvt::RS_Bold, urxvt::RS_Italic, urxvt::RS_Blink,
756 urxvt::RS_RVid, urxvt::RS_Uline
757 Return the bit that enabled bold, italic, blink, reverse-video and
758 underline, respectively. To enable such a style, just logically OR
759 it into the bitset.
760 $foreground = urxvt::GET_BASEFG $rend
762 $background = urxvt::GET_BASEBG $rend
763 Return the foreground/background colour index, respectively.
764 $rend = urxvt::SET_FGCOLOR $rend, $new_colour
766 $rend = urxvt::SET_BGCOLOR $rend, $new_colour
767 $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
768 Replace the foreground/background colour in the rendition mask with
769 the specified one.
770 $value = urxvt::GET_CUSTOM $rend
772 Return the "custom" value: Every rendition has 5 bits for use by
773 extensions. They can be set and changed as you like and are
774 initially zero.
775 $rend = urxvt::SET_CUSTOM $rend, $new_value
777 Change the custom value.
778 The "urxvt::anyevent" Class
780 The sole purpose of this class is to deliver an interface to the
781 "AnyEvent" module - any module using it will work inside urxvt without
782 further programming. The only exception is that you cannot wait on
783 condition variables, but non-blocking condvar use is ok. What this
784 means is that you cannot use blocking APIs, but the non-blocking
785 variant should work.
786 The "urxvt::term" Class
788 $term = new urxvt::term $envhashref, $rxvtname, [arg...]
789 Creates a new terminal, very similar as if you had started it with
790 system "$rxvtname, arg...". $envhashref must be a reference to a
791 %ENV-like hash which defines the environment of the new terminal.
792 Croaks (and probably outputs an error message) if the new instance
794 couldn't be created. Returns "undef" if the new instance didn't
795 initialise perl, and the terminal object otherwise. The "init" and
796 "start" hooks will be called before this call returns, and are free
797 to refer to global data (which is race free).
798 $term->destroy
800 Destroy the terminal object (close the window, free resources
801 etc.). Please note that urxvt-ml will not exit as long as any event
802 watchers (timers, io watchers) are still active.
803 $term->exec_async ($cmd[, @args])
805 Works like the combination of the "fork"/"exec" builtins, which
806 executes ("starts") programs in the background. This function takes
807 care of setting the user environment before exec'ing the command
808 (e.g. "PATH") and should be preferred over explicit calls to "exec"
809 or "system".
810 Returns the pid of the subprocess or "undef" on error.
812 $isset = $term->option ($optval[, $set])
814 Returns true if the option specified by $optval is enabled, and
815 optionally change it. All option values are stored by name in the
816 hash %urxvt::OPTION. Options not enabled in this binary are not in
817 the hash.
818 Here is a likely non-exhaustive list of option names, please see
820 the source file /src/optinc.h to see the actual list:
821 borderLess console cursorBlink cursorUnderline hold iconic insecure
823 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
824 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
825 scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput
826 scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs
827 transparent tripleclickwords utmpInhibit visualBell
828 $value = $term->resource ($name[, $newval])
830 Returns the current resource value associated with a given name and
831 optionally sets a new value. Setting values is most useful in the
832 "init" hook. Unset resources are returned and accepted as "undef".
833 The new value must be properly encoded to a suitable character
835 encoding before passing it to this method. Similarly, the returned
836 value may need to be converted from the used encoding to text.
837 Resource names are as defined in src/rsinc.h. Colours can be
839 specified as resource names of the form "color+<index>", e.g.
840 "color+5". (will likely change).
841 Please note that resource strings will currently only be freed when
843 the terminal is destroyed, so changing options frequently will eat
844 memory.
845 Here is a likely non-exhaustive list of resource names, not all of
847 which are supported in every build, please see the source file
848 /src/rsinc.h to see the actual list:
849 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
851 borderLess chdir color cursorBlink cursorUnderline cutchars delete_key
852 display_name embed ext_bwidth fade font geometry hold iconName
853 imFont imLocale inputMethod insecure int_bwidth intensityStyles
854 italicFont jumpScroll lineSpace letterSpace loginShell mapAlert meta8
855 modifier mouseWheelScrollPage name override_redirect pastableTabs path
856 perl_eval perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
857 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
858 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
859 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
860 secondaryScreen secondaryScroll shade term_name title
861 transient_for transparent transparent_all tripleclickwords utmpInhibit
862 visualBell
863 $value = $term->x_resource ($pattern)
865 Returns the X-Resource for the given pattern, excluding the program
866 or class name, i.e. "$term->x_resource ("boldFont")" should return
867 the same value as used by this instance of rxvt-unicode. Returns
868 "undef" if no resource with that pattern exists.
869 This method should only be called during the "on_start" hook, as
871 there is only one resource database per display, and later
872 invocations might return the wrong resources.
873 $success = $term->parse_keysym ($keysym_spec, $command_string)
875 Adds a keymap translation exactly as specified via a resource. See
876 the "keysym" resource in the urxvt-ml(1) manpage.
877 $rend = $term->rstyle ([$new_rstyle])
879 Return and optionally change the current rendition. Text that is
880 output by the terminal application will use this style.
881 ($row, $col) = $term->screen_cur ([$row, $col])
883 Return the current coordinates of the text cursor position and
884 optionally set it (which is usually bad as applications don't
885 expect that).
886 ($row, $col) = $term->selection_mark ([$row, $col])
888 ($row, $col) = $term->selection_beg ([$row, $col])
889 ($row, $col) = $term->selection_end ([$row, $col])
890 Return the current values of the selection mark, begin or end
891 positions.
892 When arguments are given, then the selection coordinates are set to
894 $row and $col, and the selection screen is set to the current
895 screen.
896 $screen = $term->selection_screen ([$screen])
898 Returns the current selection screen, and then optionally sets it.
899 $term->selection_make ($eventtime[, $rectangular])
901 Tries to make a selection as set by "selection_beg" and
902 "selection_end". If $rectangular is true (default: false), a
903 rectangular selection will be made. This is the preferred function
904 to make a selection.
905 $success = $term->selection_grab ($eventtime[, $clipboard])
907 Try to acquire ownership of the primary (clipboard if $clipboard is
908 true) selection from the server. The corresponding text can be set
909 with the next method. No visual feedback will be given. This
910 function is mostly useful from within "on_sel_grab" hooks.
911 $oldtext = $term->selection ([$newtext, $clipboard])
913 Return the current selection (clipboard if $clipboard is true) text
914 and optionally replace it by $newtext.
915 $term->selection_clear ([$clipboard])
917 Revoke ownership of the primary (clipboard if $clipboard is true)
918 selection.
919 $term->overlay_simple ($x, $y, $text)
921 Create a simple multi-line overlay box. See the next method for
922 details.
923 $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
925 Create a new (empty) overlay at the given position with the given
926 width/height. $rstyle defines the initial rendition style (default:
927 "OVERLAY_RSTYLE").
928 If $border is 2 (default), then a decorative border will be put
930 around the box.
931 If either $x or $y is negative, then this is counted from the
933 right/bottom side, respectively.
934 This method returns an urxvt::overlay object. The overlay will be
936 visible as long as the perl object is referenced.
937 The methods currently supported on "urxvt::overlay" objects are:
939 $overlay->set ($x, $y, $text[, $rend])
941 Similar to "$term->ROW_t" and "$term->ROW_r" in that it puts
942 text in rxvt-unicode's special encoding and an array of
943 rendition values at a specific position inside the overlay.
944 If $rend is missing, then the rendition will not be changed.
946 $overlay->hide
948 If visible, hide the overlay, but do not destroy it.
949 $overlay->show
951 If hidden, display the overlay again.
952 $popup = $term->popup ($event)
954 Creates a new "urxvt::popup" object that implements a popup menu.
955 The $event must be the event causing the menu to pop up (a button
956 event, currently).
957 $cellwidth = $term->strwidth ($string)
959 Returns the number of screen-cells this string would need.
960 Correctly accounts for wide and combining characters.
961 $octets = $term->locale_encode ($string)
963 Convert the given text string into the corresponding locale
964 encoding.
965 $string = $term->locale_decode ($octets)
967 Convert the given locale-encoded octets into a perl string.
968 $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
970 XORs the rendition values in the given span with the provided value
971 (default: "RS_RVid"), which MUST NOT contain font styles. Useful in
972 refresh hooks to provide effects similar to the selection.
973 $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[,
975 $rstyle1[, $rstyle2]])
976 Similar to "scr_xor_span", but xors a rectangle instead. Trailing
977 whitespace will additionally be xored with the $rstyle2, which
978 defaults to "RS_RVid | RS_Uline", which removes reverse video again
979 and underlines it instead. Both styles MUST NOT contain font
980 styles.
981 $term->scr_bell
983 Ring the bell!
984 $term->scr_add_lines ($string)
986 Write the given text string to the screen, as if output by the
987 application running inside the terminal. It may not contain command
988 sequences (escape codes), but is free to use line feeds, carriage
989 returns and tabs. The string is a normal text string, not in
990 locale-dependent encoding.
991 Normally its not a good idea to use this function, as programs
993 might be confused by changes in cursor position or scrolling. Its
994 useful inside a "on_add_lines" hook, though.
995 $term->scr_change_screen ($screen)
997 Switch to given screen - 0 primary, 1 secondary.
998 $term->cmd_parse ($octets)
1000 Similar to "scr_add_lines", but the argument must be in the locale-
1001 specific encoding of the terminal and can contain command sequences
1002 (escape codes) that will be interpreted.
1003 $term->tt_write ($octets)
1005 Write the octets given in $octets to the tty (i.e. as program
1006 input). To pass characters instead of octets, you should convert
1007 your strings first to the locale-specific encoding using
1008 "$term->locale_encode".
1009 $term->tt_paste ($octets)
1011 Write the octets given in $octets to the tty as a paste, converting
1012 NL to CR and bracketing the data with control sequences if
1013 bracketed paste mode is set.
1014 $old_events = $term->pty_ev_events ([$new_events])
1016 Replaces the event mask of the pty watcher by the given event mask.
1017 Can be used to suppress input and output handling to the pty/tty.
1018 See the description of "urxvt::timer->events". Make sure to always
1019 restore the previous value.
1020 $fd = $term->pty_fd
1022 Returns the master file descriptor for the pty in use, or "-1" if
1023 no pty is used.
1024 $windowid = $term->parent
1026 Return the window id of the toplevel window.
1027 $windowid = $term->vt
1029 Return the window id of the terminal window.
1030 $term->vt_emask_add ($x_event_mask)
1032 Adds the specified events to the vt event mask. Useful e.g. when
1033 you want to receive pointer events all the times:
1034 $term->vt_emask_add (urxvt::PointerMotionMask);
1036 $term->focus_in
1038 $term->focus_out
1039 $term->key_press ($state, $keycode[, $time])
1040 $term->key_release ($state, $keycode[, $time])
1041 Deliver various fake events to to terminal.
1042 $window_width = $term->width
1044 $window_height = $term->height
1045 $font_width = $term->fwidth
1046 $font_height = $term->fheight
1047 $font_ascent = $term->fbase
1048 $terminal_rows = $term->nrow
1049 $terminal_columns = $term->ncol
1050 $has_focus = $term->focus
1051 $is_mapped = $term->mapped
1052 $max_scrollback = $term->saveLines
1053 $nrow_plus_saveLines = $term->total_rows
1054 $topmost_scrollback_row = $term->top_row
1055 Return various integers describing terminal characteristics.
1056 $x_display = $term->display_id
1058 Return the DISPLAY used by rxvt-unicode.
1059 $lc_ctype = $term->locale
1061 Returns the LC_CTYPE category string used by this rxvt-unicode.
1062 $env = $term->env
1064 Returns a copy of the environment in effect for the terminal as a
1065 hashref similar to "\%ENV".
1066 @envv = $term->envv
1068 Returns the environment as array of strings of the form
1069 "VAR=VALUE".
1070 @argv = $term->argv
1072 Return the argument vector as this terminal, similar to @ARGV, but
1073 includes the program name as first element.
1074 $modifiermask = $term->ModLevel3Mask
1076 $modifiermask = $term->ModMetaMask
1077 $modifiermask = $term->ModNumLockMask
1078 Return the modifier masks corresponding to the "ISO Level 3 Shift"
1079 (often AltGr), the meta key (often Alt) and the num lock key, if
1080 applicable.
1081 $screen = $term->current_screen
1083 Returns the currently displayed screen (0 primary, 1 secondary).
1084 $cursor_is_hidden = $term->hidden_cursor
1086 Returns whether the cursor is currently hidden or not.
1087 $view_start = $term->view_start ([$newvalue])
1089 Returns the row number of the topmost displayed line. Maximum value
1090 is 0, which displays the normal terminal contents. Lower values
1091 scroll this many lines into the scrollback buffer.
1092 $term->want_refresh
1094 Requests a screen refresh. At the next opportunity, rxvt-unicode
1095 will compare the on-screen display with its stored representation.
1096 If they differ, it redraws the differences.
1097 Used after changing terminal contents to display them.
1099 $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
1101 Returns the text of the entire row with number $row_number. Row
1102 "$term->top_row" is the topmost terminal line, row "$term->nrow-1"
1103 is the bottommost terminal line. Nothing will be returned if a
1104 nonexistent line is requested.
1105 If $new_text is specified, it will replace characters in the
1107 current line, starting at column $start_col (default 0), which is
1108 useful to replace only parts of a line. The font index in the
1109 rendition will automatically be updated.
1110 $text is in a special encoding: tabs and wide characters that use
1112 more than one cell when displayed are padded with $urxvt::NOCHAR
1113 (chr 65535) characters. Characters with combining characters and
1114 other characters that do not fit into the normal text encoding will
1115 be replaced with characters in the private use area.
1116 You have to obey this encoding when changing text. The advantage is
1118 that "substr" and similar functions work on screen cells and not on
1119 characters.
1120 The methods "$term->special_encode" and "$term->special_decode" can
1122 be used to convert normal strings into this encoding and vice
1123 versa.
1124 $rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])
1126 Like "$term->ROW_t", but returns an arrayref with rendition
1127 bitsets. Rendition bitsets contain information about colour, font,
1128 font styles and similar information. See also "$term->ROW_t".
1129 When setting rendition, the font mask will be ignored.
1131 See the section on RENDITION, above.
1133 $length = $term->ROW_l ($row_number[, $new_length])
1135 Returns the number of screen cells that are in use ("the line
1136 length"). Unlike the urxvt core, this returns "$term->ncol" if the
1137 line is joined with the following one.
1138 $bool = $term->is_longer ($row_number)
1140 Returns true if the row is part of a multiple-row logical "line"
1141 (i.e. joined with the following row), which means all characters
1142 are in use and it is continued on the next row (and possibly a
1143 continuation of the previous row(s)).
1144 $line = $term->line ($row_number)
1146 Create and return a new "urxvt::line" object that stores
1147 information about the logical line that row $row_number is part of.
1148 It supports the following methods:
1149 $text = $line->t ([$new_text])
1151 Returns or replaces the full text of the line, similar to
1152 "ROW_t"
1153 $rend = $line->r ([$new_rend])
1155 Returns or replaces the full rendition array of the line,
1156 similar to "ROW_r"
1157 $length = $line->l
1159 Returns the length of the line in cells, similar to "ROW_l".
1160 $rownum = $line->beg
1162 $rownum = $line->end
1163 Return the row number of the first/last row of the line,
1164 respectively.
1165 $offset = $line->offset_of ($row, $col)
1167 Returns the character offset of the given row|col pair within
1168 the logical line. Works for rows outside the line, too, and
1169 returns corresponding offsets outside the string.
1170 ($row, $col) = $line->coord_of ($offset)
1172 Translates a string offset into terminal coordinates again.
1173 $text = $term->special_encode $string
1175 Converts a perl string into the special encoding used by rxvt-
1176 unicode, where one character corresponds to one screen cell. See
1177 "$term->ROW_t" for details.
1178 $string = $term->special_decode $text
1180 Converts rxvt-unicodes text representation into a perl string. See
1181 "$term->ROW_t" for details.
1182 $success = $term->grab_button ($button, $modifiermask[, $window =
1184 $term->vt])
1185 $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1186 Register/unregister a synchronous button grab. See the XGrabButton
1187 manpage.
1188 $success = $term->grab ($eventtime[, $sync])
1190 Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1191 synchronous ($sync is true). Also remembers the grab timestamp.
1192 $term->allow_events_async
1194 Calls XAllowEvents with AsyncBoth for the most recent grab.
1195 $term->allow_events_sync
1197 Calls XAllowEvents with SyncBoth for the most recent grab.
1198 $term->allow_events_replay
1200 Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for
1201 the most recent grab.
1202 $term->ungrab
1204 Calls XUngrabPointer and XUngrabKeyboard for the most recent grab.
1205 Is called automatically on evaluation errors, as it is better to
1206 lose the grab in the error case as the session.
1207 $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
1209 $atom_name = $term->XGetAtomName ($atom)
1210 @atoms = $term->XListProperties ($window)
1211 ($type,$format,$octets) = $term->XGetWindowProperty ($window,
1212 $property)
1213 $term->XChangeProperty ($window, $property, $type, $format, $octets)
1214 $term->XDeleteProperty ($window, $property)
1215 $window = $term->DefaultRootWindow
1216 $term->XReparentWindow ($window, $parent, [$x, $y])
1217 $term->XMapWindow ($window)
1218 $term->XUnmapWindow ($window)
1219 $term->XMoveResizeWindow ($window, $x, $y, $width, $height)
1220 ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x,
1221 $y)
1222 $term->XChangeInput ($window, $add_events[, $del_events])
1223 Various X or X-related functions. The $term object only serves as
1224 the source of the display, otherwise those functions map more-or-
1225 less directly onto the X functions of the same name.
1226 The "urxvt::popup" Class
1228 $popup->add_title ($title)
1229 Adds a non-clickable title to the popup.
1230 $popup->add_separator ([$sepchr])
1232 Creates a separator, optionally using the character given as
1233 $sepchr.
1234 $popup->add_button ($text, $cb)
1236 Adds a clickable button to the popup. $cb is called whenever it is
1237 selected.
1238 $popup->add_toggle ($text, $initial_value, $cb)
1240 Adds a toggle/checkbox item to the popup. The callback gets called
1241 whenever it gets toggled, with a boolean indicating its new value
1242 as its first argument.
1243 $popup->show
1245 Displays the popup (which is initially hidden).
1246 The "urxvt::timer" Class
1248 This class implements timer watchers/events. Time is represented as a
1249 fractional number of seconds since the epoch. Example:
1250 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
1252 $term->{timer} = urxvt::timer
1253 ->new
1254 ->interval (1)
1255 ->cb (sub {
1256 $term->{overlay}->set (0, 0,
1257 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
1258 });
1259 $timer = new urxvt::timer
1261 Create a new timer object in started state. It is scheduled to fire
1262 immediately.
1263 $timer = $timer->cb (sub { my ($timer) = @_; ... })
1265 Set the callback to be called when the timer triggers.
1266 $timer = $timer->set ($tstamp[, $interval])
1268 Set the time the event is generated to $tstamp (and optionally
1269 specifies a new $interval).
1270 $timer = $timer->interval ($interval)
1272 By default (and when $interval is 0), the timer will automatically
1273 stop after it has fired once. If $interval is non-zero, then the
1274 timer is automatically rescheduled at the given intervals.
1275 $timer = $timer->start
1277 Start the timer.
1278 $timer = $timer->start ($tstamp[, $interval])
1280 Set the event trigger time to $tstamp and start the timer.
1281 Optionally also replaces the interval.
1282 $timer = $timer->after ($delay[, $interval])
1284 Like "start", but sets the expiry timer to c<urxvt::NOW + $delay>.
1285 $timer = $timer->stop
1287 Stop the timer.
1288 The "urxvt::iow" Class
1290 This class implements io watchers/events. Example:
1291 $term->{socket} = ...
1293 $term->{iow} = urxvt::iow
1294 ->new
1295 ->fd (fileno $term->{socket})
1296 ->events (urxvt::EV_READ)
1297 ->start
1298 ->cb (sub {
1299 my ($iow, $revents) = @_;
1300 # $revents must be 1 here, no need to check
1301 sysread $term->{socket}, my $buf, 8192
1302 or end-of-file;
1303 });
1304 $iow = new urxvt::iow
1306 Create a new io watcher object in stopped state.
1307 $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
1309 Set the callback to be called when io events are triggered.
1310 $reventmask is a bitset as described in the "events" method.
1311 $iow = $iow->fd ($fd)
1313 Set the file descriptor (not handle) to watch.
1314 $iow = $iow->events ($eventmask)
1316 Set the event mask to watch. The only allowed values are
1317 "urxvt::EV_READ" and "urxvt::EV_WRITE", which might be ORed
1318 together, or "urxvt::EV_NONE".
1319 $iow = $iow->start
1321 Start watching for requested events on the given handle.
1322 $iow = $iow->stop
1324 Stop watching for events on the given file handle.
1325 The "urxvt::iw" Class
1327 This class implements idle watchers, that get called automatically when
1328 the process is idle. They should return as fast as possible, after
1329 doing some useful work.
1330 $iw = new urxvt::iw
1332 Create a new idle watcher object in stopped state.
1333 $iw = $iw->cb (sub { my ($iw) = @_; ... })
1335 Set the callback to be called when the watcher triggers.
1336 $timer = $timer->start
1338 Start the watcher.
1339 $timer = $timer->stop
1341 Stop the watcher.
1342 The "urxvt::pw" Class
1344 This class implements process watchers. They create an event whenever a
1345 process exits, after which they stop automatically.
1346 my $pid = fork;
1348 ...
1349 $term->{pw} = urxvt::pw
1350 ->new
1351 ->start ($pid)
1352 ->cb (sub {
1353 my ($pw, $exit_status) = @_;
1354 ...
1355 });
1356 $pw = new urxvt::pw
1358 Create a new process watcher in stopped state.
1359 $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
1361 Set the callback to be called when the timer triggers.
1362 $pw = $timer->start ($pid)
1364 Tells the watcher to start watching for process $pid.
1365 $pw = $pw->stop
1367 Stop the watcher.
1368
1370 URXVT_PERL_VERBOSITY
1371 This variable controls the verbosity level of the perl extension.
1372 Higher numbers indicate more verbose output.
1373 == 0 - fatal messages
1375 >= 3 - script loading and management
1376 >=10 - all called hooks
1377 >=11 - hook return values
1378
1380 Marc Lehmann <schmorp@schmorp.de>
1381 http://software.schmorp.de/pkg/rxvt-unicode
13829.12 2011-06-29 urxvt-ml(3)