1urxvtperl(3)                     RXVT-UNICODE                     urxvtperl(3)
2
3
4

NAME

6       urxvtperl - rxvt-unicode's embedded perl interpreter
7

SYNOPSIS

9          # create a file grab_test in $HOME:
10
11          sub on_sel_grab {
12             warn "you selected ", $_[0]->selection;
13             ()
14          }
15
16          # start a urxvt using it:
17
18          urxvt --perl-lib $HOME -pe grab_test
19

DESCRIPTION

21       Every time a terminal object gets created, extension scripts specified
22       via the "perl" resource are loaded and associated with it.
23
24       Scripts are compiled in a 'use strict "vars"' and 'use utf8'
25       environment, and thus must be encoded as UTF-8.
26
27       Each script will only ever be loaded once, even in urxvtd, where
28       scripts will be shared (but not enabled) for all terminals.
29
30       You can disable the embedded perl interpreter by setting both "perl-
31       ext" and "perl-ext-common" resources to the empty string.
32

PREPACKAGED EXTENSIONS

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
38       You can activate them like this:
39
40         urxvt -pe <extensionname>
41
42       Or by adding them to the resource for extensions loaded by default:
43
44         URxvt.perl-ext-common: default,selection-autotransform
45
46       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

API DOCUMENTATION

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
63       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
68       Argument names also often indicate the type of a parameter. Here are
69       some hints on what they mean:
70
71       $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
76       $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
81       $octets
82           Either binary data or - more common - a text string encoded in a
83           locale-specific way.
84
85       $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
90   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
99       Although it isn't a "urxvt::term" object, you can call all methods of
100       the "urxvt::term" class on this object.
101
102       Additional methods only supported for extension objects are described
103       in the "urxvt::extension" section below.
104
105   META comments
106       Rxvt-unicode recognizes special meta comments in extensions that define
107       different types of metadata.
108
109       Currently, it recognises only one such comment:
110
111       #: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
116   Hooks
117       The following subroutines can be declared in extension files, and will
118       be called whenever the relevant event happens.
119
120       The first argument passed to them is an extension object as described
121       in the in the "Extension Objects" section.
122
123       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
127       When in doubt, return a false value (preferably "()").
128
129       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
137       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
142       on_destroy $term
143           Called whenever something tries to destroy terminal, when the
144           terminal is still fully functional (not for long, though).
145
146       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
151       on_child_start $term, $pid
152           Called just after the child process has been "fork"ed.
153
154       on_child_exit $term, $status
155           Called just after the child process has exited. $status is the
156           status from "waitpid".
157
158       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
163           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
167       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
172           Returning a true value aborts selection grabbing. It will still be
173           highlighted.
174
175       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
184           See the selection example extension.
185
186       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
191       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
196           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
201       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
208           "on_osc_seq_perl" should be used for new behaviour.
209
210       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
218           For example, "overlay-osc" uses this:
219
220              sub on_osc_seq_perl {
221                 my ($self, $osc, $resp) = @_;
222
223                 return unless $osc =~ s/^overlay;//;
224
225                 ... process remaining $osc string
226              }
227
228           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
232           For responses, $resp contains the end-of-args separator used by the
233           sender.
234
235       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
242       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
246       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
252       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
258           The row number is always the topmost row of the line if the line
259           spans multiple rows.
260
261           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
266       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
273       on_refresh_end $term
274           Called just after the screen gets redrawn. See "on_refresh_begin".
275
276       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
283       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
288           The event is simply the action string. This interface is going away
289           in preference to the "on_action" hook.
290
291       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
297       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
302       on_root_event $term, $event
303           Like "on_x_event", but is called for events on the root window.
304
305       on_focus_in $term
306           Called whenever the window gets the keyboard focus, before rxvt-
307           unicode does focus in processing.
308
309       on_focus_out $term
310           Called whenever the window loses keyboard focus, before rxvt-
311           unicode does focus out processing.
312
313       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
326           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
331           "on_key_press" additionally receives the string rxvt-unicode would
332           output, if any, in locale-specific encoding.
333
334       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
340       on_bell $term
341           Called on receipt of a bell character.
342
343   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
348       $urxvt::RESCLASS, $urxvt::RESCLASS
349           The resource class and name rxvt-unicode uses to look up X
350           resources.
351
352       $urxvt::RXVTNAME
353           The basename of the installed binaries, usually "urxvt".
354
355       $urxvt::TERM
356           The current terminal. This variable stores the current
357           "urxvt::term" object, whenever a callback/hook is executing.
358
359       @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
366           This complements to the perl-eval command line option, but gets
367           executed first.
368
369       @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
375   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
382       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
387           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
390           Messages have a size limit of 1023 bytes currently.
391
392       @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
399       $time = urxvt::NOW
400           Returns the "current time" (as per the event loop).
401
402       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
424   RENDITION
425       Rendition bitsets contain information about colour, font, font styles
426       and similar information for each screen cell.
427
428       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
433       $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
438       $rend = urxvt::OVERLAY_RSTYLE
439           Return the rendition mask used for overlays by default.
440
441       $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
447       $foreground = urxvt::GET_BASEFG $rend
448       $background = urxvt::GET_BASEBG $rend
449           Return the foreground/background colour index, respectively.
450
451       $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
457       $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
462       $rend = urxvt::SET_CUSTOM $rend, $new_value
463           Change the custom value.
464
465   The "urxvt::term::extension" class
466       Each extension attached to a terminal object is represented by a
467       "urxvt::term::extension" object.
468
469       You can use these objects, which are passed to all callbacks to store
470       any state related to the terminal and extension instance.
471
472       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
476       $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
480       $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
485           This is useful when you want to overwrite time-critical hooks only
486           temporarily.
487
488           To install additional callbacks for the same hook, you can use the
489           "on" method of the "urxvt::term" class.
490
491       $self->disable ($hook_name[, $hook_name..])
492           Dynamically disable the given hooks.
493
494       $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
500       $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
508   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
514       In practical terms this means is that you cannot use blocking APIs, but
515       the non-blocking variant should work.
516
517   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
523           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
529       $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
534       $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
541           Returns the pid of the subprocess or "undef" on error.
542
543       $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
549           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
552            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
560       $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
565           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
569           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
573           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
577           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
581             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
596       $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
602           Extensions that define extra resources also need to call this
603           method to access their values.
604
605           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
612           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
616       $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
621           You should always use this method to parse boolean resources.
622
623       $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
627       $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
631           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
636           Example: the "searchable-scrollback" by default binds itself on
637           "Meta-s", using "$self->bind_action", which calls
638           "$term->bind_action".
639
640              sub init {
641                 my ($self) = @_;
642
643                 $self->bind_action ("M-s" => "%:start");
644              }
645
646       $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
650       ($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
655       ($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
661           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
665       $screen = $term->selection_screen ([$screen])
666           Returns the current selection screen, and then optionally sets it.
667
668       $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
674       $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
680       $oldtext = $term->selection ([$newtext, $clipboard])
681           Return the current selection (clipboard if $clipboard is true) text
682           and optionally replace it by $newtext.
683
684       $term->selection_clear ([$clipboard])
685           Revoke ownership of the primary (clipboard if $clipboard is true)
686           selection.
687
688       $term->overlay_simple ($x, $y, $text)
689           Create a simple multi-line overlay box. See the next method for
690           details.
691
692       $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
697           If $border is 2 (default), then a decorative border will be put
698           around the box.
699
700           If either $x or $y is negative, then this is counted from the
701           right/bottom side, respectively.
702
703           This method returns an urxvt::overlay object. The overlay will be
704           visible as long as the perl object is referenced.
705
706           The methods currently supported on "urxvt::overlay" objects are:
707
708           $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
713               If $rend is missing, then the rendition will not be changed.
714
715           $overlay->hide
716               If visible, hide the overlay, but do not destroy it.
717
718           $overlay->show
719               If hidden, display the overlay again.
720
721       $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
726       $cellwidth = $term->strwidth ($string)
727           Returns the number of screen-cells this string would need.
728           Correctly accounts for wide and combining characters.
729
730       $octets = $term->locale_encode ($string)
731           Convert the given text string into the corresponding locale
732           encoding.
733
734       $string = $term->locale_decode ($octets)
735           Convert the given locale-encoded octets into a perl string.
736
737       $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
742       $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
750       $term->scr_bell
751           Ring the bell!
752
753       $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
760           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
764       $term->scr_change_screen ($screen)
765           Switch to given screen - 0 primary, 1 secondary.
766
767       $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
772       $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
778       $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
784           The typical use case would be inside "on_action" hooks.
785
786       $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
791       $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
797       $fd = $term->pty_fd
798           Returns the master file descriptor for the pty in use, or "-1" if
799           no pty is used.
800
801       $windowid = $term->parent
802           Return the window id of the toplevel window.
803
804       $windowid = $term->vt
805           Return the window id of the terminal window.
806
807       $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
811              $term->vt_emask_add (urxvt::PointerMotionMask);
812
813       $term->set_urgency ($set)
814           Enable/disable the urgency hint on the toplevel window.
815
816       $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
822       $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
837       $x_display = $term->display_id
838           Return the DISPLAY used by rxvt-unicode.
839
840       $lc_ctype = $term->locale
841           Returns the LC_CTYPE category string used by this rxvt-unicode.
842
843       $env = $term->env
844           Returns a copy of the environment in effect for the terminal as a
845           hashref similar to "\%ENV".
846
847       @envv = $term->envv
848           Returns the environment as array of strings of the form
849           "VAR=VALUE".
850
851       @argv = $term->argv
852           Return the argument vector as this terminal, similar to @ARGV, but
853           includes the program name as first element.
854
855       $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
862       $screen = $term->current_screen
863           Returns the currently displayed screen (0 primary, 1 secondary).
864
865       $cursor_is_hidden = $term->hidden_cursor
866           Returns whether the cursor is currently hidden or not.
867
868       $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
873       $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
878           Used after changing terminal contents to display them.
879
880       $term->refresh_check
881           Checks if a refresh has been requested and, if so, schedules one.
882
883       $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
889           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
894           $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
900           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
904           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
908       $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
913           When setting rendition, the font mask will be ignored.
914
915           See the section on RENDITION, above.
916
917       $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
922       $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
928       $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
933           $text = $line->t ([$new_text])
934               Returns or replaces the full text of the line, similar to
935               "ROW_t"
936
937           $rend = $line->r ([$new_rend])
938               Returns or replaces the full rendition array of the line,
939               similar to "ROW_r"
940
941           $length = $line->l
942               Returns the length of the line in cells, similar to "ROW_l".
943
944           $rownum = $line->beg
945           $rownum = $line->end
946               Return the row number of the first/last row of the line,
947               respectively.
948
949           $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
954           ($row, $col) = $line->coord_of ($offset)
955               Translates a string offset into terminal coordinates again.
956
957       $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
962       $string = $term->special_decode $text
963           Converts rxvt-unicodes text representation into a perl string. See
964           "$term->ROW_t" for details.
965
966       $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
972       $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
976       $term->allow_events_async
977           Calls XAllowEvents with AsyncBoth for the most recent grab.
978
979       $term->allow_events_sync
980           Calls XAllowEvents with SyncBoth for the most recent grab.
981
982       $term->allow_events_replay
983           Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for
984           the most recent grab.
985
986       $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
991       $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
1012   The "urxvt::popup" Class
1013       $popup->add_title ($title)
1014           Adds a non-clickable title to the popup.
1015
1016       $popup->add_separator ([$sepchr])
1017           Creates a separator, optionally using the character given as
1018           $sepchr.
1019
1020       $popup->add_button ($text, $cb)
1021           Adds a clickable button to the popup. $cb is called whenever it is
1022           selected.
1023
1024       $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
1029       $popup->show
1030           Displays the popup (which is initially hidden).
1031
1032   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
1036          $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
1045       $timer = new urxvt::timer
1046           Create a new timer object in started state. It is scheduled to fire
1047           immediately.
1048
1049       $timer = $timer->cb (sub { my ($timer) = @_; ... })
1050           Set the callback to be called when the timer triggers.
1051
1052       $timer = $timer->set ($tstamp[, $interval])
1053           Set the time the event is generated to $tstamp (and optionally
1054           specifies a new $interval).
1055
1056       $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
1061       $timer = $timer->start
1062           Start the timer.
1063
1064       $timer = $timer->start ($tstamp[, $interval])
1065           Set the event trigger time to $tstamp and start the timer.
1066           Optionally also replaces the interval.
1067
1068       $timer = $timer->after ($delay[, $interval])
1069           Like "start", but sets the expiry timer to c<urxvt::NOW + $delay>.
1070
1071       $timer = $timer->stop
1072           Stop the timer.
1073
1074   The "urxvt::iow" Class
1075       This class implements io watchers/events. Example:
1076
1077         $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
1090       $iow = new urxvt::iow
1091           Create a new io watcher object in stopped state.
1092
1093       $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
1097       $iow = $iow->fd ($fd)
1098           Set the file descriptor (not handle) to watch.
1099
1100       $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
1105       $iow = $iow->start
1106           Start watching for requested events on the given handle.
1107
1108       $iow = $iow->stop
1109           Stop watching for events on the given file handle.
1110
1111   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
1116       $iw = new urxvt::iw
1117           Create a new idle watcher object in stopped state.
1118
1119       $iw = $iw->cb (sub { my ($iw) = @_; ... })
1120           Set the callback to be called when the watcher triggers.
1121
1122       $timer = $timer->start
1123           Start the watcher.
1124
1125       $timer = $timer->stop
1126           Stop the watcher.
1127
1128   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
1132          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
1142       $pw = new urxvt::pw
1143           Create a new process watcher in stopped state.
1144
1145       $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
1146           Set the callback to be called when the timer triggers.
1147
1148       $pw = $timer->start ($pid)
1149           Tells the watcher to start watching for process $pid.
1150
1151       $pw = $pw->stop
1152           Stop the watcher.
1153

ENVIRONMENT

1155   URXVT_PERL_VERBOSITY
1156       This variable controls the verbosity level of the perl extension.
1157       Higher numbers indicate more verbose output.
1158
1159       == 0 - fatal messages
1160       >= 3 - script loading and management
1161       >=10 - all called hooks
1162       >=11 - hook return values
1163

AUTHOR

1165        Marc Lehmann <schmorp@schmorp.de>
1166        http://software.schmorp.de/pkg/rxvt-unicode
1167
1168
1169
11709.22                              2019-02-02                      urxvtperl(3)
Impressum