1urxvtperl(3) RXVT-UNICODE urxvtperl(3)
2
6 urxvtperl - rxvt-unicode's embedded perl interpreter
7
9 # create a file grab_test in $HOME:
10 sub on_sel_grab {
12 warn "you selected ", $_[0]->selection;
13 ()
14 }
15 # start a urxvt using it:
17 urxvt --perl-lib $HOME -pe grab_test
19
21 Every time a terminal object gets created, extension scripts specified
22 via the "perl" resource are loaded and associated with it.
23 Scripts are compiled in a 'use strict "vars"' 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 only one such comment:
112 #:META:RESOURCE:name:type:desc
114 The RESOURCE comment defines a resource used by the extension,
115 where "name" is the resource name, "type" is the resource type,
116 "boolean" or "string", and "desc" is the resource description.
117 The extension will be autoloaded when this resource is specified or
119 used as a command line parameter.
120 Hooks
122 The following subroutines can be declared in extension files, and will
123 be called whenever the relevant event happens.
124 The first argument passed to them is an extension object as described
126 in the in the "Extension Objects" section.
127 All of these hooks must return a boolean value. If any of the called
129 hooks returns true, then the event counts as being consumed, and the
130 relevant action might not be carried out by the C++ code.
131 When in doubt, return a false value (preferably "()").
133 on_init $term
135 Called after a new terminal object has been initialized, but before
136 windows are created or the command gets run. Most methods are
137 unsafe to call or deliver senseless data, as terminal size and
138 other characteristics have not yet been determined. You can safely
139 query and change resources and options, though. For many purposes
140 the "on_start" hook is a better place.
141 on_start $term
143 Called at the very end of initialisation of a new terminal, just
144 before trying to map (display) the toplevel and returning to the
145 main loop.
146 on_destroy $term
148 Called whenever something tries to destroy terminal, when the
149 terminal is still fully functional (not for long, though).
150 on_reset $term
152 Called after the screen is "reset" for any reason, such as resizing
153 or control sequences. Here is where you can react on changes to
154 size-related variables.
155 on_child_start $term, $pid
157 Called just after the child process has been "fork"ed.
158 on_child_exit $term, $status
160 Called just after the child process has exited. $status is the
161 status from "waitpid".
162 on_sel_make $term, $eventtime
164 Called whenever a selection has been made by the user, but before
165 the selection text is copied, so changes to the beginning, end or
166 type of the selection will be honored.
167 Returning a true value aborts selection making by urxvt, in which
169 case you have to make a selection yourself by calling
170 "$term->selection_grab".
171 on_sel_grab $term, $eventtime
173 Called whenever a selection has been copied, but before the
174 selection is requested from the server. The selection text can be
175 queried and changed by calling "$term->selection".
176 Returning a true value aborts selection grabbing. It will still be
178 highlighted.
179 on_sel_extend $term
181 Called whenever the user tries to extend the selection (e.g. with a
182 double click) and is either supposed to return false (normal
183 operation), or should extend the selection itself and return true
184 to suppress the built-in processing. This can happen multiple
185 times, as long as the callback returns true, it will be called on
186 every further click by the user and is supposed to enlarge the
187 selection more and more, if possible.
188 See the selection example extension.
190 on_view_change $term, $offset
192 Called whenever the view offset changes, i.e. the user or program
193 scrolls. Offset 0 means display the normal terminal, positive
194 values show this many lines of scrollback.
195 on_scroll_back $term, $lines, $saved
197 Called whenever lines scroll out of the terminal area into the
198 scrollback buffer. $lines is the number of lines scrolled out and
199 may be larger than the scroll back buffer or the terminal.
200 It is called before lines are scrolled out (so rows 0 .. min
202 ($lines - 1, $nrow - 1) represent the lines to be scrolled out).
203 $saved is the total number of lines that will be in the scrollback
204 buffer.
205 on_osc_seq $term, $op, $args, $resp
207 Called on every OSC sequence and can be used to suppress it or
208 modify its behaviour. The default should be to return an empty
209 list. A true value suppresses execution of the request completely.
210 Make sure you don't get confused by recursive invocations when you
211 output an OSC sequence within this callback.
212 "on_osc_seq_perl" should be used for new behaviour.
214 on_osc_seq_perl $term, $args, $resp
216 Called whenever the ESC ] 777 ; string ST command sequence (OSC =
217 operating system command) is processed. Cursor position and other
218 state information is up-to-date when this happens. For
219 interoperability, the string should start with the extension name
220 (sans -osc) and a semicolon, to distinguish it from commands for
221 other extensions, and this might be enforced in the future.
222 For example, "overlay-osc" uses this:
224 sub on_osc_seq_perl {
226 my ($self, $osc, $resp) = @_;
227 return unless $osc =~ s/^overlay;//;
229 ... process remaining $osc string
231 }
232 Be careful not ever to trust (in a security sense) the data you
234 receive, as its source can not easily be controlled (e-mail
235 content, messages from other users on the same system etc.).
236 For responses, $resp contains the end-of-args separator used by the
238 sender.
239 on_add_lines $term, $string
241 Called whenever text is about to be output, with the text as
242 argument. You can filter/change and output the text yourself by
243 returning a true value and calling "$term->scr_add_lines" yourself.
244 Please note that this might be very slow, however, as your hook is
245 called for all text being output.
246 on_tt_write $term, $octets
248 Called whenever some data is written to the tty/pty and can be used
249 to suppress or filter tty input.
250 on_tt_paste $term, $octets
252 Called whenever text is about to be pasted, with the text as
253 argument. You can filter/change and paste the text yourself by
254 returning a true value and calling "$term->tt_paste" yourself.
255 $octets is locale-encoded.
256 on_line_update $term, $row
258 Called whenever a line was updated or changed. Can be used to
259 filter screen output (e.g. underline urls or other useless stuff).
260 Only lines that are being shown will be filtered, and, due to
261 performance reasons, not always immediately.
262 The row number is always the topmost row of the line if the line
264 spans multiple rows.
265 Please note that, if you change the line, then the hook might get
267 called later with the already-modified line (e.g. if unrelated
268 parts change), so you cannot just toggle rendition bits, but only
269 set them.
270 on_refresh_begin $term
272 Called just before the screen gets redrawn. Can be used for overlay
273 or similar effects by modifying the terminal contents in
274 refresh_begin, and restoring them in refresh_end. The built-in
275 overlay and selection display code is run after this hook, and
276 takes precedence.
277 on_refresh_end $term
279 Called just after the screen gets redrawn. See "on_refresh_begin".
280 on_action $term, $string
282 Called whenever an action is invoked for the corresponding
283 extension (e.g. via a "extension:string" builtin action bound to a
284 key, see description of the keysym resource in the urxvt(1)
285 manpage). The event is simply the action string. Note that an
286 action event is always associated to a single extension.
287 on_user_command $term, $string *DEPRECATED*
289 Called whenever a user-configured event is being activated (e.g.
290 via a "perl:string" action bound to a key, see description of the
291 keysym resource in the urxvt(1) manpage).
292 The event is simply the action string. This interface is going away
294 in preference to the "on_action" hook.
295 on_resize_all_windows $term, $new_width, $new_height
297 Called just after the new window size has been calculated, but
298 before windows are actually being resized or hints are being set.
299 If this hook returns a true value, setting of the window hints is
300 being skipped.
301 on_x_event $term, $event
303 Called on every X event received on the vt window (and possibly
304 other windows). Should only be used as a last resort. Most event
305 structure members are not passed.
306 on_root_event $term, $event
308 Like "on_x_event", but is called for events on the root window.
309 on_focus_in $term
311 Called whenever the window gets the keyboard focus, before rxvt-
312 unicode does focus in processing.
313 on_focus_out $term
315 Called whenever the window loses keyboard focus, before rxvt-
316 unicode does focus out processing.
317 on_configure_notify $term, $event
319 on_property_notify $term, $event
320 on_key_press $term, $event, $keysym, $octets
321 on_key_release $term, $event, $keysym
322 on_button_press $term, $event
323 on_button_release $term, $event
324 on_motion_notify $term, $event
325 on_map_notify $term, $event
326 on_unmap_notify $term, $event
327 Called whenever the corresponding X event is received for the
328 terminal. If the hook returns true, then the event will be ignored
329 by rxvt-unicode.
330 The event is a hash with most values as named by Xlib (see the
332 XEvent manpage), with the additional members "row" and "col", which
333 are the (real, not screen-based) row and column under the mouse
334 cursor.
335 "on_key_press" additionally receives the string rxvt-unicode would
337 output, if any, in locale-specific encoding.
338 on_client_message $term, $event
340 on_wm_protocols $term, $event
341 on_wm_delete_window $term, $event
342 Called when various types of ClientMessage events are received (all
343 with format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
344 on_bell $term
346 Called on receipt of a bell character.
347 Variables in the "urxvt" Package
349 $urxvt::LIBDIR
350 The rxvt-unicode library directory, where, among other things, the
351 perl modules and scripts are stored.
352 $urxvt::RESCLASS, $urxvt::RESCLASS
354 The resource class and name rxvt-unicode uses to look up X
355 resources.
356 $urxvt::RXVTNAME
358 The basename of the installed binaries, usually "urxvt".
359 $urxvt::TERM
361 The current terminal. This variable stores the current
362 "urxvt::term" object, whenever a callback/hook is executing.
363 @urxvt::TERM_INIT
365 All code references in this array will be called as methods of the
366 next newly created "urxvt::term" object (during the "on_init"
367 phase). The array gets cleared before the code references that were
368 in it are being executed, so references can push themselves onto it
369 again if they so desire.
370 This complements to the perl-eval command line option, but gets
372 executed first.
373 @urxvt::TERM_EXT
375 Works similar to @TERM_INIT, but contains perl package/class names,
376 which get registered as normal extensions after calling the hooks
377 in @TERM_INIT but before other extensions. Gets cleared just like
378 @TERM_INIT.
379 Functions in the "urxvt" Package
381 urxvt::fatal $errormessage
382 Fatally aborts execution with the given error message (which should
383 include a trailing newline). Avoid at all costs! The only time this
384 is acceptable (and useful) is in the init hook, where it prevents
385 the terminal from starting up.
386 urxvt::warn $string
388 Calls "rxvt_warn" with the given string which should include a
389 trailing newline. The module also overwrites the "warn" builtin
390 with a function that calls this function.
391 Using this function has the advantage that its output ends up in
393 the correct place, e.g. on stderr of the connecting urxvtc client.
394 Messages have a size limit of 1023 bytes currently.
396 @terms = urxvt::termlist
398 Returns all urxvt::term objects that exist in this process,
399 regardless of whether they are started, being destroyed etc., so be
400 careful. Only term objects that have perl extensions attached will
401 be returned (because there is no urxvt::term object associated with
402 others).
403 $time = urxvt::NOW
405 Returns the "current time" (as per the event loop).
406 urxvt::CurrentTime
408 urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask,
409 Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask,
410 Button5Mask, AnyModifier
411 urxvt::NoEventMask, KeyPressMask, KeyReleaseMask, ButtonPressMask,
412 ButtonReleaseMask, EnterWindowMask, LeaveWindowMask, PointerMotionMask,
413 PointerMotionHintMask, Button1MotionMask, Button2MotionMask,
414 Button3MotionMask, Button4MotionMask, Button5MotionMask,
415 ButtonMotionMask, KeymapStateMask, ExposureMask, VisibilityChangeMask,
416 StructureNotifyMask, ResizeRedirectMask, SubstructureNotifyMask,
417 SubstructureRedirectMask, FocusChangeMask, PropertyChangeMask,
418 ColormapChangeMask, OwnerGrabButtonMask
419 urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify,
420 EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose,
421 GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify,
422 DestroyNotify, UnmapNotify, MapNotify, MapRequest, ReparentNotify,
423 ConfigureNotify, ConfigureRequest, GravityNotify, ResizeRequest,
424 CirculateNotify, CirculateRequest, PropertyNotify, SelectionClear,
425 SelectionRequest, SelectionNotify, ColormapNotify, ClientMessage,
426 MappingNotify
427 Various constants for use in X calls and event processing.
428 urxvt::PrivMode_132, PrivMode_132OK, PrivMode_rVideo,
430 PrivMode_relOrigin, PrivMode_Screen, PrivMode_Autowrap,
431 PrivMode_aplCUR, PrivMode_aplKP, PrivMode_HaveBackSpace,
432 PrivMode_BackSpace, PrivMode_ShiftKeys, PrivMode_VisibleCursor,
433 PrivMode_MouseX10, PrivMode_MouseX11, PrivMode_scrollBar,
434 PrivMode_TtyOutputInh, PrivMode_Keypress, PrivMode_smoothScroll,
435 PrivMode_vt52, PrivMode_LFNL, PrivMode_MouseBtnEvent,
436 PrivMode_MouseAnyEvent, PrivMode_BracketPaste, PrivMode_ExtMouseUTF8,
437 PrivMode_ExtMouseUrxvt, PrivMode_BlinkingCursor, PrivMode_mouse_report,
438 PrivMode_Default
439 Constants for checking DEC private modes.
440 RENDITION
442 Rendition bitsets contain information about colour, font, font styles
443 and similar information for each screen cell.
444 The following "macros" deal with changes in rendition sets. You should
446 never just create a bitset, you should always modify an existing one,
447 as they contain important information required for correct operation of
448 rxvt-unicode.
449 $rend = urxvt::DEFAULT_RSTYLE
451 Returns the default rendition, as used when the terminal is
452 starting up or being reset. Useful as a base to start when creating
453 renditions.
454 $rend = urxvt::OVERLAY_RSTYLE
456 Return the rendition mask used for overlays by default.
457 $rendbit = urxvt::RS_Bold, urxvt::RS_Italic, urxvt::RS_Blink,
459 urxvt::RS_RVid, urxvt::RS_Uline
460 Return the bit that enabled bold, italic, blink, reverse-video and
461 underline, respectively. To enable such a style, just logically OR
462 it into the bitset.
463 $foreground = urxvt::GET_BASEFG $rend
465 $background = urxvt::GET_BASEBG $rend
466 Return the foreground/background colour index, respectively.
467 $rend = urxvt::SET_FGCOLOR $rend, $new_colour
469 $rend = urxvt::SET_BGCOLOR $rend, $new_colour
470 $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
471 Replace the foreground/background colour in the rendition mask with
472 the specified one.
473 $value = urxvt::GET_CUSTOM $rend
475 Return the "custom" value: Every rendition has 5 bits for use by
476 extensions. They can be set and changed as you like and are
477 initially zero.
478 $rend = urxvt::SET_CUSTOM $rend, $new_value
480 Change the custom value.
481 The "urxvt::term::extension" class
483 Each extension attached to a terminal object is represented by a
484 "urxvt::term::extension" object.
485 You can use these objects, which are passed to all callbacks to store
487 any state related to the terminal and extension instance.
488 The methods (And data members) documented below can be called on
490 extension objects, in addition to call methods documented for the
491 <urxvt::term> class.
492 $urxvt_term = $self->{term}
494 Returns the "urxvt::term" object associated with this instance of
495 the extension. This member must not be changed in any way.
496 $self->enable ($hook_name => $cb[, $hook_name => $cb..])
498 Dynamically enable the given hooks (named without the "on_" prefix)
499 for this extension, replacing any hook previously installed via
500 "enable" in this extension.
501 This is useful when you want to overwrite time-critical hooks only
503 temporarily.
504 To install additional callbacks for the same hook, you can use the
506 "on" method of the "urxvt::term" class.
507 $self->disable ($hook_name[, $hook_name..])
509 Dynamically disable the given hooks.
510 $guard = $self->on ($hook_name => $cb[, $hook_name => $cb..])
512 Similar to the "enable" enable, but installs additional callbacks
513 for the given hook(s) (that is, it doesn't replace existing
514 callbacks), and returns a guard object. When the guard object is
515 destroyed the callbacks are disabled again.
516 $self->bind_action ($hotkey, $action)
518 $self->x_resource ($pattern)
519 $self->x_resource_boolean ($pattern)
520 These methods support an additional "%" prefix for $action or
521 $pattern when called on an extension object, compared to the
522 "urxvt::term" methods of the same name - see the description of
523 these methods in the "urxvt::term" class for details.
524 The "urxvt::anyevent" Class
526 The sole purpose of this class is to deliver an interface to the
527 "AnyEvent" module - any module using it will work inside urxvt without
528 further programming. The only exception is that you cannot wait on
529 condition variables, but non-blocking condvar use is ok.
530 In practical terms this means is that you cannot use blocking APIs, but
532 the non-blocking variant should work.
533 The "urxvt::term" Class
535 $term = new urxvt::term $envhashref, $rxvtname, [arg...]
536 Creates a new terminal, very similar as if you had started it with
537 system "$rxvtname, arg...". $envhashref must be a reference to a
538 %ENV-like hash which defines the environment of the new terminal.
539 Croaks (and probably outputs an error message) if the new instance
541 couldn't be created. Returns "undef" if the new instance didn't
542 initialise perl, and the terminal object otherwise. The "init" and
543 "start" hooks will be called before this call returns, and are free
544 to refer to global data (which is race free).
545 $term->destroy
547 Destroy the terminal object (close the window, free resources
548 etc.). Please note that urxvt will not exit as long as any event
549 watchers (timers, io watchers) are still active.
550 $term->exec_async ($cmd[, @args])
552 Works like the combination of the "fork"/"exec" builtins, which
553 executes ("starts") programs in the background. This function takes
554 care of setting the user environment before exec'ing the command
555 (e.g. "PATH") and should be preferred over explicit calls to "exec"
556 or "system".
557 Returns the pid of the subprocess or "undef" on error.
559 $isset = $term->option ($optval[, $set])
561 Returns true if the option specified by $optval is enabled, and
562 optionally change it. All option values are stored by name in the
563 hash %urxvt::OPTION. Options not enabled in this binary are not in
564 the hash.
565 Here is a likely non-exhaustive list of option names, please see
567 the source file /src/optinc.h to see the actual list:
568 borderLess buffered console cursorBlink cursorUnderline hold iconic
570 insecure intensityStyles iso14755 iso14755_52 jumpScroll loginShell
571 mapAlert meta8 mouseWheelScrollPage override_redirect pastableTabs
572 pointerBlank reverseVideo scrollBar scrollBar_floating scrollBar_right
573 scrollTtyKeypress scrollTtyOutput scrollWithBuffer secondaryScreen
574 secondaryScroll skipBuiltinGlyphs skipScroll transparent tripleclickwords
575 urgentOnBell utmpInhibit visualBell
576 $value = $term->resource ($name[, $newval])
578 Returns the current resource value associated with a given name and
579 optionally sets a new value. Setting values is most useful in the
580 "init" hook. Unset resources are returned and accepted as "undef".
581 The new value must be properly encoded to a suitable character
583 encoding before passing it to this method. Similarly, the returned
584 value may need to be converted from the used encoding to text.
585 Resource names are as defined in src/rsinc.h. Colours can be
587 specified as resource names of the form "color+<index>", e.g.
588 "color+5". (will likely change).
589 Please note that resource strings will currently only be freed when
591 the terminal is destroyed, so changing options frequently will eat
592 memory.
593 Here is a likely non-exhaustive list of resource names, not all of
595 which are supported in every build, please see the source file
596 /src/rsinc.h to see the actual list:
597 answerbackstring backgroundPixmap backspace_key blurradius
599 boldFont boldItalicFont borderLess buffered chdir color cursorBlink
600 cursorUnderline cutchars delete_key depth display_name embed ext_bwidth
601 fade font geometry hold iconName iconfile imFont imLocale inputMethod
602 insecure int_bwidth intensityStyles iso14755 iso14755_52 italicFont
603 jumpScroll letterSpace lineSpace loginShell mapAlert meta8 modifier
604 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
605 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
606 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
607 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
608 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
609 secondaryScreen secondaryScroll shade skipBuiltinGlyphs skipScroll
610 term_name title transient_for transparent tripleclickwords urgentOnBell
611 utmpInhibit visualBell
612 $value = $term->x_resource ($pattern)
614 Returns the X-Resource for the given pattern, excluding the program
615 or class name, i.e. "$term->x_resource ("boldFont")" should return
616 the same value as used by this instance of rxvt-unicode. Returns
617 "undef" if no resource with that pattern exists.
618 Extensions that define extra resources also need to call this
620 method to access their values.
621 If the method is called on an extension object (basically, from an
623 extension), then the special prefix "%." will be replaced by the
624 name of the extension and a dot, and the lone string "%" will be
625 replaced by the extension name itself. This makes it possible to
626 code extensions so you can rename them and get a new set of
627 resources without having to change the actual code.
628 This method should only be called during the "on_start" hook, as
630 there is only one resource database per display, and later
631 invocations might return the wrong resources.
632 $value = $term->x_resource_boolean ($pattern)
634 Like "x_resource", above, but interprets the string value as a
635 boolean and returns 1 for true values, 0 for false values and
636 "undef" if the resource or option isn't specified.
637 You should always use this method to parse boolean resources.
639 $action = $term->lookup_keysym ($keysym, $state)
641 Returns the action bound to key combination "($keysym, $state)", if
642 a binding for it exists, and "undef" otherwise.
643 $success = $term->bind_action ($key, $action)
645 Adds a key binding exactly as specified via a "keysym" resource.
646 See the "keysym" resource in the urxvt(1) manpage.
647 To add default bindings for actions, an extension should call
649 "->bind_action" in its "init" hook for every such binding. Doing it
650 in the "init" hook allows users to override or remove the binding
651 again.
652 Example: the "searchable-scrollback" by default binds itself on
654 "Meta-s", using "$self->bind_action", which calls
655 "$term->bind_action".
656 sub init {
658 my ($self) = @_;
659 $self->bind_action ("M-s" => "%:start");
661 }
662 $rend = $term->rstyle ([$new_rstyle])
664 Return and optionally change the current rendition. Text that is
665 output by the terminal application will use this style.
666 ($row, $col) = $term->screen_cur ([$row, $col])
668 Return the current coordinates of the text cursor position and
669 optionally set it (which is usually bad as applications don't
670 expect that).
671 ($row, $col) = $term->selection_mark ([$row, $col])
673 ($row, $col) = $term->selection_beg ([$row, $col])
674 ($row, $col) = $term->selection_end ([$row, $col])
675 Return the current values of the selection mark, begin or end
676 positions.
677 When arguments are given, then the selection coordinates are set to
679 $row and $col, and the selection screen is set to the current
680 screen.
681 $screen = $term->selection_screen ([$screen])
683 Returns the current selection screen, and then optionally sets it.
684 $term->selection_make ($eventtime[, $rectangular])
686 Tries to make a selection as set by "selection_beg" and
687 "selection_end". If $rectangular is true (default: false), a
688 rectangular selection will be made. This is the preferred function
689 to make a selection.
690 $success = $term->selection_grab ($eventtime[, $clipboard])
692 Try to acquire ownership of the primary (clipboard if $clipboard is
693 true) selection from the server. The corresponding text can be set
694 with the next method. No visual feedback will be given. This
695 function is mostly useful from within "on_sel_grab" hooks.
696 $oldtext = $term->selection ([$newtext, $clipboard])
698 Return the current selection (clipboard if $clipboard is true) text
699 and optionally replace it by $newtext.
700 $term->selection_clear ([$clipboard])
702 Revoke ownership of the primary (clipboard if $clipboard is true)
703 selection.
704 $term->overlay_simple ($x, $y, $text)
706 Create a simple multi-line overlay box. See the next method for
707 details.
708 $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
710 Create a new (empty) overlay at the given position with the given
711 width/height. $rstyle defines the initial rendition style (default:
712 "OVERLAY_RSTYLE").
713 If $border is 2 (default), then a decorative border will be put
715 around the box.
716 If either $x or $y is negative, then this is counted from the
718 right/bottom side, respectively.
719 This method returns an urxvt::overlay object. The overlay will be
721 visible as long as the perl object is referenced.
722 The methods currently supported on "urxvt::overlay" objects are:
724 $overlay->set ($x, $y, $text[, $rend])
726 Similar to "$term->ROW_t" and "$term->ROW_r" in that it puts
727 text in rxvt-unicode's special encoding and an array of
728 rendition values at a specific position inside the overlay.
729 If $rend is missing, then the rendition will not be changed.
731 $overlay->hide
733 If visible, hide the overlay, but do not destroy it.
734 $overlay->show
736 If hidden, display the overlay again.
737 $popup = $term->popup ($event)
739 Creates a new "urxvt::popup" object that implements a popup menu.
740 The $event must be the event causing the menu to pop up (a button
741 event, currently).
742 $cellwidth = $term->strwidth ($string)
744 Returns the number of screen-cells this string would need.
745 Correctly accounts for wide and combining characters.
746 $octets = $term->locale_encode ($string)
748 Convert the given text string into the corresponding locale
749 encoding.
750 $string = $term->locale_decode ($octets)
752 Convert the given locale-encoded octets into a perl string.
753 $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
755 XORs the rendition values in the given span with the provided value
756 (default: "RS_RVid"), which MUST NOT contain font styles. Useful in
757 refresh hooks to provide effects similar to the selection.
758 $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[,
760 $rstyle1[, $rstyle2]])
761 Similar to "scr_xor_span", but xors a rectangle instead. Trailing
762 whitespace will additionally be xored with the $rstyle2, which
763 defaults to "RS_RVid | RS_Uline", which removes reverse video again
764 and underlines it instead. Both styles MUST NOT contain font
765 styles.
766 $term->scr_bell
768 Ring the bell!
769 $term->scr_add_lines ($string)
771 Write the given text string to the screen, as if output by the
772 application running inside the terminal. It may not contain command
773 sequences (escape codes - see "cmd_parse" for that), but is free to
774 use line feeds, carriage returns and tabs. The string is a normal
775 text string, not in locale-dependent encoding.
776 Normally its not a good idea to use this function, as programs
778 might be confused by changes in cursor position or scrolling. Its
779 useful inside a "on_add_lines" hook, though.
780 $term->scr_change_screen ($screen)
782 Switch to given screen - 0 primary, 1 secondary.
783 $term->cmd_parse ($octets)
785 Similar to "scr_add_lines", but the argument must be in the locale-
786 specific encoding of the terminal and can contain command sequences
787 (escape codes) that will be interpreted.
788 $term->tt_write ($octets)
790 Write the octets given in $octets to the tty (i.e. as user input to
791 the program, see "cmd_parse" for the opposite direction). To pass
792 characters instead of octets, you should convert your strings first
793 to the locale-specific encoding using "$term->locale_encode".
794 $term->tt_write_user_input ($octets)
796 Like "tt_write", but should be used when writing strings in
797 response to the user pressing a key, to invoke the additional
798 actions requested by the user for that case ("tt_write" doesn't do
799 that).
800 The typical use case would be inside "on_action" hooks.
802 $term->tt_paste ($octets)
804 Write the octets given in $octets to the tty as a paste, converting
805 NL to CR and bracketing the data with control sequences if
806 bracketed paste mode is set.
807 $old_events = $term->pty_ev_events ([$new_events])
809 Replaces the event mask of the pty watcher by the given event mask.
810 Can be used to suppress input and output handling to the pty/tty.
811 See the description of "urxvt::timer->events". Make sure to always
812 restore the previous value.
813 $fd = $term->pty_fd
815 Returns the master file descriptor for the pty in use, or "-1" if
816 no pty is used.
817 $windowid = $term->parent
819 Return the window id of the toplevel window.
820 $windowid = $term->vt
822 Return the window id of the terminal window.
823 $term->vt_emask_add ($x_event_mask)
825 Adds the specified events to the vt event mask. Useful e.g. when
826 you want to receive pointer events all the times:
827 $term->vt_emask_add (urxvt::PointerMotionMask);
829 $term->set_urgency ($set)
831 Enable/disable the urgency hint on the toplevel window.
832 $term->focus_in
834 $term->focus_out
835 $term->key_press ($state, $keycode[, $time])
836 $term->key_release ($state, $keycode[, $time])
837 Deliver various fake events to to terminal.
838 $window_width = $term->width ([$new_value])
840 $window_height = $term->height ([$new_value])
841 $font_width = $term->fwidth ([$new_value])
842 $font_height = $term->fheight ([$new_value])
843 $font_ascent = $term->fbase ([$new_value])
844 $terminal_rows = $term->nrow ([$new_value])
845 $terminal_columns = $term->ncol ([$new_value])
846 $has_focus = $term->focus ([$new_value])
847 $is_mapped = $term->mapped ([$new_value])
848 $max_scrollback = $term->saveLines ([$new_value])
849 $nrow_plus_saveLines = $term->total_rows ([$new_value])
850 $topmost_scrollback_row = $term->top_row ([$new_value])
851 Return various integers describing terminal characteristics. If an
852 argument is given, changes the value and returns the previous one.
853 $x_display = $term->display_id
855 Return the DISPLAY used by rxvt-unicode.
856 $lc_ctype = $term->locale
858 Returns the LC_CTYPE category string used by this rxvt-unicode.
859 $env = $term->env
861 Returns a copy of the environment in effect for the terminal as a
862 hashref similar to "\%ENV".
863 @envv = $term->envv
865 Returns the environment as array of strings of the form
866 "VAR=VALUE".
867 @argv = $term->argv
869 Return the argument vector as this terminal, similar to @ARGV, but
870 includes the program name as first element.
871 $modifiermask = $term->ModLevel3Mask
873 $modifiermask = $term->ModMetaMask
874 $modifiermask = $term->ModNumLockMask
875 Return the modifier masks corresponding to the "ISO Level 3 Shift"
876 (often AltGr), the meta key (often Alt) and the num lock key, if
877 applicable.
878 $screen = $term->current_screen
880 Returns the currently displayed screen (0 primary, 1 secondary).
881 $cursor_is_hidden = $term->hidden_cursor
883 Returns whether the cursor is currently hidden or not.
884 $priv_modes = $term->priv_modes
886 Returns a bitset with the state of DEC private modes.
887 Example:
889 if ($term->priv_modes & urxvt::PrivMode_mouse_report) {
891 # mouse reporting is turned on
892 }
893 $view_start = $term->view_start ([$newvalue])
895 Returns the row number of the topmost displayed line. Maximum value
896 is 0, which displays the normal terminal contents. Lower values
897 scroll this many lines into the scrollback buffer.
898 $term->want_refresh
900 Requests a screen refresh. At the next opportunity, rxvt-unicode
901 will compare the on-screen display with its stored representation.
902 If they differ, it redraws the differences.
903 Used after changing terminal contents to display them.
905 $term->refresh_check
907 Checks if a refresh has been requested and, if so, schedules one.
908 $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
910 Returns the text of the entire row with number $row_number. Row
911 "$term->top_row" is the topmost terminal line, row "$term->nrow-1"
912 is the bottommost terminal line. Nothing will be returned if a
913 nonexistent line is requested.
914 If $new_text is specified, it will replace characters in the
916 current line, starting at column $start_col (default 0), which is
917 useful to replace only parts of a line. The font index in the
918 rendition will automatically be updated.
919 $text is in a special encoding: tabs and wide characters that use
921 more than one cell when displayed are padded with $urxvt::NOCHAR
922 (chr 65535) characters. Characters with combining characters and
923 other characters that do not fit into the normal text encoding will
924 be replaced with characters in the private use area.
925 You have to obey this encoding when changing text. The advantage is
927 that "substr" and similar functions work on screen cells and not on
928 characters.
929 The methods "$term->special_encode" and "$term->special_decode" can
931 be used to convert normal strings into this encoding and vice
932 versa.
933 $rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])
935 Like "$term->ROW_t", but returns an arrayref with rendition
936 bitsets. Rendition bitsets contain information about colour, font,
937 font styles and similar information. See also "$term->ROW_t".
938 When setting rendition, the font mask will be ignored.
940 See the section on RENDITION, above.
942 $length = $term->ROW_l ($row_number[, $new_length])
944 Returns the number of screen cells that are in use ("the line
945 length"). Unlike the urxvt core, this returns "$term->ncol" if the
946 line is joined with the following one.
947 $bool = $term->is_longer ($row_number)
949 Returns true if the row is part of a multiple-row logical "line"
950 (i.e. joined with the following row), which means all characters
951 are in use and it is continued on the next row (and possibly a
952 continuation of the previous row(s)).
953 $line = $term->line ($row_number)
955 Create and return a new "urxvt::line" object that stores
956 information about the logical line that row $row_number is part of.
957 It supports the following methods:
958 $text = $line->t ([$new_text])
960 Returns or replaces the full text of the line, similar to
961 "ROW_t"
962 $rend = $line->r ([$new_rend])
964 Returns or replaces the full rendition array of the line,
965 similar to "ROW_r"
966 $length = $line->l
968 Returns the length of the line in cells, similar to "ROW_l".
969 $rownum = $line->beg
971 $rownum = $line->end
972 Return the row number of the first/last row of the line,
973 respectively.
974 $offset = $line->offset_of ($row, $col)
976 Returns the character offset of the given row|col pair within
977 the logical line. Works for rows outside the line, too, and
978 returns corresponding offsets outside the string.
979 ($row, $col) = $line->coord_of ($offset)
981 Translates a string offset into terminal coordinates again.
982 $text = $term->special_encode $string
984 Converts a perl string into the special encoding used by rxvt-
985 unicode, where one character corresponds to one screen cell. See
986 "$term->ROW_t" for details.
987 $string = $term->special_decode $text
989 Converts rxvt-unicodes text representation into a perl string. See
990 "$term->ROW_t" for details.
991 $success = $term->grab_button ($button, $modifiermask[, $window =
993 $term->vt])
994 $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
995 Register/unregister a synchronous button grab. See the XGrabButton
996 manpage.
997 $success = $term->grab ($eventtime[, $sync])
999 Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1000 synchronous ($sync is true). Also remembers the grab timestamp.
1001 $term->allow_events_async
1003 Calls XAllowEvents with AsyncBoth for the most recent grab.
1004 $term->allow_events_sync
1006 Calls XAllowEvents with SyncBoth for the most recent grab.
1007 $term->allow_events_replay
1009 Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for
1010 the most recent grab.
1011 $term->ungrab
1013 Calls XUngrabPointer and XUngrabKeyboard for the most recent grab.
1014 Is called automatically on evaluation errors, as it is better to
1015 lose the grab in the error case as the session.
1016 $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
1018 $atom_name = $term->XGetAtomName ($atom)
1019 @atoms = $term->XListProperties ($window)
1020 ($type,$format,$octets) = $term->XGetWindowProperty ($window,
1021 $property)
1022 $term->XChangeProperty ($window, $property, $type, $format, $octets)
1023 $term->XDeleteProperty ($window, $property)
1024 $window = $term->DefaultRootWindow
1025 $term->XReparentWindow ($window, $parent, [$x, $y])
1026 $term->XMapWindow ($window)
1027 $term->XUnmapWindow ($window)
1028 $term->XMoveResizeWindow ($window, $x, $y, $width, $height)
1029 ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x,
1030 $y)
1031 $term->XChangeInput ($window, $add_events[, $del_events])
1032 $keysym = $term->XStringToKeysym ($string)
1033 $string = $term->XKeysymToString ($keysym)
1034 Various X or X-related functions. The $term object only serves as
1035 the source of the display, otherwise those functions map more-or-
1036 less directly onto the X functions of the same name.
1037 The "urxvt::popup" Class
1039 $popup->add_title ($title)
1040 Adds a non-clickable title to the popup.
1041 $popup->add_separator ([$sepchr])
1043 Creates a separator, optionally using the character given as
1044 $sepchr.
1045 $popup->add_button ($text, $cb)
1047 Adds a clickable button to the popup. $cb is called whenever it is
1048 selected.
1049 $popup->add_toggle ($text, $initial_value, $cb)
1051 Adds a toggle/checkbox item to the popup. The callback gets called
1052 whenever it gets toggled, with a boolean indicating its new value
1053 as its first argument.
1054 $popup->show
1056 Displays the popup (which is initially hidden).
1057 The "urxvt::timer" Class
1059 This class implements timer watchers/events. Time is represented as a
1060 fractional number of seconds since the epoch. Example:
1061 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
1063 $term->{timer} = urxvt::timer
1064 ->new
1065 ->interval (1)
1066 ->cb (sub {
1067 $term->{overlay}->set (0, 0,
1068 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
1069 });
1070 $timer = new urxvt::timer
1072 Create a new timer object in started state. It is scheduled to fire
1073 immediately.
1074 $timer = $timer->cb (sub { my ($timer) = @_; ... })
1076 Set the callback to be called when the timer triggers.
1077 $timer = $timer->set ($tstamp[, $interval])
1079 Set the time the event is generated to $tstamp (and optionally
1080 specifies a new $interval).
1081 $timer = $timer->interval ($interval)
1083 By default (and when $interval is 0), the timer will automatically
1084 stop after it has fired once. If $interval is non-zero, then the
1085 timer is automatically rescheduled at the given intervals.
1086 $timer = $timer->start
1088 Start the timer.
1089 $timer = $timer->start ($tstamp[, $interval])
1091 Set the event trigger time to $tstamp and start the timer.
1092 Optionally also replaces the interval.
1093 $timer = $timer->after ($delay[, $interval])
1095 Like "start", but sets the expiry timer to c<urxvt::NOW + $delay>.
1096 $timer = $timer->stop
1098 Stop the timer.
1099 The "urxvt::iow" Class
1101 This class implements io watchers/events. Example:
1102 $term->{socket} = ...
1104 $term->{iow} = urxvt::iow
1105 ->new
1106 ->fd (fileno $term->{socket})
1107 ->events (urxvt::EV_READ)
1108 ->start
1109 ->cb (sub {
1110 my ($iow, $revents) = @_;
1111 # $revents must be 1 here, no need to check
1112 sysread $term->{socket}, my $buf, 8192
1113 or end-of-file;
1114 });
1115 $iow = new urxvt::iow
1117 Create a new io watcher object in stopped state.
1118 $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
1120 Set the callback to be called when io events are triggered.
1121 $reventmask is a bitset as described in the "events" method.
1122 $iow = $iow->fd ($fd)
1124 Set the file descriptor (not handle) to watch.
1125 $iow = $iow->events ($eventmask)
1127 Set the event mask to watch. The only allowed values are
1128 "urxvt::EV_READ" and "urxvt::EV_WRITE", which might be ORed
1129 together, or "urxvt::EV_NONE".
1130 $iow = $iow->start
1132 Start watching for requested events on the given handle.
1133 $iow = $iow->stop
1135 Stop watching for events on the given file handle.
1136 The "urxvt::iw" Class
1138 This class implements idle watchers, that get called automatically when
1139 the process is idle. They should return as fast as possible, after
1140 doing some useful work.
1141 $iw = new urxvt::iw
1143 Create a new idle watcher object in stopped state.
1144 $iw = $iw->cb (sub { my ($iw) = @_; ... })
1146 Set the callback to be called when the watcher triggers.
1147 $timer = $timer->start
1149 Start the watcher.
1150 $timer = $timer->stop
1152 Stop the watcher.
1153 The "urxvt::pw" Class
1155 This class implements process watchers. They create an event whenever a
1156 process exits, after which they stop automatically.
1157 my $pid = fork;
1159 ...
1160 $term->{pw} = urxvt::pw
1161 ->new
1162 ->start ($pid)
1163 ->cb (sub {
1164 my ($pw, $exit_status) = @_;
1165 ...
1166 });
1167 $pw = new urxvt::pw
1169 Create a new process watcher in stopped state.
1170 $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
1172 Set the callback to be called when the timer triggers.
1173 $pw = $timer->start ($pid)
1175 Tells the watcher to start watching for process $pid.
1176 $pw = $pw->stop
1178 Stop the watcher.
1179
1181 URXVT_PERL_VERBOSITY
1182 This variable controls the verbosity level of the perl extension.
1183 Higher numbers indicate more verbose output.
1184 == 0 - fatal messages
1186 >= 3 - script loading and management
1187 >=10 - all called hooks
1188 >=11 - hook return values
1189
1191 Marc Lehmann <schmorp@schmorp.de>
1192 http://software.schmorp.de/pkg/rxvt-unicode
11939.26 2021-07-23 urxvtperl(3)