1urxvtperl(3) RXVT-UNICODE urxvtperl(3)
2
6 urxvtperl - rxvt-unicode's embedded perl interpreter
7
9 # create a file grab_test in some directory:
10 sub on_sel_grab {
12 warn "you selected ", $_[0]->selection;
13 ()
14 }
15 # start a urxvt instance using it:
17 urxvt --perl-lib path/to/somedirectory -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 qw(vars subs)' and 'use utf8'
25 environment, and thus must be encoded as UTF-8.
26 Each script will only ever be loaded once, even in urxvtd, where
28 scripts will be shared (but not enabled) for all terminals.
29 You can disable the embedded perl interpreter by setting both "perl-
31 ext" and "perl-ext-common" resources to the empty string.
32
34 A number of extensions are delivered with this release. You can find
35 them in <libdir>/urxvt/perl/, and the documentation can be viewed using
36 man urxvt-<EXTENSIONNAME>.
37 You can activate them like this:
39 urxvt -pe <extensionname>
41 Or by adding them to the resource for extensions loaded by default:
43 URxvt.perl-ext-common: default,selection-autotransform
45 Extensions may add additional resources and "actions", i.e., methods
47 which can be bound to a key and invoked by the user. An extension can
48 define the resources it support using so called META comments,
49 described below. Similarly to builtin resources, extension resources
50 can also be specified on the command line as long options (with "."
51 replaced by "-"), in which case the corresponding extension is loaded
52 automatically. For this to work the extension must define META comments
53 for its resources.
54
56 General API Considerations
57 All objects (such as terminals, time watchers etc.) are typical
58 reference-to-hash objects. The hash can be used to store anything you
59 like. All members starting with an underscore (such as "_ptr" or
60 "_hook") are reserved for internal uses and MUST NOT be accessed or
61 modified).
62 When objects are destroyed on the C++ side, the perl object hashes are
64 emptied, so its best to store related objects such as time watchers and
65 the like inside the terminal object so they get destroyed as soon as
66 the terminal is destroyed.
67 Argument names also often indicate the type of a parameter. Here are
69 some hints on what they mean:
70 $text
72 Rxvt-unicode's special way of encoding text, where one "unicode"
73 character always represents one screen cell. See ROW_t for a
74 discussion of this format.
75 $string
77 A perl text string, with an emphasis on text. It can store all
78 unicode characters and is to be distinguished with text encoded in
79 a specific encoding (often locale-specific) and binary data.
80 $octets
82 Either binary data or - more common - a text string encoded in a
83 locale-specific way.
84 $keysym
86 an integer that is a valid X11 keysym code. You can convert a
87 string into a keysym and viceversa by using "XStringToKeysym" and
88 "XKeysymToString".
89 Extension Objects
91 Every perl extension is a perl class. A separate perl object is created
92 for each terminal, and each terminal has its own set of extension
93 objects, which are passed as the first parameter to hooks. So
94 extensions can use their $self object without having to think about
95 clashes with other extensions or other terminals, with the exception of
96 methods and members that begin with an underscore character "_": these
97 are reserved for internal use.
98 Although it isn't a "urxvt::term" object, you can call all methods of
100 the "urxvt::term" class on this object.
101 Additional methods only supported for extension objects are described
103 in the "urxvt::extension" section below.
104 META comments
106 Rxvt-unicode recognizes special meta comments in extensions that define
107 different types of metadata. These comments are scanned whenever a
108 terminal is created and are typically used to autoload extensions when
109 their resources or command line parameters are used.
110 Currently, it recognises these comments below. Individual components
112 are separated by colons (":"), and should not contain colons themselves
113 - there is also currently no escaping mechanism provided for this.
114 #:META:RESOURCE:name:type:desc
116 The RESOURCE comment defines a resource used by the extension,
117 where "name" is the resource name, "type" is the resource type,
118 "boolean" or "string", and "desc" is the resource description.
119 The extension will be autoloaded when this resource is specified or
121 used as a command line parameter.
122 Example: matcher provides the "matcher.launcher" resource by having
124 this comment:
125 #:META:RESOURCE:%.launcher:string:default launcher command
127 Example: load this extension when the "-tr" command line option or
129 resource name is used.
130 #:META:RESOURCE:tr:boolean:set root pixmap as background
132 #:META:OSC:number:desc
134 The OSC comment specifies an OSC sequence, where "number" is the
135 numerical OSC code and "desc" is a short description that is
136 currently unused.
137 This will cause the extension to be autoloaded when the OSC
139 sequence is used for the first time.
140 Note that autoloading carries some extra responsibilities with it:
142 although the terminal cannot really protect itself against
143 malicious sources of command sequences, therefore relying on the
144 programs running inside to sanitize data that they output, it is
145 very common for programs to emit command sequences from untrusted
146 sources.
147 While this means that extensions should, as a defense-in-depth
149 mechanism, always consider whether OSC sequences are safe,
150 autoloading automatically exposes any autoloaded extension in all
151 terminal windows, so extra care should be taken.
152 Example: the background extension registers OSC 20 like this:
154 #:META:OSC:20:change/query background image
156 #:META:OSC_PERL:prefix:desc
158 The same as the OSC comment, but for the Perl OSC sequence (777).
159 The "prefix" should be unique among extensions, of course, which is
160 most easily arranged by using the extension name, although this is
161 not required.
162 Example: the overlay-osc extension registers its Perl OSC like
164 this:
165 #:META:OSC_PERL:overlay:man overlay-osc
167 Hooks
169 The following subroutines can be declared in extension files, and will
170 be called whenever the relevant event happens.
171 The first argument passed to them is an extension object as described
173 in the in the "Extension Objects" section.
174 All of these hooks must return a boolean value. If any of the called
176 hooks returns true, then the event counts as being consumed, and the
177 relevant action might not be carried out by the C++ code.
178 When in doubt, return a false value (preferably "()").
180 on_attach $term
182 Called when an extension package is attached to a running terminal
183 instance. Must return true in all cases, and runs with the same
184 limitations as "on_init".
185 Unlike "on_init" or "on_start", this is called when the extension
187 is attached to a terminal, regardless of whether the extension is
188 loaded before or after the terminal is started. Extensions that
189 need to do something before they work can do it in this callback,
190 as opposed to e.g. "on_init", which might not be called.
191 on_init $term
193 Called after a new terminal object has been initialized, but before
194 windows are created or the command gets run. Most methods are
195 unsafe to call or deliver senseless data, as terminal size and
196 other characteristics have not yet been determined. You can safely
197 query and change resources and options, though. For many purposes
198 the "on_start" hook is a better place.
199 on_start $term
201 Called at the very end of initialisation of a new terminal, just
202 before trying to map (display) the toplevel and returning to the
203 main loop.
204 on_destroy $term
206 Called whenever something tries to destroy terminal, when the
207 terminal is still fully functional (not for long, though).
208 on_reset $term
210 Called after the screen is "reset" for any reason, such as resizing
211 or control sequences. Here is where you can react on changes to
212 size-related variables.
213 on_child_start $term, $pid
215 Called just after the child process has been "fork"ed.
216 on_child_exit $term, $status
218 Called just after the child process has exited. $status is the
219 status from "waitpid".
220 on_sel_make $term, $eventtime
222 Called whenever a selection has been made by the user, but before
223 the selection text is copied, so changes to the beginning, end or
224 type of the selection will be honored.
225 Returning a true value aborts selection making by urxvt, in which
227 case you have to make a selection yourself by calling
228 "$term->selection_grab".
229 on_sel_grab $term, $eventtime
231 Called whenever a selection has been copied, but before the
232 selection is requested from the server. The selection text can be
233 queried and changed by calling "$term->selection".
234 Returning a true value aborts selection grabbing. It will still be
236 highlighted.
237 on_sel_extend $term
239 Called whenever the user tries to extend the selection (e.g. with a
240 double click) and is either supposed to return false (normal
241 operation), or should extend the selection itself and return true
242 to suppress the built-in processing. This can happen multiple
243 times, as long as the callback returns true, it will be called on
244 every further click by the user and is supposed to enlarge the
245 selection more and more, if possible.
246 See the selection example extension.
248 on_view_change $term, $offset
250 Called whenever the view offset changes, i.e. the user or program
251 scrolls. Offset 0 means display the normal terminal, positive
252 values show this many lines of scrollback.
253 on_scroll_back $term, $lines, $saved
255 Called whenever lines scroll out of the terminal area into the
256 scrollback buffer. $lines is the number of lines scrolled out and
257 may be larger than the scroll back buffer or the terminal.
258 It is called before lines are scrolled out (so rows 0 .. min
260 ($lines - 1, $nrow - 1) represent the lines to be scrolled out).
261 $saved is the total number of lines that will be in the scrollback
262 buffer.
263 on_osc_seq $term, $op, $args, $resp
265 Called on every OSC sequence and can be used to suppress it or
266 modify its behaviour. The default should be to return an empty
267 list. A true value suppresses execution of the request completely.
268 Make sure you don't get confused by recursive invocations when you
269 output an OSC sequence within this callback.
270 "on_osc_seq_perl" should be used for new behaviour.
272 on_osc_seq_perl $term, $args, $resp
274 Called whenever the ESC ] 777 ; prefix ; string ST command sequence
275 (OSC = operating system command) is processed. Cursor position and
276 other state information is up-to-date when this happens. For
277 interoperability, the argument should start with the extension name
278 (sans -osc) or some other suitable prefix, and a semicolon, to
279 distinguish it from commands for other extensions.
280 For example, "overlay-osc" uses this:
282 sub on_osc_seq_perl {
284 my ($self, $osc, $resp) = @_;
285 return unless $osc =~ s/^overlay;//;
287 ... process remaining $osc string
289 }
290 Be careful not ever to trust (in a security sense) the data you
292 receive, as its source can not easily be controlled (e-mail
293 content, messages from other users on the same system etc.).
294 For responses, $resp contains the end-of-args separator used by the
296 sender.
297 on_add_lines $term, $string
299 Called whenever text is about to be output, with the text as
300 argument. You can filter/change and output the text yourself by
301 returning a true value and calling "$term->scr_add_lines" yourself.
302 Please note that this might be very slow, however, as your hook is
303 called for all text being output.
304 on_tt_write $term, $octets
306 Called whenever some data is written to the tty/pty and can be used
307 to suppress or filter tty input.
308 on_tt_paste $term, $octets
310 Called whenever text is about to be pasted, with the text as
311 argument. You can filter/change and paste the text yourself by
312 returning a true value and calling "$term->tt_paste" yourself.
313 $octets is locale-encoded.
314 on_line_update $term, $row
316 Called whenever a line was updated or changed. Can be used to
317 filter screen output (e.g. underline urls or other useless stuff).
318 Only lines that are being shown will be filtered, and, due to
319 performance reasons, not always immediately.
320 The row number is always the topmost row of the line if the line
322 spans multiple rows.
323 Please note that, if you change the line, then the hook might get
325 called later with the already-modified line (e.g. if unrelated
326 parts change), so you cannot just toggle rendition bits, but only
327 set them.
328 on_refresh_begin $term
330 Called just before the screen gets redrawn. Can be used for overlay
331 or similar effects by modifying the terminal contents in
332 refresh_begin, and restoring them in refresh_end. The built-in
333 overlay and selection display code is run after this hook, and
334 takes precedence.
335 on_refresh_end $term
337 Called just after the screen gets redrawn. See "on_refresh_begin".
338 on_action $term, $string
340 Called whenever an action is invoked for the corresponding
341 extension (e.g. via a "extension:string" builtin action bound to a
342 key, see description of the keysym resource in the urxvt(1)
343 manpage). The event is simply the action string. Note that an
344 action event is always associated to a single extension.
345 on_user_command $term, $string *DEPRECATED*
347 Called whenever a user-configured event is being activated (e.g.
348 via a "perl:string" action bound to a key, see description of the
349 keysym resource in the urxvt(1) manpage).
350 The event is simply the action string. This interface is going away
352 in preference to the "on_action" hook.
353 on_resize_all_windows $term, $new_width, $new_height
355 Called just after the new window size has been calculated, but
356 before windows are actually being resized or hints are being set.
357 If this hook returns a true value, setting of the window hints is
358 being skipped.
359 on_x_event $term, $event
361 Called on every X event received on the vt window (and possibly
362 other windows). Should only be used as a last resort. Most event
363 structure members are not passed.
364 on_root_event $term, $event
366 Like "on_x_event", but is called for events on the root window.
367 on_focus_in $term
369 Called whenever the window gets the keyboard focus, before rxvt-
370 unicode does focus in processing.
371 on_focus_out $term
373 Called whenever the window loses keyboard focus, before rxvt-
374 unicode does focus out processing.
375 on_configure_notify $term, $event
377 on_property_notify $term, $event
378 on_key_press $term, $event, $keysym, $octets
379 on_key_release $term, $event, $keysym
380 on_button_press $term, $event
381 on_button_release $term, $event
382 on_motion_notify $term, $event
383 on_map_notify $term, $event
384 on_unmap_notify $term, $event
385 Called whenever the corresponding X event is received for the
386 terminal. If the hook returns true, then the event will be ignored
387 by rxvt-unicode.
388 The event is a hash with most values as named by Xlib (see the
390 XEvent manpage), with the additional members "row" and "col", which
391 are the (real, not screen-based) row and column under the mouse
392 cursor.
393 "on_key_press" additionally receives the string rxvt-unicode would
395 output, if any, in locale-specific encoding.
396 on_client_message $term, $event
398 on_wm_protocols $term, $event
399 on_wm_delete_window $term, $event
400 Called when various types of ClientMessage events are received (all
401 with format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
402 on_bell $term
404 Called on receipt of a bell character.
405 Variables in the "urxvt" Package
407 $urxvt::LIBDIR
408 The rxvt-unicode library directory, where, among other things, the
409 perl modules and scripts are stored.
410 $urxvt::RESCLASS, $urxvt::RESCLASS
412 The resource class and name rxvt-unicode uses to look up X
413 resources.
414 $urxvt::RXVTNAME
416 The basename of the installed binaries, usually "urxvt".
417 $urxvt::TERM
419 The current terminal. This variable stores the current
420 "urxvt::term" object, whenever a callback/hook is executing.
421 @urxvt::TERM_INIT
423 All code references in this array will be called as methods of the
424 next newly created "urxvt::term" object (during the "on_init"
425 phase). The array gets cleared before the code references that were
426 in it are being executed, so references can push themselves onto it
427 again if they so desire.
428 This complements to the perl-eval command line option, but gets
430 executed first.
431 @urxvt::TERM_EXT
433 Works similar to @TERM_INIT, but contains perl package/class names,
434 which get registered as normal extensions after calling the hooks
435 in @TERM_INIT but before other extensions. Gets cleared just like
436 @TERM_INIT.
437 Functions in the "urxvt" Package
439 urxvt::fatal $errormessage
440 Fatally aborts execution with the given error message (which should
441 include a trailing newline). Avoid at all costs! The only time this
442 is acceptable (and useful) is in the init hook, where it prevents
443 the terminal from starting up.
444 urxvt::warn $string
446 Calls "rxvt_warn" with the given string which should include a
447 trailing newline. The module also overwrites the "warn" builtin
448 with a function that calls this function.
449 Using this function has the advantage that its output ends up in
451 the correct place, e.g. on stderr of the connecting urxvtc client.
452 Messages have a size limit of 1023 bytes currently.
454 @terms = urxvt::termlist
456 Returns all urxvt::term objects that exist in this process,
457 regardless of whether they are started, being destroyed etc., so be
458 careful. Only term objects that have perl extensions attached will
459 be returned (because there is no urxvt::term object associated with
460 others).
461 $time = urxvt::NOW
463 Returns the "current time" (as per the event loop).
464 urxvt::CurrentTime
466 urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask,
467 Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask,
468 Button5Mask, AnyModifier
469 urxvt::NoEventMask, KeyPressMask, KeyReleaseMask, ButtonPressMask,
470 ButtonReleaseMask, EnterWindowMask, LeaveWindowMask, PointerMotionMask,
471 PointerMotionHintMask, Button1MotionMask, Button2MotionMask,
472 Button3MotionMask, Button4MotionMask, Button5MotionMask,
473 ButtonMotionMask, KeymapStateMask, ExposureMask, VisibilityChangeMask,
474 StructureNotifyMask, ResizeRedirectMask, SubstructureNotifyMask,
475 SubstructureRedirectMask, FocusChangeMask, PropertyChangeMask,
476 ColormapChangeMask, OwnerGrabButtonMask
477 urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify,
478 EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose,
479 GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify,
480 DestroyNotify, UnmapNotify, MapNotify, MapRequest, ReparentNotify,
481 ConfigureNotify, ConfigureRequest, GravityNotify, ResizeRequest,
482 CirculateNotify, CirculateRequest, PropertyNotify, SelectionClear,
483 SelectionRequest, SelectionNotify, ColormapNotify, ClientMessage,
484 MappingNotify
485 Various constants for use in X calls and event processing.
486 urxvt::PrivMode_132, PrivMode_132OK, PrivMode_rVideo,
488 PrivMode_relOrigin, PrivMode_Screen, PrivMode_Autowrap,
489 PrivMode_aplCUR, PrivMode_aplKP, PrivMode_HaveBackSpace,
490 PrivMode_BackSpace, PrivMode_ShiftKeys, PrivMode_VisibleCursor,
491 PrivMode_MouseX10, PrivMode_MouseX11, PrivMode_scrollBar,
492 PrivMode_TtyOutputInh, PrivMode_Keypress, PrivMode_smoothScroll,
493 PrivMode_vt52, PrivMode_LFNL, PrivMode_MouseBtnEvent,
494 PrivMode_MouseAnyEvent, PrivMode_BracketPaste, PrivMode_ExtMouseUTF8,
495 PrivMode_ExtMouseUrxvt, PrivMode_BlinkingCursor, PrivMode_mouse_report,
496 PrivMode_Default
497 Constants for checking DEC private modes.
498 RENDITION
500 Rendition bitsets contain information about colour, font, font styles
501 and similar information for each screen cell.
502 The following "macros" deal with changes in rendition sets. You should
504 never just create a bitset, you should always modify an existing one,
505 as they contain important information required for correct operation of
506 rxvt-unicode.
507 $rend = urxvt::DEFAULT_RSTYLE
509 Returns the default rendition, as used when the terminal is
510 starting up or being reset. Useful as a base to start when creating
511 renditions.
512 $rend = urxvt::OVERLAY_RSTYLE
514 Return the rendition mask used for overlays by default.
515 $rendbit = urxvt::RS_Bold, urxvt::RS_Italic, urxvt::RS_Blink,
517 urxvt::RS_RVid, urxvt::RS_Uline
518 Return the bit that enabled bold, italic, blink, reverse-video and
519 underline, respectively. To enable such a style, just logically OR
520 it into the bitset.
521 $foreground = urxvt::GET_BASEFG $rend
523 $background = urxvt::GET_BASEBG $rend
524 Return the foreground/background colour index, respectively.
525 $rend = urxvt::SET_FGCOLOR $rend, $new_colour
527 $rend = urxvt::SET_BGCOLOR $rend, $new_colour
528 $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
529 Replace the foreground/background colour in the rendition mask with
530 the specified one.
531 $value = urxvt::GET_CUSTOM $rend
533 Return the "custom" value: Every rendition has 5 bits for use by
534 extensions. They can be set and changed as you like and are
535 initially zero.
536 $rend = urxvt::SET_CUSTOM $rend, $new_value
538 Change the custom value.
539 The "urxvt::term::extension" class
541 Each extension attached to a terminal object is represented by a
542 "urxvt::term::extension" object.
543 You can use these objects, which are passed to all callbacks to store
545 any state related to the terminal and extension instance.
546 The methods (And data members) documented below can be called on
548 extension objects, in addition to call methods documented for the
549 <urxvt::term> class.
550 $urxvt_term = $self->{term}
552 Returns the "urxvt::term" object associated with this instance of
553 the extension. This member must not be changed in any way.
554 $self->enable ($hook_name => $cb[, $hook_name => $cb..])
556 Dynamically enable the given hooks (named without the "on_" prefix)
557 for this extension, replacing any hook previously installed via
558 "enable" in this extension.
559 This is useful when you want to overwrite time-critical hooks only
561 temporarily.
562 To install additional callbacks for the same hook, you can use the
564 "on" method of the "urxvt::term" class.
565 $self->disable ($hook_name[, $hook_name..])
567 Dynamically disable the given hooks.
568 $guard = $self->on ($hook_name => $cb[, $hook_name => $cb..])
570 Similar to the "enable" enable, but installs additional callbacks
571 for the given hook(s) (that is, it doesn't replace existing
572 callbacks), and returns a guard object. When the guard object is
573 destroyed the callbacks are disabled again.
574 $self->bind_action ($hotkey, $action)
576 $self->x_resource ($pattern)
577 $self->x_resource_boolean ($pattern)
578 These methods support an additional "%" prefix for $action or
579 $pattern when called on an extension object, compared to the
580 "urxvt::term" methods of the same name - see the description of
581 these methods in the "urxvt::term" class for details.
582 The "urxvt::anyevent" Class
584 The sole purpose of this class is to deliver an interface to the
585 "AnyEvent" module - any module using it will work inside urxvt without
586 further programming. The only exception is that you cannot wait on
587 condition variables, but non-blocking condvar use is ok.
588 In practical terms this means is that you cannot use blocking APIs, but
590 the non-blocking variant should work.
591 The "urxvt::term" Class
593 $term = new urxvt::term $envhashref, $rxvtname, [arg...]
594 Creates a new terminal, very similar as if you had started it with
595 system "$rxvtname, arg...". $envhashref must be a reference to a
596 %ENV-like hash which defines the environment of the new terminal.
597 Croaks (and probably outputs an error message) if the new instance
599 couldn't be created. Returns "undef" if the new instance didn't
600 initialise perl, and the terminal object otherwise. The "init" and
601 "start" hooks will be called before this call returns, and are free
602 to refer to global data (which is race free).
603 $term->destroy
605 Destroy the terminal object (close the window, free resources
606 etc.). Please note that urxvt will not exit as long as any event
607 watchers (timers, io watchers) are still active.
608 $term->exec_async ($cmd[, @args])
610 Works like the combination of the "fork"/"exec" builtins, which
611 executes ("starts") programs in the background. This function takes
612 care of setting the user environment before exec'ing the command
613 (e.g. "PATH") and should be preferred over explicit calls to "exec"
614 or "system".
615 It also sets the "URXVT_EXT_WINDOWID" environment variable to the
617 window ID of the terminal ("$self->parent"), similar to the
618 "WINDOWID" variable set for the process spawned inside the
619 terminal.
620 Returns the pid of the subprocess or "undef" on error.
622 $isset = $term->option ($optval[, $set])
624 Returns true if the option specified by $optval is enabled, and
625 optionally change it. All option values are stored by name in the
626 hash %urxvt::OPTION. Options not enabled in this binary are not in
627 the hash.
628 Here is a likely non-exhaustive list of option names, please see
630 the source file /src/optinc.h to see the actual list:
631 borderLess buffered console cursorBlink cursorUnderline hold iconic
633 insecure intensityStyles iso14755 iso14755_52 jumpScroll loginShell
634 mapAlert meta8 mouseWheelScrollPage override_redirect pastableTabs
635 pointerBlank reverseVideo scrollBar scrollBar_floating scrollBar_right
636 scrollTtyKeypress scrollTtyOutput scrollWithBuffer secondaryScreen
637 secondaryScroll skipBuiltinGlyphs skipScroll transparent tripleclickwords
638 urgentOnBell utmpInhibit visualBell disablePasteBrackets
639 $value = $term->resource ($name[, $newval])
641 Returns the current resource value associated with a given name and
642 optionally sets a new value. Setting values is most useful in the
643 "init" hook. Unset resources are returned and accepted as "undef".
644 The new value must be properly encoded to a suitable character
646 encoding before passing it to this method. Similarly, the returned
647 value may need to be converted from the used encoding to text.
648 Resource names are as defined in src/rsinc.h. Colours can be
650 specified as resource names of the form "color+<index>", e.g.
651 "color+5". (will likely change).
652 Please note that resource strings will currently only be freed when
654 the terminal is destroyed, so changing options frequently will eat
655 memory.
656 Here is a likely non-exhaustive list of resource names, not all of
658 which are supported in every build, please see the source file
659 /src/rsinc.h to see the actual list:
660 answerbackstring backgroundPixmap backspace_key blurradius
662 boldFont boldItalicFont borderLess buffered chdir color cursorBlink
663 cursorUnderline cutchars delete_key depth display_name embed ext_bwidth
664 fade font geometry hold iconName iconfile imFont imLocale inputMethod
665 insecure int_bwidth intensityStyles iso14755 iso14755_52 italicFont
666 jumpScroll letterSpace lineSpace loginShell mapAlert meta8 modifier
667 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
668 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
669 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
670 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
671 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
672 secondaryScreen secondaryScroll shade skipBuiltinGlyphs skipScroll
673 term_name title transient_for transparent tripleclickwords urgentOnBell
674 utmpInhibit visualBell rewrapMode disablePasteBrackets
675 $value = $term->x_resource ($pattern)
677 Returns the X-Resource for the given pattern, excluding the program
678 or class name, i.e. "$term->x_resource ("boldFont")" should return
679 the same value as used by this instance of rxvt-unicode. Returns
680 "undef" if no resource with that pattern exists.
681 Extensions that define extra resources also need to call this
683 method to access their values.
684 If the method is called on an extension object (basically, from an
686 extension), then the special prefix "%." will be replaced by the
687 name of the extension and a dot, and the lone string "%" will be
688 replaced by the extension name itself. This makes it possible to
689 code extensions so you can rename them and get a new set of
690 resources without having to change the actual code.
691 This method should only be called during the "on_start" hook, as
693 there is only one resource database per display, and later
694 invocations might return the wrong resources.
695 $value = $term->x_resource_boolean ($pattern)
697 Like "x_resource", above, but interprets the string value as a
698 boolean and returns 1 for true values, 0 for false values and
699 "undef" if the resource or option isn't specified.
700 You should always use this method to parse boolean resources.
702 $action = $term->lookup_keysym ($keysym, $state)
704 Returns the action bound to key combination "($keysym, $state)", if
705 a binding for it exists, and "undef" otherwise.
706 $success = $term->bind_action ($key, $action)
708 Adds a key binding exactly as specified via a "keysym" resource.
709 See the "keysym" resource in the urxvt(1) manpage.
710 To add default bindings for actions, an extension should call
712 "->bind_action" in its "init" hook for every such binding. Doing it
713 in the "init" hook allows users to override or remove the binding
714 again.
715 Example: the "searchable-scrollback" by default binds itself on
717 "Meta-s", using "$self->bind_action", which calls
718 "$term->bind_action".
719 sub init {
721 my ($self) = @_;
722 $self->bind_action ("M-s" => "%:start");
724 }
725 $rend = $term->rstyle ([$new_rstyle])
727 Return and optionally change the current rendition. Text that is
728 output by the terminal application will use this style.
729 ($row, $col) = $term->screen_cur ([$row, $col])
731 Return the current coordinates of the text cursor position and
732 optionally set it (which is usually bad as applications don't
733 expect that).
734 ($row, $col) = $term->selection_mark ([$row, $col])
736 ($row, $col) = $term->selection_beg ([$row, $col])
737 ($row, $col) = $term->selection_end ([$row, $col])
738 Return the current values of the selection mark, begin or end
739 positions.
740 When arguments are given, then the selection coordinates are set to
742 $row and $col, and the selection screen is set to the current
743 screen.
744 $screen = $term->selection_screen ([$screen])
746 Returns the current selection screen, and then optionally sets it.
747 $term->selection_make ($eventtime[, $rectangular])
749 Tries to make a selection as set by "selection_beg" and
750 "selection_end". If $rectangular is true (default: false), a
751 rectangular selection will be made. This is the preferred function
752 to make a selection.
753 $success = $term->selection_grab ($eventtime[, $clipboard])
755 Try to acquire ownership of the primary (clipboard if $clipboard is
756 true) selection from the server. The corresponding text can be set
757 with the next method. No visual feedback will be given. This
758 function is mostly useful from within "on_sel_grab" hooks.
759 $oldtext = $term->selection ([$newtext, $clipboard])
761 Return the current selection (clipboard if $clipboard is true) text
762 and optionally replace it by $newtext.
763 $term->selection_clear ([$clipboard])
765 Revoke ownership of the primary (clipboard if $clipboard is true)
766 selection.
767 $term->overlay_simple ($x, $y, $text)
769 Create a simple multi-line overlay box. See the next method for
770 details.
771 $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
773 Create a new (empty) overlay at the given position with the given
774 width/height. $rstyle defines the initial rendition style (default:
775 "OVERLAY_RSTYLE").
776 If $border is 2 (default), then a decorative border will be put
778 around the box.
779 If either $x or $y is negative, then this is counted from the
781 right/bottom side, respectively.
782 This method returns an urxvt::overlay object. The overlay will be
784 visible as long as the perl object is referenced.
785 The methods currently supported on "urxvt::overlay" objects are:
787 $overlay->set ($x, $y, $text[, $rend])
789 Similar to "$term->ROW_t" and "$term->ROW_r" in that it puts
790 text in rxvt-unicode's special encoding and an array of
791 rendition values at a specific position inside the overlay.
792 If $rend is missing, then the rendition will not be changed.
794 $overlay->hide
796 If visible, hide the overlay, but do not destroy it.
797 $overlay->show
799 If hidden, display the overlay again.
800 $popup = $term->popup ($event)
802 Creates a new "urxvt::popup" object that implements a popup menu.
803 The $event must be the event causing the menu to pop up (a button
804 event, currently).
805 $cellwidth = $term->strwidth ($string)
807 Returns the number of screen-cells this string would need.
808 Correctly accounts for wide and combining characters.
809 $octets = $term->locale_encode ($string)
811 Convert the given text string into the corresponding locale
812 encoding. Returns "undef" if $string is "undef".
813 $string = $term->locale_decode ($octets)
815 Convert the given locale-encoded octets into a perl string. Returns
816 "undef" if $octets is "undef".
817 $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
819 XORs the rendition values in the given span with the provided value
820 (default: "RS_RVid"), which MUST NOT contain font styles. Useful in
821 refresh hooks to provide effects similar to the selection.
822 $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[,
824 $rstyle1[, $rstyle2]])
825 Similar to "scr_xor_span", but xors a rectangle instead. Trailing
826 whitespace will additionally be xored with the $rstyle2, which
827 defaults to "RS_RVid | RS_Uline", which removes reverse video again
828 and underlines it instead. Both styles MUST NOT contain font
829 styles.
830 $term->scr_bell
832 Ring the bell!
833 $term->scr_add_lines ($string)
835 Write the given text string to the screen, as if output by the
836 application running inside the terminal. It may not contain command
837 sequences (escape codes - see "cmd_parse" for that), but is free to
838 use line feeds, carriage returns and tabs. The string is a normal
839 text string, not in locale-dependent encoding.
840 Normally its not a good idea to use this function, as programs
842 might be confused by changes in cursor position or scrolling. Its
843 useful inside a "on_add_lines" hook, though.
844 $term->scr_change_screen ($screen)
846 Switch to given screen - 0 primary, 1 secondary.
847 $term->cmd_parse ($octets)
849 Similar to "scr_add_lines", but the argument must be in the locale-
850 specific encoding of the terminal and can contain command sequences
851 (escape codes) that will be interpreted.
852 $term->tt_write ($octets)
854 Write the octets given in $octets to the tty (i.e. as user input to
855 the program, see "cmd_parse" for the opposite direction). To pass
856 characters instead of octets, you should convert your strings first
857 to the locale-specific encoding using "$term->locale_encode".
858 $term->tt_write_user_input ($octets)
860 Like "tt_write", but should be used when writing strings in
861 response to the user pressing a key, to invoke the additional
862 actions requested by the user for that case ("tt_write" doesn't do
863 that).
864 The typical use case would be inside "on_action" hooks.
866 $term->tt_paste ($octets)
868 Write the octets given in $octets to the tty as a paste, converting
869 NL to CR and bracketing the data with control sequences if
870 bracketed paste mode is set.
871 $old_events = $term->pty_ev_events ([$new_events])
873 Replaces the event mask of the pty watcher by the given event mask.
874 Can be used to suppress input and output handling to the pty/tty.
875 See the description of "urxvt::timer->events". Make sure to always
876 restore the previous value.
877 $fd = $term->pty_fd
879 Returns the master file descriptor for the pty in use, or -1 if no
880 pty is used.
881 $windowid = $term->parent
883 Return the window id of the toplevel window.
884 $windowid = $term->vt
886 Return the window id of the terminal window.
887 $term->vt_emask_add ($x_event_mask)
889 Adds the specified events to the vt event mask. Useful e.g. when
890 you want to receive pointer events all the times:
891 $term->vt_emask_add (urxvt::PointerMotionMask);
893 $term->set_urgency ($set)
895 Enable/disable the urgency hint on the toplevel window.
896 $term->focus_in
898 $term->focus_out
899 $term->key_press ($state, $keycode[, $time])
900 $term->key_release ($state, $keycode[, $time])
901 Deliver various fake events to to terminal.
902 $window_width = $term->width ([$new_value])
904 $window_height = $term->height ([$new_value])
905 $font_width = $term->fwidth ([$new_value])
906 $font_height = $term->fheight ([$new_value])
907 $font_ascent = $term->fbase ([$new_value])
908 $terminal_rows = $term->nrow ([$new_value])
909 $terminal_columns = $term->ncol ([$new_value])
910 $has_focus = $term->focus ([$new_value])
911 $is_mapped = $term->mapped ([$new_value])
912 $max_scrollback = $term->saveLines ([$new_value])
913 $nrow_plus_saveLines = $term->total_rows ([$new_value])
914 $topmost_scrollback_row = $term->top_row ([$new_value])
915 Return various integers describing terminal characteristics. If an
916 argument is given, changes the value and returns the previous one.
917 $x_display = $term->display_id
919 Return the DISPLAY used by rxvt-unicode.
920 $lc_ctype = $term->locale
922 Returns the LC_CTYPE category string used by this rxvt-unicode.
923 $env = $term->env
925 Returns a copy of the environment in effect for the terminal as a
926 hashref similar to "\%ENV".
927 @envv = $term->envv
929 Returns the environment as array of strings of the form
930 "VAR=VALUE".
931 @argv = $term->argv
933 Return the argument vector as this terminal, similar to @ARGV, but
934 includes the program name as first element.
935 $modifiermask = $term->ModLevel3Mask
937 $modifiermask = $term->ModMetaMask
938 $modifiermask = $term->ModNumLockMask
939 Return the modifier masks corresponding to the "ISO Level 3 Shift"
940 (often AltGr), the meta key (often Alt) and the num lock key, if
941 applicable.
942 $screen = $term->current_screen
944 Returns the currently displayed screen (0 primary, 1 secondary).
945 $cursor_is_hidden = $term->hidden_cursor
947 Returns whether the cursor is currently hidden or not.
948 $priv_modes = $term->priv_modes
950 Returns a bitset with the state of DEC private modes.
951 Example:
953 if ($term->priv_modes & urxvt::PrivMode_mouse_report) {
955 # mouse reporting is turned on
956 }
957 $view_start = $term->view_start ([$newvalue])
959 Returns the row number of the topmost displayed line and changes
960 it, if an argument is given. Values greater than or equal to 0
961 display the terminal contents. Lower values scroll this many lines
962 into the scrollback buffer.
963 $term->want_refresh
965 Requests a screen refresh. At the next opportunity, rxvt-unicode
966 will compare the on-screen display with its stored representation.
967 If they differ, it redraws the differences.
968 Used after changing terminal contents to display them.
970 $term->refresh_check
972 Checks if a refresh has been requested and, if so, schedules one.
973 $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
975 Returns the text of the entire row with number $row_number. Row
976 "$term->top_row" is the topmost terminal line, row "$term->nrow-1"
977 is the bottommost terminal line. Nothing will be returned if a
978 nonexistent line is requested.
979 If $new_text is specified, it will replace characters in the
981 current line, starting at column $start_col (default 0), which is
982 useful to replace only parts of a line. The font index in the
983 rendition will automatically be updated.
984 $text is in a special encoding: tabs and wide characters that use
986 more than one cell when displayed are padded with $urxvt::NOCHAR
987 (chr 65535) characters. Characters with combining characters and
988 other characters that do not fit into the normal text encoding will
989 be replaced with characters in the private use area.
990 You have to obey this encoding when changing text. The advantage is
992 that "substr" and similar functions work on screen cells and not on
993 characters.
994 The methods "$term->special_encode" and "$term->special_decode" can
996 be used to convert normal strings into this encoding and vice
997 versa.
998 $rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])
1000 Like "$term->ROW_t", but returns an arrayref with rendition
1001 bitsets. Rendition bitsets contain information about colour, font,
1002 font styles and similar information. See also "$term->ROW_t".
1003 When setting rendition, the font mask will be ignored.
1005 See the section on RENDITION, above.
1007 $length = $term->ROW_l ($row_number[, $new_length])
1009 Returns the number of screen cells that are in use ("the line
1010 length"). Unlike the urxvt core, this returns "$term->ncol" if the
1011 line is joined with the following one.
1012 $bool = $term->is_longer ($row_number)
1014 Returns true if the row is part of a multiple-row logical "line"
1015 (i.e. joined with the following row), which means all characters
1016 are in use and it is continued on the next row (and possibly a
1017 continuation of the previous row(s)).
1018 $line = $term->line ($row_number)
1020 Create and return a new "urxvt::line" object that stores
1021 information about the logical line that row $row_number is part of.
1022 It supports the following methods:
1023 $text = $line->t ([$new_text])
1025 Returns or replaces the full text of the line, similar to
1026 "ROW_t"
1027 $rend = $line->r ([$new_rend])
1029 Returns or replaces the full rendition array of the line,
1030 similar to "ROW_r"
1031 $length = $line->l
1033 Returns the length of the line in cells, similar to "ROW_l".
1034 $rownum = $line->beg
1036 $rownum = $line->end
1037 Return the row number of the first/last row of the line,
1038 respectively.
1039 $offset = $line->offset_of ($row, $col)
1041 Returns the character offset of the given row|col pair within
1042 the logical line. Works for rows outside the line, too, and
1043 returns corresponding offsets outside the string.
1044 ($row, $col) = $line->coord_of ($offset)
1046 Translates a string offset into terminal coordinates again.
1047 $text = $term->special_encode ($string)
1049 Converts a perl string into the special encoding used by rxvt-
1050 unicode, where one character corresponds to one screen cell. See
1051 "$term->ROW_t" for details.
1052 $string = $term->special_decode ($text)
1054 Converts rxvt-unicode's text representation into a perl string. See
1055 "$term->ROW_t" for details.
1056 $success = $term->grab_button ($button, $modifiermask[, $window =
1058 $term->vt])
1059 $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1060 Register/unregister a synchronous button grab. See the XGrabButton
1061 manpage.
1062 $success = $term->grab ($eventtime[, $sync])
1064 Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1065 synchronous ($sync is true). Also remembers the grab timestamp.
1066 $term->allow_events_async
1068 Calls XAllowEvents with AsyncBoth for the most recent grab.
1069 $term->allow_events_sync
1071 Calls XAllowEvents with SyncBoth for the most recent grab.
1072 $term->allow_events_replay
1074 Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for
1075 the most recent grab.
1076 $term->ungrab
1078 Calls XUngrabPointer and XUngrabKeyboard for the most recent grab.
1079 Is called automatically on evaluation errors, as it is better to
1080 lose the grab in the error case as the session.
1081 $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
1083 $atom_name = $term->XGetAtomName ($atom)
1084 @atoms = $term->XListProperties ($window)
1085 ($type,$format,$octets) = $term->XGetWindowProperty ($window,
1086 $property)
1087 $term->XChangeProperty ($window, $property, $type, $format, $octets)
1088 $term->XDeleteProperty ($window, $property)
1089 $window = $term->DefaultRootWindow
1090 $term->XReparentWindow ($window, $parent, [$x, $y])
1091 $term->XMapWindow ($window)
1092 $term->XUnmapWindow ($window)
1093 $term->XMoveResizeWindow ($window, $x, $y, $width, $height)
1094 ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x,
1095 $y)
1096 $term->XChangeInput ($window, $add_events[, $del_events])
1097 $keysym = $term->XStringToKeysym ($string)
1098 $string = $term->XKeysymToString ($keysym)
1099 Various X or X-related functions. The $term object only serves as
1100 the source of the display, otherwise those functions map more-or-
1101 less directly onto the X functions of the same name.
1102 The "urxvt::popup" Class
1104 $popup->add_title ($title)
1105 Adds a non-clickable title to the popup.
1106 $popup->add_separator ([$sepchr])
1108 Creates a separator, optionally using the character given as
1109 $sepchr.
1110 $popup->add_button ($text, $cb)
1112 Adds a clickable button to the popup. $cb is called whenever it is
1113 selected.
1114 $popup->add_toggle ($text, $initial_value, $cb)
1116 Adds a toggle/checkbox item to the popup. The callback gets called
1117 whenever it gets toggled, with a boolean indicating its new value
1118 as its first argument.
1119 $popup->show
1121 Displays the popup (which is initially hidden).
1122 The "urxvt::timer" Class
1124 This class implements timer watchers/events. Time is represented as a
1125 fractional number of seconds since the epoch. Example:
1126 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
1128 $term->{timer} = urxvt::timer
1129 ->new
1130 ->interval (1)
1131 ->cb (sub {
1132 $term->{overlay}->set (0, 0,
1133 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
1134 });
1135 $timer = new urxvt::timer
1137 Create a new timer object in started state. It is scheduled to fire
1138 immediately.
1139 $timer = $timer->cb (sub { my ($timer) = @_; ... })
1141 Set the callback to be called when the timer triggers.
1142 $timer = $timer->set ($tstamp[, $interval])
1144 Set the time the event is generated to $tstamp (and optionally
1145 specifies a new $interval).
1146 $timer = $timer->interval ($interval)
1148 By default (and when $interval is 0), the timer will automatically
1149 stop after it has fired once. If $interval is non-zero, then the
1150 timer is automatically rescheduled at the given intervals.
1151 $timer = $timer->start
1153 Start the timer.
1154 $timer = $timer->start ($tstamp[, $interval])
1156 Set the event trigger time to $tstamp and start the timer.
1157 Optionally also replaces the interval.
1158 $timer = $timer->after ($delay[, $interval])
1160 Like "start", but sets the expiry timer to c<urxvt::NOW + $delay>.
1161 $timer = $timer->stop
1163 Stop the timer.
1164 The "urxvt::iow" Class
1166 This class implements io watchers/events. Example:
1167 $term->{socket} = ...
1169 $term->{iow} = urxvt::iow
1170 ->new
1171 ->fd (fileno $term->{socket})
1172 ->events (urxvt::EV_READ)
1173 ->start
1174 ->cb (sub {
1175 my ($iow, $revents) = @_;
1176 # $revents must be 1 here, no need to check
1177 sysread $term->{socket}, my $buf, 8192
1178 or end-of-file;
1179 });
1180 $iow = new urxvt::iow
1182 Create a new io watcher object in stopped state.
1183 $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
1185 Set the callback to be called when io events are triggered.
1186 $reventmask is a bitset as described in the "events" method.
1187 $iow = $iow->fd ($fd)
1189 Set the file descriptor (not handle) to watch.
1190 $iow = $iow->events ($eventmask)
1192 Set the event mask to watch. The only allowed values are
1193 "urxvt::EV_READ" and "urxvt::EV_WRITE", which might be ORed
1194 together, or "urxvt::EV_NONE".
1195 $iow = $iow->start
1197 Start watching for requested events on the given handle.
1198 $iow = $iow->stop
1200 Stop watching for events on the given file handle.
1201 The "urxvt::iw" Class
1203 This class implements idle watchers, that get called automatically when
1204 the process is idle. They should return as fast as possible, after
1205 doing some useful work.
1206 $iw = new urxvt::iw
1208 Create a new idle watcher object in stopped state.
1209 $iw = $iw->cb (sub { my ($iw) = @_; ... })
1211 Set the callback to be called when the watcher triggers.
1212 $timer = $timer->start
1214 Start the watcher.
1215 $timer = $timer->stop
1217 Stop the watcher.
1218 The "urxvt::pw" Class
1220 This class implements process watchers. They create an event whenever a
1221 process exits, after which they stop automatically.
1222 my $pid = fork;
1224 ...
1225 $term->{pw} = urxvt::pw
1226 ->new
1227 ->start ($pid)
1228 ->cb (sub {
1229 my ($pw, $exit_status) = @_;
1230 ...
1231 });
1232 $pw = new urxvt::pw
1234 Create a new process watcher in stopped state.
1235 $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
1237 Set the callback to be called when the timer triggers.
1238 $pw = $timer->start ($pid)
1240 Tells the watcher to start watching for process $pid.
1241 $pw = $pw->stop
1243 Stop the watcher.
1244
1246 URXVT_PERL_VERBOSITY
1247 This variable controls the verbosity level of the perl extension.
1248 Higher numbers indicate more verbose output.
1249 == 0 - fatal messages only
1251 >= 2 - general warnings (default level)
1252 >= 3 - script loading and management
1253 >=10 - all called hooks
1254 >=11 - hook return values
1255
1257 Marc Lehmann <schmorp@schmorp.de>
1258 http://software.schmorp.de/pkg/rxvt-unicode
12599.31 2023-07-22 urxvtperl(3)