5 @@RXVT_NAME@@perl - rxvt-unicode's embedded perl interpreter
9 # create a file grab_test in $HOME:
12 warn "you selected ", $_[0]->selection;
16 # start a @@RXVT_NAME@@ using it:
18 @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test
22 Every time a terminal object gets created, extension scripts specified via
23 the C<perl> resource are loaded and associated with it.
25 Scripts are compiled in a 'use strict' and 'use utf8' environment, and
26 thus must be encoded as UTF-8.
28 Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where
29 scripts will be shared (but not enabled) for all terminals.
31 You can disable the embedded perl interpreter by setting both "perl-ext"
32 and "perl-ext-common" resources to the empty string.
34 =head1 PREPACKAGED EXTENSIONS
36 This section describes the extensions delivered with this release. You can
37 find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>.
39 You can activate them like this:
41 @@RXVT_NAME@@ -pe <extensionname>
43 Or by adding them to the resource for extensions loaded by default:
45 URxvt.perl-ext-common: default,selection-autotransform
49 =item selection (enabled by default)
51 (More) intelligent selection. This extension tries to be more intelligent
52 when the user extends selections (double-click and further clicks). Right
53 now, it tries to select words, urls and complete shell-quoted
54 arguments, which is very convenient, too, if your F<ls> supports
55 C<--quoting-style=shell>.
57 A double-click usually selects the word under the cursor, further clicks
58 will enlarge the selection.
60 The selection works by trying to match a number of regexes and displaying
61 them in increasing order of length. You can add your own regexes by
62 specifying resources of the form:
64 URxvt.selection.pattern-0: perl-regex
65 URxvt.selection.pattern-1: perl-regex
68 The index number (0, 1...) must not have any holes, and each regex must
69 contain at least one pair of capturing parentheses, which will be used for
70 the match. For example, the following adds a regex that matches everything
71 between two vertical bars:
73 URxvt.selection.pattern-0: \\|([^|]+)\\|
75 Another example: Programs I use often output "absolute path: " at the
76 beginning of a line when they process multiple files. The following
77 pattern matches the filename (note, there is a single space at the very
80 URxvt.selection.pattern-0: ^(/[^:]+):\
82 You can look at the source of the selection extension to see more
83 interesting uses, such as parsing a line from beginning to end.
85 This extension also offers following bindable keyboard commands:
91 Rot-13 the selection when activated. Used via keyboard trigger:
93 URxvt.keysym.C-M-r: perl:selection:rot13
97 =item option-popup (enabled by default)
99 Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at
102 Other extensions can extend this popup menu by pushing a code reference
103 onto C<@{ $term->{option_popup_hook} }>, which gets called whenever the
104 popup is being displayed.
106 Its sole argument is the popup menu, which can be modified. It should
107 either return nothing or a string, the initial boolean value and a code
108 reference. The string will be used as button text and the code reference
109 will be called when the toggle changes, with the new boolean value as
112 The following will add an entry C<myoption> that changes
113 C<< $self->{myoption} >>:
115 push @{ $self->{term}{option_popup_hook} }, sub {
116 ("my option" => $myoption, sub { $self->{myoption} = $_[0] })
119 =item selection-popup (enabled by default)
121 Binds a popup menu to Ctrl-Button3 that lets you convert the selection
122 text into various other formats/action (such as uri unescaping, perl
123 evaluation, web-browser starting etc.), depending on content.
125 Other extensions can extend this popup menu by pushing a code reference
126 onto C<@{ $term->{selection_popup_hook} }>, which gets called whenever the
127 popup is being displayed.
129 Its sole argument is the popup menu, which can be modified. The selection
130 is in C<$_>, which can be used to decide whether to add something or not.
131 It should either return nothing or a string and a code reference. The
132 string will be used as button text and the code reference will be called
133 when the button gets activated and should transform C<$_>.
135 The following will add an entry C<a to b> that transforms all C<a>s in
136 the selection to C<b>s, but only if the selection currently contains any
139 push @{ $self->{term}{selection_popup_hook} }, sub {
140 /a/ ? ("a to b" => sub { s/a/b/g }
144 =item searchable-scrollback<hotkey> (enabled by default)
146 Adds regex search functionality to the scrollback buffer, triggered
147 by a hotkey (default: C<M-s>). While in search mode, normal terminal
148 input/output is suspended and a regex is displayed at the bottom of the
151 Inputting characters appends them to the regex and continues incremental
152 search. C<BackSpace> removes a character from the regex, C<Up> and C<Down>
153 search upwards/downwards in the scrollback buffer, C<End> jumps to the
154 bottom. C<Escape> leaves search mode and returns to the point where search
155 was started, while C<Enter> or C<Return> stay at the current position and
156 additionally stores the first match in the current line into the primary
157 selection if the C<Shift> modifier is active.
159 The regex defaults to "(?i)", resulting in a case-insensitive search. To
160 get a case-sensitive search you can delete this prefix using C<BackSpace>
161 or simply use an uppercase character which removes the "(?i)" prefix.
163 See L<perlre> for more info about perl regular expression syntax.
165 =item readline (enabled by default)
167 A support package that tries to make editing with readline easier. At
168 the moment, it reacts to clicking shift-left mouse button by trying to
169 move the text cursor to this position. It does so by generating as many
170 cursor-left or cursor-right keypresses as required (this only works
171 for programs that correctly support wide characters).
173 To avoid too many false positives, this is only done when:
177 =item - the tty is in ICANON state.
179 =item - the text cursor is visible.
181 =item - the primary screen is currently being displayed.
183 =item - the mouse is on the same (multi-row-) line as the text cursor.
187 The normal selection mechanism isn't disabled, so quick successive clicks
188 might interfere with selection creation in harmless ways.
190 =item selection-autotransform
192 This selection allows you to do automatic transforms on a selection
193 whenever a selection is made.
195 It works by specifying perl snippets (most useful is a single C<s///>
196 operator) that modify C<$_> as resources:
198 URxvt.selection-autotransform.0: transform
199 URxvt.selection-autotransform.1: transform
202 For example, the following will transform selections of the form
203 C<filename:number>, often seen in compiler messages, into C<vi +$filename
206 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
208 And this example matches the same,but replaces it with vi-commands you can
209 paste directly into your (vi :) editor:
211 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/
213 Of course, this can be modified to suit your needs and your editor :)
215 To expand the example above to typical perl error messages ("XXX at
216 FILENAME line YYY."), you need a slightly more elaborate solution:
218 URxvt.selection.pattern-0: ( at .*? line \\d+[,.])
219 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/
221 The first line tells the selection code to treat the unchanging part of
222 every error message as a selection pattern, and the second line transforms
223 the message into vi commands to load the file.
227 This transforms the terminal into a tabbar with additional terminals, that
228 is, it implements what is commonly referred to as "tabbed terminal". The topmost line
229 displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one
232 Clicking a button will activate that tab. Pressing B<Shift-Left> and
233 B<Shift-Right> will switch to the tab left or right of the current one,
234 while B<Shift-Down> creates a new tab.
236 The tabbar itself can be configured similarly to a normal terminal, but
237 with a resource class of C<URxvt.tabbed>. In addition, it supports the
238 following four resources (shown with defaults):
240 URxvt.tabbed.tabbar-fg: <colour-index, default 3>
241 URxvt.tabbed.tabbar-bg: <colour-index, default 0>
242 URxvt.tabbed.tab-fg: <colour-index, default 0>
243 URxvt.tabbed.tab-bg: <colour-index, default 1>
245 See I<COLOR AND GRAPHICS> in the @@RXVT_NAME@@(1) manpage for valid
250 Uses per-line display filtering (C<on_line_update>) to underline text
251 matching a certain pattern and make it clickable. When clicked with the
252 mouse button specified in the C<matcher.button> resource (default 2, or
253 middle), the program specified in the C<matcher.launcher> resource
254 (default, the C<urlLauncher> resource, C<sensible-browser>) will be started
255 with the matched text as first argument. The default configuration is
256 suitable for matching URLs and launching a web browser, like the
257 former "mark-urls" extension.
259 The default pattern to match URLs can be overridden with the
260 C<matcher.pattern.0> resource, and additional patterns can be specified
261 with numbered patterns, in a manner similar to the "selection" extension.
262 The launcher can also be overridden on a per-pattern basis.
264 It is possible to activate the most recently seen match from the keyboard.
265 Simply bind a keysym to "perl:matcher" as seen in the example below.
267 Example configuration:
269 URxvt.perl-ext: default,matcher
270 URxvt.urlLauncher: sensible-browser
271 URxvt.keysym.C-Delete: perl:matcher
272 URxvt.matcher.button: 1
273 URxvt.matcher.pattern.1: \\bwww\\.[\\w-]+\\.[\\w./?&@#-]*[\\w/-]
274 URxvt.matcher.pattern.2: \\B(/\\S+?):(\\d+)(?=:|$)
275 URxvt.matcher.launcher.2: gvim +$2 $1
279 This (experimental) perl extension implements OnTheSpot editing. It does
280 not work perfectly, and some input methods don't seem to work well with
281 OnTheSpot editing in general, but it seems to work at least for SCIM and
284 You enable it by specifying this extension and a preedit style of
287 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot
291 A very primitive quake-console-like extension. It was inspired by a
292 description of how the programs C<kuake> and C<yakuake> work: Whenever the
293 user presses a global accelerator key (by default C<F10>), the terminal
294 will show or hide itself. Another press of the accelerator key will hide
297 Initially, the window will not be shown when using this extension.
299 This is useful if you need a single terminal that is not using any desktop
300 space most of the time but is quickly available at the press of a key.
302 The accelerator key is grabbed regardless of any modifiers, so this
303 extension will actually grab a physical key just for this function.
305 If you want a quake-like animation, tell your window manager to do so
310 This extension implements some OSC commands to display timed popups on the
311 screen - useful for status displays from within scripts. You have to read
312 the sources for more info.
314 =item block-graphics-to-ascii
316 A not very useful example of filtering all text output to the terminal
317 by replacing all line-drawing characters (U+2500 .. U+259F) by a
318 similar-looking ascii character.
322 Displays a digital clock using the built-in overlay.
324 =item remote-clipboard
326 Somewhat of a misnomer, this extension adds two menu entries to the
327 selection popup that allows one to run external commands to store the
328 selection somewhere and fetch it again.
330 We use it to implement a "distributed selection mechanism", which just
331 means that one command uploads the file to a remote server, and another
334 The commands can be set using the C<URxvt.remote-selection.store> and
335 C<URxvt.remote-selection.fetch> resources. The first should read the
336 selection to store from STDIN (always in UTF-8), the second should provide
337 the selection data on STDOUT (also in UTF-8).
339 The defaults (which are likely useless to you) use rsh and cat:
341 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
342 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
344 =item selection-pastebin
346 This is a little rarely useful extension that uploads the selection as
347 textfile to a remote site (or does other things). (The implementation is
348 not currently secure for use in a multiuser environment as it writes to
351 It listens to the C<selection-pastebin:remote-pastebin> keyboard command,
354 URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin
356 Pressing this combination runs a command with C<%> replaced by the name of
357 the textfile. This command can be set via a resource:
359 URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
361 And the default is likely not useful to anybody but the few people around
364 The name of the textfile is the hex encoded md5 sum of the selection, so
365 the same content should lead to the same filename.
367 After a successful upload the selection will be replaced by the text given
368 in the C<selection-pastebin-url> resource (again, the % is the placeholder
371 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
373 I<Note to xrdb users:> xrdb uses the C preprocessor, which might interpret
374 the double C</> characters as comment start. Use C<\057\057> instead,
375 which works regardless of whether xrdb is used to parse the resource file
378 =item macosx-clipboard and macosx-clipboard-native
380 These two modules implement an extended clipboard for Mac OS X. They are
383 URxvt.perl-ext-common: default,macosx-clipboard
384 URxvt.keysym.M-c: perl:macosx-clipboard:copy
385 URxvt.keysym.M-v: perl:macosx-clipboard:paste
387 The difference between them is that the native variant requires a
388 perl from apple's devkit or so, and C<macosx-clipboard> requires the
389 C<Mac::Pasteboard> module, works with other perls, has fewer bugs, is
392 =item example-refresh-hooks
394 Displays a very simple digital clock in the upper right corner of the
395 window. Illustrates overwriting the refresh callbacks to create your own
400 =head1 API DOCUMENTATION
402 =head2 General API Considerations
404 All objects (such as terminals, time watchers etc.) are typical
405 reference-to-hash objects. The hash can be used to store anything you
406 like. All members starting with an underscore (such as C<_ptr> or
407 C<_hook>) are reserved for internal uses and B<MUST NOT> be accessed or
410 When objects are destroyed on the C++ side, the perl object hashes are
411 emptied, so its best to store related objects such as time watchers and
412 the like inside the terminal object so they get destroyed as soon as the
413 terminal is destroyed.
415 Argument names also often indicate the type of a parameter. Here are some
416 hints on what they mean:
422 Rxvt-unicode's special way of encoding text, where one "unicode" character
423 always represents one screen cell. See L<ROW_t> for a discussion of this format.
427 A perl text string, with an emphasis on I<text>. It can store all unicode
428 characters and is to be distinguished with text encoded in a specific
429 encoding (often locale-specific) and binary data.
433 Either binary data or - more common - a text string encoded in a
438 =head2 Extension Objects
440 Every perl extension is a perl class. A separate perl object is created
441 for each terminal, and each terminal has its own set of extenion objects,
442 which are passed as the first parameter to hooks. So extensions can use
443 their C<$self> object without having to think about clashes with other
444 extensions or other terminals, with the exception of methods and members
445 that begin with an underscore character C<_>: these are reserved for
448 Although it isn't a C<urxvt::term> object, you can call all methods of the
449 C<urxvt::term> class on this object.
451 It has the following methods and data members:
455 =item $urxvt_term = $self->{term}
457 Returns the C<urxvt::term> object associated with this instance of the
458 extension. This member I<must not> be changed in any way.
460 =item $self->enable ($hook_name => $cb, [$hook_name => $cb..])
462 Dynamically enable the given hooks (named without the C<on_> prefix) for
463 this extension, replacing any previous hook. This is useful when you want
464 to overwrite time-critical hooks only temporarily.
466 =item $self->disable ($hook_name[, $hook_name..])
468 Dynamically disable the given hooks.
474 The following subroutines can be declared in extension files, and will be
475 called whenever the relevant event happens.
477 The first argument passed to them is an extension object as described in
478 the in the C<Extension Objects> section.
480 B<All> of these hooks must return a boolean value. If any of the called
481 hooks returns true, then the event counts as being I<consumed>, and the
482 relevant action might not be carried out by the C++ code.
484 I<< When in doubt, return a false value (preferably C<()>). >>
490 Called after a new terminal object has been initialized, but before
491 windows are created or the command gets run. Most methods are unsafe to
492 call or deliver senseless data, as terminal size and other characteristics
493 have not yet been determined. You can safely query and change resources
494 and options, though. For many purposes the C<on_start> hook is a better
499 Called at the very end of initialisation of a new terminal, just before
500 trying to map (display) the toplevel and returning to the main loop.
502 =item on_destroy $term
504 Called whenever something tries to destroy terminal, when the terminal is
505 still fully functional (not for long, though).
509 Called after the screen is "reset" for any reason, such as resizing or
510 control sequences. Here is where you can react on changes to size-related
513 =item on_child_start $term, $pid
515 Called just after the child process has been C<fork>ed.
517 =item on_child_exit $term, $status
519 Called just after the child process has exited. C<$status> is the status
522 =item on_sel_make $term, $eventtime
524 Called whenever a selection has been made by the user, but before the
525 selection text is copied, so changes to the beginning, end or type of the
526 selection will be honored.
528 Returning a true value aborts selection making by urxvt, in which case you
529 have to make a selection yourself by calling C<< $term->selection_grab >>.
531 =item on_sel_grab $term, $eventtime
533 Called whenever a selection has been copied, but before the selection is
534 requested from the server. The selection text can be queried and changed
535 by calling C<< $term->selection >>.
537 Returning a true value aborts selection grabbing. It will still be highlighted.
539 =item on_sel_extend $term
541 Called whenever the user tries to extend the selection (e.g. with a double
542 click) and is either supposed to return false (normal operation), or
543 should extend the selection itself and return true to suppress the built-in
544 processing. This can happen multiple times, as long as the callback
545 returns true, it will be called on every further click by the user and is
546 supposed to enlarge the selection more and more, if possible.
548 See the F<selection> example extension.
550 =item on_view_change $term, $offset
552 Called whenever the view offset changes, i.e. the user or program
553 scrolls. Offset C<0> means display the normal terminal, positive values
554 show this many lines of scrollback.
556 =item on_scroll_back $term, $lines, $saved
558 Called whenever lines scroll out of the terminal area into the scrollback
559 buffer. C<$lines> is the number of lines scrolled out and may be larger
560 than the scroll back buffer or the terminal.
562 It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
563 $nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
564 number of lines that will be in the scrollback buffer.
566 =item on_osc_seq $term, $op, $args, $resp
568 Called on every OSC sequence and can be used to suppress it or modify its
569 behaviour. The default should be to return an empty list. A true value
570 suppresses execution of the request completely. Make sure you don't get
571 confused by recursive invocations when you output an OSC sequence within
574 C<on_osc_seq_perl> should be used for new behaviour.
576 =item on_osc_seq_perl $term, $args, $resp
578 Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
579 operating system command) is processed. Cursor position and other state
580 information is up-to-date when this happens. For interoperability, the
581 string should start with the extension name (sans -osc) and a semicolon,
582 to distinguish it from commands for other extensions, and this might be
583 enforced in the future.
585 For example, C<overlay-osc> uses this:
587 sub on_osc_seq_perl {
588 my ($self, $osc, $resp) = @_;
590 return unless $osc =~ s/^overlay;//;
592 ... process remaining $osc string
595 Be careful not ever to trust (in a security sense) the data you receive,
596 as its source can not easily be controlled (e-mail content, messages from
597 other users on the same system etc.).
599 For responses, C<$resp> contains the end-of-args separator used by the
602 =item on_add_lines $term, $string
604 Called whenever text is about to be output, with the text as argument. You
605 can filter/change and output the text yourself by returning a true value
606 and calling C<< $term->scr_add_lines >> yourself. Please note that this
607 might be very slow, however, as your hook is called for B<all> text being
610 =item on_tt_write $term, $octets
612 Called whenever some data is written to the tty/pty and can be used to
613 suppress or filter tty input.
615 =item on_line_update $term, $row
617 Called whenever a line was updated or changed. Can be used to filter
618 screen output (e.g. underline urls or other useless stuff). Only lines
619 that are being shown will be filtered, and, due to performance reasons,
620 not always immediately.
622 The row number is always the topmost row of the line if the line spans
625 Please note that, if you change the line, then the hook might get called
626 later with the already-modified line (e.g. if unrelated parts change), so
627 you cannot just toggle rendition bits, but only set them.
629 =item on_refresh_begin $term
631 Called just before the screen gets redrawn. Can be used for overlay or
632 similar effects by modifying the terminal contents in refresh_begin, and
633 restoring them in refresh_end. The built-in overlay and selection display
634 code is run after this hook, and takes precedence.
636 =item on_refresh_end $term
638 Called just after the screen gets redrawn. See C<on_refresh_begin>.
640 =item on_user_command $term, $string
642 Called whenever a user-configured event is being activated (e.g. via
643 a C<perl:string> action bound to a key, see description of the B<keysym>
644 resource in the @@RXVT_NAME@@(1) manpage).
646 The event is simply the action string. This interface is assumed to change
647 slightly in the future.
649 =item on_resize_all_windows $tern, $new_width, $new_height
651 Called just after the new window size has been calculated, but before
652 windows are actually being resized or hints are being set. If this hook
653 returns TRUE, setting of the window hints is being skipped.
655 =item on_x_event $term, $event
657 Called on every X event received on the vt window (and possibly other
658 windows). Should only be used as a last resort. Most event structure
659 members are not passed.
661 =item on_root_event $term, $event
663 Like C<on_x_event>, but is called for events on the root window.
665 =item on_focus_in $term
667 Called whenever the window gets the keyboard focus, before rxvt-unicode
668 does focus in processing.
670 =item on_focus_out $term
672 Called whenever the window loses keyboard focus, before rxvt-unicode does
673 focus out processing.
675 =item on_configure_notify $term, $event
677 =item on_property_notify $term, $event
679 =item on_key_press $term, $event, $keysym, $octets
681 =item on_key_release $term, $event, $keysym
683 =item on_button_press $term, $event
685 =item on_button_release $term, $event
687 =item on_motion_notify $term, $event
689 =item on_map_notify $term, $event
691 =item on_unmap_notify $term, $event
693 Called whenever the corresponding X event is received for the terminal. If
694 the hook returns true, then the event will be ignored by rxvt-unicode.
696 The event is a hash with most values as named by Xlib (see the XEvent
697 manpage), with the additional members C<row> and C<col>, which are the
698 (real, not screen-based) row and column under the mouse cursor.
700 C<on_key_press> additionally receives the string rxvt-unicode would
701 output, if any, in locale-specific encoding.
705 =item on_client_message $term, $event
707 =item on_wm_protocols $term, $event
709 =item on_wm_delete_window $term, $event
711 Called when various types of ClientMessage events are received (all with
712 format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
716 Called on receipt of a bell character.
735 our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
743 our $NOCHAR = chr 0xffff;
745 =head2 Variables in the C<urxvt> Package
751 The rxvt-unicode library directory, where, among other things, the perl
752 modules and scripts are stored.
754 =item $urxvt::RESCLASS, $urxvt::RESCLASS
756 The resource class and name rxvt-unicode uses to look up X resources.
758 =item $urxvt::RXVTNAME
760 The basename of the installed binaries, usually C<urxvt>.
764 The current terminal. This variable stores the current C<urxvt::term>
765 object, whenever a callback/hook is executing.
767 =item @urxvt::TERM_INIT
769 All code references in this array will be called as methods of the next newly
770 created C<urxvt::term> object (during the C<on_init> phase). The array
771 gets cleared before the code references that were in it are being executed,
772 so references can push themselves onto it again if they so desire.
774 This complements to the perl-eval command line option, but gets executed
777 =item @urxvt::TERM_EXT
779 Works similar to C<@TERM_INIT>, but contains perl package/class names, which
780 get registered as normal extensions after calling the hooks in C<@TERM_INIT>
781 but before other extensions. Gets cleared just like C<@TERM_INIT>.
785 =head2 Functions in the C<urxvt> Package
789 =item urxvt::fatal $errormessage
791 Fatally aborts execution with the given error message. Avoid at all
792 costs! The only time this is acceptable is when the terminal process
795 =item urxvt::warn $string
797 Calls C<rxvt_warn> with the given string which should not include a
798 newline. The module also overwrites the C<warn> builtin with a function
799 that calls this function.
801 Using this function has the advantage that its output ends up in the
802 correct place, e.g. on stderr of the connecting urxvtc client.
804 Messages have a size limit of 1023 bytes currently.
806 =item @terms = urxvt::termlist
808 Returns all urxvt::term objects that exist in this process, regardless of
809 whether they are started, being destroyed etc., so be careful. Only term
810 objects that have perl extensions attached will be returned (because there
811 is no urxvt::term objet associated with others).
813 =item $time = urxvt::NOW
815 Returns the "current time" (as per the event loop).
817 =item urxvt::CurrentTime
819 =item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
820 Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
821 Button4Mask, Button5Mask, AnyModifier
823 =item urxvt::NoEventMask, KeyPressMask, KeyReleaseMask,
824 ButtonPressMask, ButtonReleaseMask, EnterWindowMask, LeaveWindowMask,
825 PointerMotionMask, PointerMotionHintMask, Button1MotionMask, Button2MotionMask,
826 Button3MotionMask, Button4MotionMask, Button5MotionMask, ButtonMotionMask,
827 KeymapStateMask, ExposureMask, VisibilityChangeMask, StructureNotifyMask,
828 ResizeRedirectMask, SubstructureNotifyMask, SubstructureRedirectMask,
829 FocusChangeMask, PropertyChangeMask, ColormapChangeMask, OwnerGrabButtonMask
831 =item urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify,
832 EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose,
833 GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify, DestroyNotify,
834 UnmapNotify, MapNotify, MapRequest, ReparentNotify, ConfigureNotify,
835 ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify,
836 CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest,
837 SelectionNotify, ColormapNotify, ClientMessage, MappingNotify
839 Various constants for use in X calls and event processing.
845 Rendition bitsets contain information about colour, font, font styles and
846 similar information for each screen cell.
848 The following "macros" deal with changes in rendition sets. You should
849 never just create a bitset, you should always modify an existing one,
850 as they contain important information required for correct operation of
855 =item $rend = urxvt::DEFAULT_RSTYLE
857 Returns the default rendition, as used when the terminal is starting up or
858 being reset. Useful as a base to start when creating renditions.
860 =item $rend = urxvt::OVERLAY_RSTYLE
862 Return the rendition mask used for overlays by default.
864 =item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
866 Return the bit that enabled bold, italic, blink, reverse-video and
867 underline, respectively. To enable such a style, just logically OR it into
870 =item $foreground = urxvt::GET_BASEFG $rend
872 =item $background = urxvt::GET_BASEBG $rend
874 Return the foreground/background colour index, respectively.
876 =item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
878 =item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
880 =item $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
882 Replace the foreground/background colour in the rendition mask with the
885 =item $value = urxvt::GET_CUSTOM $rend
887 Return the "custom" value: Every rendition has 5 bits for use by
888 extensions. They can be set and changed as you like and are initially
891 =item $rend = urxvt::SET_CUSTOM $rend, $new_value
893 Change the custom value.
900 # overwrite perl's warn
901 *CORE::GLOBAL::warn = sub {
902 my $msg = join "", @_;
904 unless $msg =~ /\n$/;
911 my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
914 my ($level, $msg) = @_;
915 warn "$msg\n" if $level <= $verbosity;
920 # load a single script into its own package, once only
921 sub extension_package($) {
924 $extension_pkg{$path} ||= do {
925 $path =~ /([^\/\\]+)$/;
927 $pkg =~ s/[^[:word:]]/_/g;
928 $pkg = "urxvt::ext::$pkg";
930 verbose 3, "loading extension '$path' into package '$pkg'";
932 open my $fh, "<:raw", $path
936 "package $pkg; use strict; use utf8; no warnings 'utf8';\n"
937 . "#line 1 \"$path\"\n{\n"
938 . (do { local $/; <$fh> })
948 our $retval; # return value for urxvt
950 # called by the rxvt core
955 if ($htype == 0) { # INIT
956 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
961 my @init = @TERM_INIT;
963 $_->($TERM) for @init;
966 $TERM->register_package ($_) for @pkg;
969 for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
970 if ($_ eq "default") {
971 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback readline);
972 } elsif (/^-(.*)$/) {
974 } elsif (/^([^<]+)<(.*)>$/) {
975 push @{ $ext_arg{$1} }, $2;
981 for my $ext (sort keys %ext_arg) {
982 my @files = grep -f $_, map "$_/$ext", @dirs;
985 $TERM->register_package (extension_package $files[0], $ext_arg{$ext});
987 warn "perl extension '$ext' not found in perl library search path\n";
991 eval "#line 1 \"--perl-eval resource/argument\"\n" . $TERM->resource ("perl_eval");
997 if (my $cb = $TERM->{_hook}[$htype]) {
998 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
1001 for my $pkg (keys %$cb) {
1002 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg}, @_) };
1003 $retval ||= $retval_;
1006 $TERM->ungrab; # better to lose the grab than the session
1011 verbose 11, "$HOOKNAME[$htype] returning <$retval>"
1012 if $verbosity >= 11;
1015 if ($htype == 1) { # DESTROY
1016 # clear package objects
1017 %$_ = () for values %{ $TERM->{_pkg} };
1026 sub SET_COLOR($$$) {
1027 SET_BGCOLOR (SET_FGCOLOR ($_[0], $_[1]), $_[2])
1032 my ($str, $mask) = (@_, 0);
1033 my %color = ( fg => undef, bg => undef );
1035 for my $spec ( split /\s+/, $str ) {
1036 if ( $spec =~ /^([fb]g)[_:-]?(\d+)/i ) {
1037 $color{lc($1)} = $2;
1039 my $neg = $spec =~ s/^[-^]//;
1040 unless ( exists &{"RS_$spec"} ) {
1041 push @failed, $spec;
1044 my $cur = &{"RS_$spec"};
1052 ($mask, @color{qw(fg bg)}, \@failed)
1055 # urxvt::term::extension
1057 package urxvt::term::extension;
1060 my ($self, %hook) = @_;
1061 my $pkg = $self->{_pkg};
1063 while (my ($name, $cb) = each %hook) {
1064 my $htype = $HOOKTYPE{uc $name};
1066 or Carp::croak "unsupported hook type '$name'";
1068 $self->set_should_invoke ($htype, +1)
1069 unless exists $self->{term}{_hook}[$htype]{$pkg};
1071 $self->{term}{_hook}[$htype]{$pkg} = $cb;
1076 my ($self, @hook) = @_;
1077 my $pkg = $self->{_pkg};
1079 for my $name (@hook) {
1080 my $htype = $HOOKTYPE{uc $name};
1082 or Carp::croak "unsupported hook type '$name'";
1084 $self->set_should_invoke ($htype, -1)
1085 if delete $self->{term}{_hook}[$htype]{$pkg};
1092 $AUTOLOAD =~ /:([^:]+)$/
1093 or die "FATAL: \$AUTOLOAD '$AUTOLOAD' unparsable";
1098 \$proxy->{term}->$1 (\@_)
1101 } or die "FATAL: unable to compile method forwarder: $@";
1110 # urxvt::destroy_hook
1112 sub urxvt::destroy_hook::DESTROY {
1116 sub urxvt::destroy_hook(&) {
1117 bless \shift, urxvt::destroy_hook::
1120 package urxvt::anyevent;
1122 =head2 The C<urxvt::anyevent> Class
1124 The sole purpose of this class is to deliver an interface to the
1125 C<AnyEvent> module - any module using it will work inside urxvt without
1126 further programming. The only exception is that you cannot wait on
1127 condition variables, but non-blocking condvar use is ok. What this means
1128 is that you cannot use blocking APIs, but the non-blocking variant should
1133 our $VERSION = '5.23';
1135 $INC{"urxvt/anyevent.pm"} = 1; # mark us as there
1136 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
1139 my ($class, %arg) = @_;
1145 ->after ($arg{after}, $arg{interval})
1146 ->cb ($arg{interval} ? $cb : sub {
1147 $_[0]->stop; # need to cancel manually
1153 my ($class, %arg) = @_;
1156 my $fd = fileno $arg{fh};
1157 defined $fd or $fd = $arg{fh};
1159 bless [$arg{fh}, urxvt::iow
1162 ->events (($arg{poll} =~ /r/ ? 1 : 0)
1163 | ($arg{poll} =~ /w/ ? 2 : 0))
1166 ], urxvt::anyevent::
1170 my ($class, %arg) = @_;
1181 my ($class, %arg) = @_;
1189 $_[0]->stop; # need to cancel manually
1190 $cb->($_[0]->rpid, $_[0]->rstatus);
1199 Carp::croak "AnyEvent->one_event blocking wait unsupported in urxvt, use a non-blocking API";
1202 package urxvt::term;
1204 =head2 The C<urxvt::term> Class
1210 # find on_xxx subs in the package and register them
1212 sub register_package {
1213 my ($self, $pkg, $argv) = @_;
1217 urxvt::verbose 6, "register package $pkg to $self";
1219 @{"$pkg\::ISA"} = urxvt::term::extension::;
1225 Scalar::Util::weaken ($proxy->{term} = $self);
1227 $self->{_pkg}{$pkg} = $proxy;
1229 for my $name (@HOOKNAME) {
1230 if (my $ref = $pkg->can ("on_" . lc $name)) {
1231 $proxy->enable ($name => $ref);
1236 =item $term = new urxvt::term $envhashref, $rxvtname, [arg...]
1238 Creates a new terminal, very similar as if you had started it with system
1239 C<$rxvtname, arg...>. C<$envhashref> must be a reference to a C<%ENV>-like
1240 hash which defines the environment of the new terminal.
1242 Croaks (and probably outputs an error message) if the new instance
1243 couldn't be created. Returns C<undef> if the new instance didn't
1244 initialise perl, and the terminal object otherwise. The C<init> and
1245 C<start> hooks will be called before this call returns, and are free to
1246 refer to global data (which is race free).
1251 my ($class, $env, @args) = @_;
1253 $env or Carp::croak "environment hash missing in call to urxvt::term->new";
1254 @args or Carp::croak "name argument missing in call to urxvt::term->new";
1256 _new ([ map "$_=$env->{$_}", keys %$env ], \@args);
1259 =item $term->destroy
1261 Destroy the terminal object (close the window, free resources
1262 etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event
1263 watchers (timers, io watchers) are still active.
1265 =item $term->exec_async ($cmd[, @args])
1267 Works like the combination of the C<fork>/C<exec> builtins, which executes
1268 ("starts") programs in the background. This function takes care of setting
1269 the user environment before exec'ing the command (e.g. C<PATH>) and should
1270 be preferred over explicit calls to C<exec> or C<system>.
1272 Returns the pid of the subprocess or C<undef> on error.
1282 if !defined $pid or $pid;
1284 %ENV = %{ $self->env };
1290 =item $isset = $term->option ($optval[, $set])
1292 Returns true if the option specified by C<$optval> is enabled, and
1293 optionally change it. All option values are stored by name in the hash
1294 C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
1296 Here is a likely non-exhaustive list of option names, please see the
1297 source file F</src/optinc.h> to see the actual list:
1299 borderLess console cursorBlink cursorUnderline hold iconic insecure
1300 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
1301 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
1302 scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput
1303 scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs
1304 transparent tripleclickwords utmpInhibit visualBell
1306 =item $value = $term->resource ($name[, $newval])
1308 Returns the current resource value associated with a given name and
1309 optionally sets a new value. Setting values is most useful in the C<init>
1310 hook. Unset resources are returned and accepted as C<undef>.
1312 The new value must be properly encoded to a suitable character encoding
1313 before passing it to this method. Similarly, the returned value may need
1314 to be converted from the used encoding to text.
1316 Resource names are as defined in F<src/rsinc.h>. Colours can be specified
1317 as resource names of the form C<< color+<index> >>, e.g. C<color+5>. (will
1320 Please note that resource strings will currently only be freed when the
1321 terminal is destroyed, so changing options frequently will eat memory.
1323 Here is a likely non-exhaustive list of resource names, not all of which
1324 are supported in every build, please see the source file F</src/rsinc.h>
1325 to see the actual list:
1327 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
1328 borderLess chdir color cursorBlink cursorUnderline cutchars delete_key
1329 display_name embed ext_bwidth fade font geometry hold iconName
1330 imFont imLocale inputMethod insecure int_bwidth intensityStyles
1331 italicFont jumpScroll lineSpace letterSpace loginShell mapAlert meta8
1332 modifier mouseWheelScrollPage name override_redirect pastableTabs path
1333 perl_eval perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
1334 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
1335 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
1336 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
1337 secondaryScreen secondaryScroll shade term_name title
1338 transient_for transparent transparent_all tripleclickwords utmpInhibit
1343 sub resource($$;$) {
1344 my ($self, $name) = (shift, shift);
1345 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
1346 goto &urxvt::term::_resource
1349 =item $value = $term->x_resource ($pattern)
1351 Returns the X-Resource for the given pattern, excluding the program or
1352 class name, i.e. C<< $term->x_resource ("boldFont") >> should return the
1353 same value as used by this instance of rxvt-unicode. Returns C<undef> if no
1354 resource with that pattern exists.
1356 This method should only be called during the C<on_start> hook, as there is
1357 only one resource database per display, and later invocations might return
1358 the wrong resources.
1360 =item $success = $term->parse_keysym ($keysym_spec, $command_string)
1362 Adds a keymap translation exactly as specified via a resource. See the
1363 C<keysym> resource in the @@RXVT_NAME@@(1) manpage.
1365 =item $rend = $term->rstyle ([$new_rstyle])
1367 Return and optionally change the current rendition. Text that is output by
1368 the terminal application will use this style.
1370 =item ($row, $col) = $term->screen_cur ([$row, $col])
1372 Return the current coordinates of the text cursor position and optionally
1373 set it (which is usually bad as applications don't expect that).
1375 =item ($row, $col) = $term->selection_mark ([$row, $col])
1377 =item ($row, $col) = $term->selection_beg ([$row, $col])
1379 =item ($row, $col) = $term->selection_end ([$row, $col])
1381 Return the current values of the selection mark, begin or end positions.
1383 When arguments are given, then the selection coordinates are set to
1384 C<$row> and C<$col>, and the selection screen is set to the current
1387 =item $screen = $term->selection_screen ([$screen])
1389 Returns the current selection screen, and then optionally sets it.
1391 =item $term->selection_make ($eventtime[, $rectangular])
1393 Tries to make a selection as set by C<selection_beg> and
1394 C<selection_end>. If C<$rectangular> is true (default: false), a
1395 rectangular selection will be made. This is the prefered function to make
1398 =item $success = $term->selection_grab ($eventtime)
1400 Try to request the primary selection text from the server (for example, as
1401 set by the next method). No visual feedback will be given. This function
1402 is mostly useful from within C<on_sel_grab> hooks.
1404 =item $oldtext = $term->selection ([$newtext])
1406 Return the current selection text and optionally replace it by C<$newtext>.
1408 =item $term->overlay_simple ($x, $y, $text)
1410 Create a simple multi-line overlay box. See the next method for details.
1414 sub overlay_simple {
1415 my ($self, $x, $y, $text) = @_;
1417 my @lines = split /\n/, $text;
1419 my $w = List::Util::max map $self->strwidth ($_), @lines;
1421 my $overlay = $self->overlay ($x, $y, $w, scalar @lines);
1422 $overlay->set (0, $_, $lines[$_]) for 0.. $#lines;
1427 =item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
1429 Create a new (empty) overlay at the given position with the given
1430 width/height. C<$rstyle> defines the initial rendition style
1431 (default: C<OVERLAY_RSTYLE>).
1433 If C<$border> is C<2> (default), then a decorative border will be put
1436 If either C<$x> or C<$y> is negative, then this is counted from the
1437 right/bottom side, respectively.
1439 This method returns an urxvt::overlay object. The overlay will be visible
1440 as long as the perl object is referenced.
1442 The methods currently supported on C<urxvt::overlay> objects are:
1446 =item $overlay->set ($x, $y, $text[, $rend])
1448 Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts
1449 text in rxvt-unicode's special encoding and an array of rendition values
1450 at a specific position inside the overlay.
1452 If C<$rend> is missing, then the rendition will not be changed.
1454 =item $overlay->hide
1456 If visible, hide the overlay, but do not destroy it.
1458 =item $overlay->show
1460 If hidden, display the overlay again.
1464 =item $popup = $term->popup ($event)
1466 Creates a new C<urxvt::popup> object that implements a popup menu. The
1467 C<$event> I<must> be the event causing the menu to pop up (a button event,
1473 my ($self, $event) = @_;
1475 $self->grab ($event->{time}, 1)
1483 Scalar::Util::weaken $popup->{term};
1485 $self->{_destroy}{$popup} = urxvt::destroy_hook { $popup->{popup}->destroy };
1486 Scalar::Util::weaken $self->{_destroy}{$popup};
1491 =item $cellwidth = $term->strwidth ($string)
1493 Returns the number of screen-cells this string would need. Correctly
1494 accounts for wide and combining characters.
1496 =item $octets = $term->locale_encode ($string)
1498 Convert the given text string into the corresponding locale encoding.
1500 =item $string = $term->locale_decode ($octets)
1502 Convert the given locale-encoded octets into a perl string.
1504 =item $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
1506 XORs the rendition values in the given span with the provided value
1507 (default: C<RS_RVid>), which I<MUST NOT> contain font styles. Useful in
1508 refresh hooks to provide effects similar to the selection.
1510 =item $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, $rstyle2]])
1512 Similar to C<scr_xor_span>, but xors a rectangle instead. Trailing
1513 whitespace will additionally be xored with the C<$rstyle2>, which defaults
1514 to C<RS_RVid | RS_Uline>, which removes reverse video again and underlines
1515 it instead. Both styles I<MUST NOT> contain font styles.
1517 =item $term->scr_bell
1521 =item $term->scr_add_lines ($string)
1523 Write the given text string to the screen, as if output by the application
1524 running inside the terminal. It may not contain command sequences (escape
1525 codes), but is free to use line feeds, carriage returns and tabs. The
1526 string is a normal text string, not in locale-dependent encoding.
1528 Normally its not a good idea to use this function, as programs might be
1529 confused by changes in cursor position or scrolling. Its useful inside a
1530 C<on_add_lines> hook, though.
1532 =item $term->scr_change_screen ($screen)
1534 Switch to given screen - 0 primary, 1 secondary.
1536 =item $term->cmd_parse ($octets)
1538 Similar to C<scr_add_lines>, but the argument must be in the
1539 locale-specific encoding of the terminal and can contain command sequences
1540 (escape codes) that will be interpreted.
1542 =item $term->tt_write ($octets)
1544 Write the octets given in C<$data> to the tty (i.e. as program input). To
1545 pass characters instead of octets, you should convert your strings first
1546 to the locale-specific encoding using C<< $term->locale_encode >>.
1548 =item $old_events = $term->pty_ev_events ([$new_events])
1550 Replaces the event mask of the pty watcher by the given event mask. Can
1551 be used to suppress input and output handling to the pty/tty. See the
1552 description of C<< urxvt::timer->events >>. Make sure to always restore
1555 =item $fd = $term->pty_fd
1557 Returns the master file descriptor for the pty in use, or C<-1> if no pty
1560 =item $windowid = $term->parent
1562 Return the window id of the toplevel window.
1564 =item $windowid = $term->vt
1566 Return the window id of the terminal window.
1568 =item $term->vt_emask_add ($x_event_mask)
1570 Adds the specified events to the vt event mask. Useful e.g. when you want
1571 to receive pointer events all the times:
1573 $term->vt_emask_add (urxvt::PointerMotionMask);
1575 =item $term->focus_in
1577 =item $term->focus_out
1579 =item $term->key_press ($state, $keycode[, $time])
1581 =item $term->key_release ($state, $keycode[, $time])
1583 Deliver various fake events to to terminal.
1585 =item $window_width = $term->width
1587 =item $window_height = $term->height
1589 =item $font_width = $term->fwidth
1591 =item $font_height = $term->fheight
1593 =item $font_ascent = $term->fbase
1595 =item $terminal_rows = $term->nrow
1597 =item $terminal_columns = $term->ncol
1599 =item $has_focus = $term->focus
1601 =item $is_mapped = $term->mapped
1603 =item $max_scrollback = $term->saveLines
1605 =item $nrow_plus_saveLines = $term->total_rows
1607 =item $topmost_scrollback_row = $term->top_row
1609 Return various integers describing terminal characteristics.
1611 =item $x_display = $term->display_id
1613 Return the DISPLAY used by rxvt-unicode.
1615 =item $lc_ctype = $term->locale
1617 Returns the LC_CTYPE category string used by this rxvt-unicode.
1619 =item $env = $term->env
1621 Returns a copy of the environment in effect for the terminal as a hashref
1622 similar to C<\%ENV>.
1624 =item @envv = $term->envv
1626 Returns the environment as array of strings of the form C<VAR=VALUE>.
1628 =item @argv = $term->argv
1630 Return the argument vector as this terminal, similar to @ARGV, but
1631 includes the program name as first element.
1636 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), $_[0]->envv }
1639 =item $modifiermask = $term->ModLevel3Mask
1641 =item $modifiermask = $term->ModMetaMask
1643 =item $modifiermask = $term->ModNumLockMask
1645 Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
1646 AltGr), the meta key (often Alt) and the num lock key, if applicable.
1648 =item $screen = $term->current_screen
1650 Returns the currently displayed screen (0 primary, 1 secondary).
1652 =item $cursor_is_hidden = $term->hidden_cursor
1654 Returns whether the cursor is currently hidden or not.
1656 =item $view_start = $term->view_start ([$newvalue])
1658 Returns the row number of the topmost displayed line. Maximum value is
1659 C<0>, which displays the normal terminal contents. Lower values scroll
1660 this many lines into the scrollback buffer.
1662 =item $term->want_refresh
1664 Requests a screen refresh. At the next opportunity, rxvt-unicode will
1665 compare the on-screen display with its stored representation. If they
1666 differ, it redraws the differences.
1668 Used after changing terminal contents to display them.
1670 =item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
1672 Returns the text of the entire row with number C<$row_number>. Row C<< $term->top_row >>
1673 is the topmost terminal line, row C<< $term->nrow-1 >> is the bottommost
1674 terminal line. Nothing will be returned if a nonexistent line
1677 If C<$new_text> is specified, it will replace characters in the current
1678 line, starting at column C<$start_col> (default C<0>), which is useful
1679 to replace only parts of a line. The font index in the rendition will
1680 automatically be updated.
1682 C<$text> is in a special encoding: tabs and wide characters that use more
1683 than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535)
1684 characters. Characters with combining characters and other characters that
1685 do not fit into the normal text encoding will be replaced with characters
1686 in the private use area.
1688 You have to obey this encoding when changing text. The advantage is
1689 that C<substr> and similar functions work on screen cells and not on
1692 The methods C<< $term->special_encode >> and C<< $term->special_decode >>
1693 can be used to convert normal strings into this encoding and vice versa.
1695 =item $rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])
1697 Like C<< $term->ROW_t >>, but returns an arrayref with rendition
1698 bitsets. Rendition bitsets contain information about colour, font, font
1699 styles and similar information. See also C<< $term->ROW_t >>.
1701 When setting rendition, the font mask will be ignored.
1703 See the section on RENDITION, above.
1705 =item $length = $term->ROW_l ($row_number[, $new_length])
1707 Returns the number of screen cells that are in use ("the line
1708 length"). Unlike the urxvt core, this returns C<< $term->ncol >> if the
1709 line is joined with the following one.
1711 =item $bool = $term->is_longer ($row_number)
1713 Returns true if the row is part of a multiple-row logical "line" (i.e.
1714 joined with the following row), which means all characters are in use
1715 and it is continued on the next row (and possibly a continuation of the
1718 =item $line = $term->line ($row_number)
1720 Create and return a new C<urxvt::line> object that stores information
1721 about the logical line that row C<$row_number> is part of. It supports the
1726 =item $text = $line->t ([$new_text])
1728 Returns or replaces the full text of the line, similar to C<ROW_t>
1730 =item $rend = $line->r ([$new_rend])
1732 Returns or replaces the full rendition array of the line, similar to C<ROW_r>
1734 =item $length = $line->l
1736 Returns the length of the line in cells, similar to C<ROW_l>.
1738 =item $rownum = $line->beg
1740 =item $rownum = $line->end
1742 Return the row number of the first/last row of the line, respectively.
1744 =item $offset = $line->offset_of ($row, $col)
1746 Returns the character offset of the given row|col pair within the logical
1747 line. Works for rows outside the line, too, and returns corresponding
1748 offsets outside the string.
1750 =item ($row, $col) = $line->coord_of ($offset)
1752 Translates a string offset into terminal coordinates again.
1759 my ($self, $row) = @_;
1761 my $maxrow = $self->nrow - 1;
1763 my ($beg, $end) = ($row, $row);
1765 --$beg while $self->ROW_is_longer ($beg - 1);
1766 ++$end while $self->ROW_is_longer ($end) && $end < $maxrow;
1772 ncol => $self->ncol,
1773 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end),
1777 sub urxvt::line::t {
1782 $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
1783 for $self->{beg} .. $self->{end};
1786 defined wantarray &&
1787 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
1791 sub urxvt::line::r {
1796 $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
1797 for $self->{beg} .. $self->{end};
1800 if (defined wantarray) {
1802 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
1804 $#$rend = $self->{len} - 1;
1811 sub urxvt::line::beg { $_[0]{beg} }
1812 sub urxvt::line::end { $_[0]{end} }
1813 sub urxvt::line::l { $_[0]{len} }
1815 sub urxvt::line::offset_of {
1816 my ($self, $row, $col) = @_;
1818 ($row - $self->{beg}) * $self->{ncol} + $col
1821 sub urxvt::line::coord_of {
1822 my ($self, $offset) = @_;
1827 $offset / $self->{ncol} + $self->{beg},
1828 $offset % $self->{ncol}
1832 =item $text = $term->special_encode $string
1834 Converts a perl string into the special encoding used by rxvt-unicode,
1835 where one character corresponds to one screen cell. See
1836 C<< $term->ROW_t >> for details.
1838 =item $string = $term->special_decode $text
1840 Converts rxvt-unicodes text representation into a perl string. See
1841 C<< $term->ROW_t >> for details.
1843 =item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1845 =item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1847 Register/unregister a synchronous button grab. See the XGrabButton
1850 =item $success = $term->grab ($eventtime[, $sync])
1852 Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1853 synchronous (C<$sync> is true). Also remembers the grab timestamp.
1855 =item $term->allow_events_async
1857 Calls XAllowEvents with AsyncBoth for the most recent grab.
1859 =item $term->allow_events_sync
1861 Calls XAllowEvents with SyncBoth for the most recent grab.
1863 =item $term->allow_events_replay
1865 Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most
1870 Calls XUngrabPointer and XUngrabKeyboard for the most recent grab. Is called automatically on
1871 evaluation errors, as it is better to lose the grab in the error case as
1874 =item $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
1876 =item $atom_name = $term->XGetAtomName ($atom)
1878 =item @atoms = $term->XListProperties ($window)
1880 =item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
1882 =item $term->XChangeProperty ($window, $property, $type, $format, $octets)
1884 =item $term->XDeleteProperty ($window, $property)
1886 =item $window = $term->DefaultRootWindow
1888 =item $term->XReparentWindow ($window, $parent, [$x, $y])
1890 =item $term->XMapWindow ($window)
1892 =item $term->XUnmapWindow ($window)
1894 =item $term->XMoveResizeWindow ($window, $x, $y, $width, $height)
1896 =item ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x, $y)
1898 =item $term->XChangeInput ($window, $add_events[, $del_events])
1900 Various X or X-related functions. The C<$term> object only serves as
1901 the source of the display, otherwise those functions map more-or-less
1902 directly onto the X functions of the same name.
1908 package urxvt::popup;
1910 =head2 The C<urxvt::popup> Class
1917 my ($self, $item) = @_;
1919 $item->{rend}{normal} = "\x1b[0;30;47m" unless exists $item->{rend}{normal};
1920 $item->{rend}{hover} = "\x1b[0;30;46m" unless exists $item->{rend}{hover};
1921 $item->{rend}{active} = "\x1b[m" unless exists $item->{rend}{active};
1923 $item->{render} ||= sub { $_[0]{text} };
1925 push @{ $self->{item} }, $item;
1928 =item $popup->add_title ($title)
1930 Adds a non-clickable title to the popup.
1935 my ($self, $title) = @_;
1938 rend => { normal => "\x1b[38;5;11;44m", hover => "\x1b[38;5;11;44m", active => "\x1b[38;5;11;44m" },
1940 activate => sub { },
1944 =item $popup->add_separator ([$sepchr])
1946 Creates a separator, optionally using the character given as C<$sepchr>.
1951 my ($self, $sep) = @_;
1956 rend => { normal => "\x1b[0;30;47m", hover => "\x1b[0;30;47m", active => "\x1b[0;30;47m" },
1958 render => sub { $sep x $self->{term}->ncol },
1959 activate => sub { },
1963 =item $popup->add_button ($text, $cb)
1965 Adds a clickable button to the popup. C<$cb> is called whenever it is
1971 my ($self, $text, $cb) = @_;
1973 $self->add_item ({ type => "button", text => $text, activate => $cb});
1976 =item $popup->add_toggle ($text, $initial_value, $cb)
1978 Adds a toggle/checkbox item to the popup. The callback gets called
1979 whenever it gets toggled, with a boolean indicating its new value as its
1985 my ($self, $text, $value, $cb) = @_;
1991 render => sub { ($_[0]{value} ? "* " : " ") . $text },
1992 activate => sub { $cb->($_[1]{value} = !$_[1]{value}); },
1995 $self->add_item ($item);
2000 Displays the popup (which is initially hidden).
2007 local $urxvt::popup::self = $self;
2009 my $env = $self->{term}->env;
2010 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
2011 delete $env->{LC_ALL};
2012 $env->{LC_CTYPE} = $self->{term}->locale;
2014 my $term = urxvt::term->new (
2016 "--perl-lib" => "", "--perl-ext-common" => "",
2017 "-pty-fd" => -1, "-sl" => 0,
2018 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect",
2019 "--transient-for" => $self->{term}->parent,
2020 "-display" => $self->{term}->display_id,
2021 "-pe" => "urxvt-popup",
2022 ) or die "unable to create popup window\n";
2024 unless (delete $term->{urxvt_popup_init_done}) {
2027 die "unable to initialise popup window\n";
2034 delete $self->{term}{_destroy}{$self};
2035 $self->{term}->ungrab;
2042 package urxvt::watcher;
2044 =head2 The C<urxvt::timer> Class
2046 This class implements timer watchers/events. Time is represented as a
2047 fractional number of seconds since the epoch. Example:
2049 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
2050 $term->{timer} = urxvt::timer
2054 $term->{overlay}->set (0, 0,
2055 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
2060 =item $timer = new urxvt::timer
2062 Create a new timer object in started state. It is scheduled to fire
2065 =item $timer = $timer->cb (sub { my ($timer) = @_; ... })
2067 Set the callback to be called when the timer triggers.
2069 =item $timer = $timer->set ($tstamp[, $interval])
2071 Set the time the event is generated to $tstamp (and optionally specifies a
2074 =item $timer = $timer->interval ($interval)
2076 By default (and when C<$interval> is C<0>), the timer will automatically
2077 stop after it has fired once. If C<$interval> is non-zero, then the timer
2078 is automatically rescheduled at the given intervals.
2080 =item $timer = $timer->start
2084 =item $timer = $timer->start ($tstamp[, $interval])
2086 Set the event trigger time to C<$tstamp> and start the timer. Optionally
2087 also replaces the interval.
2089 =item $timer = $timer->after ($delay[, $interval])
2091 Like C<start>, but sets the expiry timer to c<urxvt::NOW + $delay>.
2093 =item $timer = $timer->stop
2099 =head2 The C<urxvt::iow> Class
2101 This class implements io watchers/events. Example:
2103 $term->{socket} = ...
2104 $term->{iow} = urxvt::iow
2106 ->fd (fileno $term->{socket})
2107 ->events (urxvt::EV_READ)
2110 my ($iow, $revents) = @_;
2111 # $revents must be 1 here, no need to check
2112 sysread $term->{socket}, my $buf, 8192
2119 =item $iow = new urxvt::iow
2121 Create a new io watcher object in stopped state.
2123 =item $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
2125 Set the callback to be called when io events are triggered. C<$reventmask>
2126 is a bitset as described in the C<events> method.
2128 =item $iow = $iow->fd ($fd)
2130 Set the file descriptor (not handle) to watch.
2132 =item $iow = $iow->events ($eventmask)
2134 Set the event mask to watch. The only allowed values are
2135 C<urxvt::EV_READ> and C<urxvt::EV_WRITE>, which might be ORed
2136 together, or C<urxvt::EV_NONE>.
2138 =item $iow = $iow->start
2140 Start watching for requested events on the given handle.
2142 =item $iow = $iow->stop
2144 Stop watching for events on the given file handle.
2148 =head2 The C<urxvt::iw> Class
2150 This class implements idle watchers, that get called automatically when
2151 the process is idle. They should return as fast as possible, after doing
2156 =item $iw = new urxvt::iw
2158 Create a new idle watcher object in stopped state.
2160 =item $iw = $iw->cb (sub { my ($iw) = @_; ... })
2162 Set the callback to be called when the watcher triggers.
2164 =item $timer = $timer->start
2168 =item $timer = $timer->stop
2174 =head2 The C<urxvt::pw> Class
2176 This class implements process watchers. They create an event whenever a
2177 process exits, after which they stop automatically.
2181 $term->{pw} = urxvt::pw
2185 my ($pw, $exit_status) = @_;
2191 =item $pw = new urxvt::pw
2193 Create a new process watcher in stopped state.
2195 =item $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
2197 Set the callback to be called when the timer triggers.
2199 =item $pw = $timer->start ($pid)
2201 Tells the watcher to start watching for process C<$pid>.
2203 =item $pw = $pw->stop
2211 =head2 URXVT_PERL_VERBOSITY
2213 This variable controls the verbosity level of the perl extension. Higher
2214 numbers indicate more verbose output.
2218 =item == 0 - fatal messages
2220 =item >= 3 - script loading and management
2222 =item >=10 - all called hooks
2224 =item >=11 - hook return values
2230 Marc Lehmann <pcg@goof.com>
2231 http://software.schmorp.de/pkg/rxvt-unicode