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