urxvt Packageurxvt Packageurxvt::anyevent Classurxvt::term Classurxvt::popup Classurxvt::timer Classurxvt::iow Classurxvt::iw Classurxvt::pw ClassEverytime a terminal object gets created, scripts specified via the
-perl resource are loaded and associated with it.
Everytime a terminal object gets created, extension scripts specified via
+the perl resource are loaded and associated with it.
Scripts are compiled in a 'use strict' and 'use utf8' environment, and thus must be encoded as UTF-8.
Each script will only ever be loaded once, even in rxvtd, where scripts will be shared (but not enabled) for all terminals.
-
This section describes the extensiosn delivered with this version. You can +
This section describes the extensions delivered with this release. You can find them in /opt/rxvt/lib/urxvt/perl/.
You can activate them like this:
rxvt -pe <extensionname>+
Or by adding them to the resource for extensions loaded by default:
++ URxvt.perl-ext-common: default,automove-background,selection-autotransform
(More) intelligent selection. This extension tries to be more intelligent
+when the user extends selections (double-click and further clicks). Right
+now, it tries to select words, urls and complete shell-quoted
+arguments, which is very convenient, too, if your ls supports
+--quoting-style=shell.
--quoting-style=shell.
+A double-click usually selects the word under the cursor, further clicks +will enlarge the selection.
+The selection works by trying to match a number of regexes and displaying +them in increasing order of length. You can add your own regexes by +specifying resources of the form:
++ URxvt.selection.pattern-0: perl-regex + URxvt.selection.pattern-1: perl-regex + ...
It also offers the following bindable event:
+The index number (0, 1...) must not have any holes, and each regex must +contain at least one pair of capturing parentheses, which will be used for +the match. For example, the followign adds a regex that matches everything +between two vertical bars:
++ URxvt.selection.pattern-0: \\|([^|]+)\\|+
Another example: Programs I use often output ``absolute path: '' at the +beginning of a line when they process multiple files. The following +pattern matches the filename (note, there is a single space at the very +end):
++ URxvt.selection.pattern-0: ^(/[^:]+):\+
You can look at the source of the selection extension to see more +interesting uses, such as parsing a line from beginning to end.
+This extension also offers following bindable keyboard commands:
Rot-13 the selection when activated. Used via keyboard trigger:
URxvt.keysym.C-M-r: perl:selection:rot13
Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at +runtime.
+Other extensions can extend this popup menu by pushing a code reference
+onto @{ $term-{option_popup_hook} }>, which gets called whenever the
+popup is being displayed.
It's sole argument is the popup menu, which can be modified. It should +either return nothing or a string, the initial boolean value and a code +reference. The string will be used as button text and the code reference +will be called when the toggle changes, with the new boolean value as +first argument.
+The following will add an entry myoption that changes
+$self-{myoption}>:
+ push @{ $self->{term}{option_popup_hook} }, sub {
+ ("my option" => $myoption, sub { $self->{myoption} = $_[0] })
+ };
+Binds a popup menu to Ctrl-Button3 that lets you convert the selection +text into various other formats/action (such as uri unescaping, perl +evaluation, web-browser starting etc.), depending on content.
+Other extensions can extend this popup menu by pushing a code reference
+onto @{ $term-{selection_popup_hook} }>, which gets called whenever the
+popup is being displayed.
It's sole argument is the popup menu, which can be modified. The selection
+is in $_, which can be used to decide wether to add something or not.
+It should either return nothing or a string and a code reference. The
+string will be used as button text and the code reference will be called
+when the button gets activated and should transform $_.
The following will add an entry a to b that transforms all as in
+the selection to bs, but only if the selection currently contains any
+as:
+ push @{ $self->{term}{selection_popup_hook} }, sub {
+ /a/ ? ("a to be" => sub { s/a/b/g }
+ : ()
+ };
+Adds regex search functionality to the scrollback buffer, triggered
+by a hotkey (default: M-s). While in search mode, normal terminal
+input/output is suspended and a regex is displayed at the bottom of the
+screen.
Inputting characters appends them to the regex and continues incremental
+search. BackSpace removes a character from the regex, Up and Down
+search upwards/downwards in the scrollback buffer, End jumps to the
+bottom. Escape leaves search mode and returns to the point where search
+was started, while Enter or Return stay at the current position and
+additionally stores the first match in the current line into the primary
+selection.
The regex defaults to ``(?i)'', resulting in a case-insensitive search. To
+get a case-sensitive search you can delete this prefix using BackSpace
+or simply use an uppercase character which removes the ``(?i)'' prefix.
See perlre for more info about perl regular expression syntax.
+A support package that tries to make editing with readline easier. At +the moment, it reacts to clicking shift-left mouse button by trying to +move the text cursor to this position. It does so by generating as many +cursor-left or cursor-right keypresses as required (the this only works +for programs that correctly support wide characters).
+To avoid too many false positives, this is only done when:
+The normal selection mechanism isn't disabled, so quick successive clicks +might interfere with selection creation in harmless ways.
+This selection allows you to do automatic transforms on a selection +whenever a selection is made.
+It works by specifying perl snippets (most useful is a single s///
+operator) that modify $_ as resources:
+ URxvt.selection-autotransform.0: transform + URxvt.selection-autotransform.1: transform + ...+
For example, the following will transform selections of the form
+filename:number, often seen in compiler messages, into vi +$filename
+$word:
+ URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/+
And this example matches the same,but replaces it with vi-commands you can +paste directly into your (vi :) editor:
++ URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/+
Of course, this can be modified to suit your needs and your editor :)
+To expand the example above to typical perl error messages (``XXX at +FILENAME line YYY.''), you need a slightly more elaborate solution:
++ URxvt.selection.pattern-0: ( at .*? line \\d+[,.]) + URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/+
The first line tells the selection code to treat the unchanging part of +every error message as a selection pattern, and the second line transforms +the message into vi commands to load the file.
+This transforms the terminal into a tabbar with additional terminals, that +is, it implements what is commonly refered to as ``tabbed terminal''. The topmost line +displays a ``[NEW]'' button, which, when clicked, will add a new tab, followed by one +button per tab.
+Clicking a button will activate that tab. Pressing Shift-Left and +Shift-Right will switch to the tab left or right of the current one, +while Shift-Down creates a new tab.
+The tabbar itself can be configured similarly to a normal terminal, but
+with a resource class of URxvt.tabbed. In addition, it supports the
+following four resources (shown with defaults):
+ URxvt.tabbed.tabbar-fg: <colour-index, default 3> + URxvt.tabbed.tabbar-bg: <colour-index, default 0> + URxvt.tabbed.tab-fg: <colour-index, default 0> + URxvt.tabbed.tab-bg: <colour-index, default 1>+
See COLOR AND GRAPHICS in the rxvt(1) manpage for valid
+indices.
Uses per-line display filtering (on_line_update) to underline urls and
+make them clickable. When middle-clicked, the program specified in the
+resource urlLauncher (default x-www-browser) will be started with
+the URL as first argument.
This (experimental) perl extension implements OnTheSpot editing. It does +not work perfectly, and some input methods don't seem to work well with +OnTheSpot editing in general, but it seems to work at leats for SCIM and +kinput2.
+You enable it by specifying this extension and a preedit style of
+OnTheSpot, i.e.:
+ rxvt -pt OnTheSpot -pe xim-onthespot+
This is basically a very small extension that dynamically changes the +background pixmap offset to the window position, in effect creating the +same effect as pseudo transparency with a custom pixmap. No scaling is +supported in this mode. Exmaple:
++ rxvt -pixmap background.xpm -pe automove-background+
A not very useful example of filtering all text output to the terminal +by replacing all line-drawing characters (U+2500 .. U+259F) by a +similar-looking ascii character.
+Displays a digital clock using the built-in overlay.
+Somewhat of a misnomer, this extension adds two menu entries to the +selection popup that allows one ti run external commands to store the +selection somewhere and fetch it again.
+We use it to implement a ``distributed selection mechanism'', which just +means that one command uploads the file to a remote server, and another +reads it.
+The commands can be set using the URxvt.remote-selection.store and
+URxvt.remote-selection.fetch resources. The first should read the
+selection to store from STDIN (always in UTF-8), the second should provide
+the selection data on STDOUT (also in UTF-8).
The defaults (which are likely useless to you) use rsh and cat:
++ URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection' + URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'+
This is a little rarely useful extension that Uploads the selection as +textfile to a remote site (or does other things). (The implementation is +not currently secure for use in a multiuser environment as it writes to +/tmp directly.).
+It listens to the selection-pastebin:remote-pastebin keyboard command,
+i.e.
+ URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin+
Pressing this combination runs a command with % replaced by the name of
+the textfile. This command can be set via a resource:
+ URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.+
And the default is likely not useful to anybody but the few people around +here :)
+The name of the textfile is the hex encoded md5 sum of the selection, so +the same content should lead to the same filename.
After a successful upload the selection will be replaced by the text given
+in the selection-pastebin-url resource (again, the % is the placeholder
+for the filename):
+ URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%+
Displays a very simple digital clock in the upper right corner of the window. Illustrates overwriting the refresh callbacks to create your own -overlays or changes. +overlays or changes.
+
+
Argument names also often indicate the type of a parameter. Here are some +hints on what they mean:
+Rxvt-unicodes special way of encoding text, where one ``unicode'' character +always represents one screen cell. See ROW_t for a discussion of this format.
+A perl text string, with an emphasis on text. It can store all unicode +characters and is to be distinguished with text encoded in a specific +encoding (often locale-specific) and binary data.
+Either binary data or - more common - a text string encoded in a +locale-specific way.
++
+Every perl extension is a perl class. A separate perl object is created
+for each terminal and each extension and passed as the first parameter to
+hooks. So extensions can use their $self object without having to think
+about other extensions, with the exception of methods and members that
+begin with an underscore character _: these are reserved for internal
+use.
Although it isn't a urxvt::term object, you can call all methods of the
+urxvt::term class on this object.
It has the following methods and data members:
+Returns the urxvt::term object associated with this instance of the
+extension. This member must not be changed in any way.
Dynamically enable the given hooks (named without the on_ prefix) for
+this extension, replacing any previous hook. This is useful when you want
+to overwrite time-critical hooks only temporarily.
Dynamically disable the given hooks.
+
The following subroutines can be declared in loaded scripts, and will be +
The following subroutines can be declared in extension files, and will be called whenever the relevant event happens.
-The first argument passed to them is an object private to each terminal
-and extension package. You can call all urxvt::term methods on it, but
-its not a real urxvt::term object. Instead, the real urxvt::term
-object that is shared between all packages is stored in the term
-member.
All of them must return a boolean value. If it is true, then the event -counts as being consumed, and the invocation of other hooks is skipped, -and the relevant action might not be carried out by the C++ code.
-When in doubt, return a false value (preferably ()).
The first argument passed to them is an extension oject as described in
+the in the Extension Objects section.
All of these hooks must return a boolean value. If any of the called +hooks returns true, then the event counts as being consumed, and the +relevant action might not be carried out by the C++ code.
+When in doubt, return a false value (preferably ()). >
Called after a new terminal object has been initialized, but before
+windows are created or the command gets run. Most methods are unsafe to
+call or deliver senseless data, as terminal size and other characteristics
+have not yet been determined. You can safely query and change resources
+and options, though. For many purposes the on_start hook is a better
+place.
Called at the very end of initialisation of a new terminal, just before +trying to map (display) the toplevel and returning to the mainloop.
+Called whenever something tries to destroy terminal, when the terminal is +still fully functional (not for long, though).
+Called after the screen is ``reset'' for any reason, such as resizing or control sequences. Here is where you can react on changes to size-related -variables. +variables.
Called just after the child process has been forked.
Called just after the child process has exited. $status is the status
+from waitpid.
Called whenever a selection has been made by the user, but before the selection text is copied, so changes to the beginning, end or type of the -selection will be honored. +selection will be honored.
Returning a true value aborts selection making by urxvt, in which case you
have to make a selection yourself by calling $term->selection_grab.
Called whenever a selection has been copied, but before the selection is
requested from the server. The selection text can be queried and changed
-by calling $term->selection.
+by calling $term->selection.
Returning a true value aborts selection grabbing. It will still be hilighted.
Called whenever the user tries to extend the selection (e.g. with a double click) and is either supposed to return false (normal operation), or should extend the selection itelf and return true to suppress the built-in -processing. +processing. This can happen multiple times, as long as the callback +returns true, it will be called on every further click by the user and is +supposed to enlarge the selection more and more, if possible.
See the selection example extension.
Called whenever the view offset changes, i..e the user or program
scrolls. Offset 0 means display the normal terminal, positive values
-show this many lines of scrollback.
+show this many lines of scrollback.
Called whenever lines scroll out of the terminal area into the scrollback
buffer. $lines is the number of lines scrolled out and may be larger
-than the scroll back buffer or the terminal.
+than the scroll back buffer or the terminal.
It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
$nrow - 1) represent the lines to be scrolled out). $saved is the total
number of lines that will be in the scrollback buffer.
program(s) running in the urxvt window send output.
+Called on every OSC sequence and can be used to suppress it or modify its +behaviour. The default should be to return an empty list. A true value +suppresses execution of the request completely. Make sure you don't get +confused by recursive invocations when you output an osc sequence within +this callback.
on_osc_seq_perl should be used for new behaviour.
Called whenever the ESC ] 777 ; string ST command sequence (OSC = operating system command) is processed. Cursor position and other state information is up-to-date when this happens. For interoperability, the string should start with the extension name and a colon, to distinguish it from commands for other extensions, and this might be enforced in the -future. +future.
Be careful not ever to trust (in a security sense) the data you receive, as its source can not easily be controleld (e-mail content, messages from other users on the same system etc.).
Called whenever text is about to be output, with the text as argument. You
+can filter/change and output the text yourself by returning a true value
+and calling $term->scr_add_lines yourself. Please note that this
+might be very slow, however, as your hook is called for all text being
+output.
Called whenever some data is written to the tty/pty and can be used to +suppress or filter tty input.
+Called whenever a line was updated or changed. Can be used to filter +screen output (e.g. underline urls or other useless stuff). Only lines +that are being shown will be filtered, and, due to performance reasons, +not always immediately.
+The row number is always the topmost row of the line if the line spans +multiple rows.
+Please note that, if you change the line, then the hook might get called +later with the already-modified line (e.g. if unrelated parts change), so +you cannot just toggle rendition bits, but only set them.
+Called just before the screen gets redrawn. Can be used for overlay or similar effects by modify terminal contents in refresh_begin, and restoring them in refresh_end. The built-in overlay and selection display -code is run after this hook, and takes precedence. +code is run after this hook, and takes precedence.
on_refresh_begin.
+Called just after the screen gets redrawn. See on_refresh_begin.
Called whenever the a user-configured event is being activated (e.g. via
+a perl:string action bound to a key, see description of the keysym
+resource in the rxvt(1) manpage).
The event is simply the action string. This interface is assumed to change +slightly in the future.
+perl:string action bound to it (see description of the keysym
-resource in the rxvt(1) manpage).
+Called just after the new window size has been calculcated, but before +windows are actually being resized or hints are being set. If this hook +returns TRUE, setting of the window hints is being skipped.
Called on every X event received on the vt window (and possibly other +windows). Should only be used as a last resort. Most event structure +members are not passed.
+Called whenever the window gets the keyboard focus, before rxvt-unicode +does focus in processing.
+Called wheneever the window loses keyboard focus, before rxvt-unicode does +focus out processing.
+Called whenever the corresponding X event is received for the terminal If +the hook returns true, then the even will be ignored by rxvt-unicode.
+The event is a hash with most values as named by Xlib (see the XEvent
+manpage), with the additional members row and col, which are the
+(real, not screen-based) row and column under the mouse cursor.
on_key_press additionally receives the string rxvt-unicode would
+output, if any, in locale-specific encoding.
subwindow.
+Called when various types of ClientMessage events are received (all with +format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
+
urxvt PackageThe rxvt-unicode library directory, where, among other things, the perl +modules and scripts are stored.
+urxvt::term object.
+The resource class and name rxvt-unicode uses to look up X resources.
The basename of the installed binaries, usually urxvt.
The current terminal. This variable stores the current urxvt::term
+object, whenever a callback/hook is executing.
All coderefs in this array will be called as methods of the next newly
+created urxvt::term object (during the on_init phase). The array
+gets cleared before the codereferences that were in it are being executed,
+so coderefs can push themselves onto it again if they so desire.
This complements to the perl-eval commandline option, but gets executed +first.
+Works similar to @TERM_INIT, but contains perl package/class names, which
+get registered as normal extensions after calling the hooks in @TERM_INIT
+but before other extensions. Gets cleared just like @TERM_INIT.
urxvt PackageFatally aborts execution with the given error message. Avoid at all costs! The only time this is acceptable is when the terminal process -starts up. +starts up.
rxvt_warn with the given string which should not include a
+Calls rxvt_warn with the given string which should not include a
newline. The module also overwrites the warn builtin with a function
-that calls this function.
+that calls this function.
Using this function has the advantage that its output ends up in the correct place, e.g. on stderr of the connecting urxvtc client.
Messages have a size limit of 1023 bytes currently.
Returns all urxvt::term objects that exist in this process, regardless of +wether they are started, being destroyed etc., so be careful. Only term +objects that have perl extensions attached will be returned (because there +is no urxvt::term objet associated with others).
+Returns the ``current time'' (as per the event loop).
+Various constants for use in X calls and event processing.
+
Returns the default rendition, as used when the terminal is starting up or +being reset. Useful as a base to start when creating renditions.
Return the rendition mask used for overlays by default.
Return the bit that enabled bold, italic, blink, reverse-video and underline, respectively. To enable such a style, just logically OR it into -the bitset. +the bitset.
Return the foreground/background colour index, respectively.
+Replace the foreground/background colour in the rendition mask with the +specified one.
+Return the ``custom'' value: Every rendition has 5 bits for use by extensions. They can be set and changed as you like and are initially -zero. +zero.
Change the custom value.
+
+urxvt::anyevent ClassThe sole purpose of this class is to deliver an interface to the
+AnyEvent module - any module using it will work inside urxvt without
+further programming. The only exception is that you cannot wait on
+condition variables, but non-blocking condvar use is ok. What this means
+is that you cannot use blocking APIs, but the non-blocking variant should
+work.
urxvt::term ClassCreates a new terminal, very similar as if you had started it with system
+$rxvtname, arg.... $envhashref must be a reference to a %ENV-like
+hash which defines the environment of the new terminal.
Croaks (and probably outputs an error message) if the new instance
+couldn't be created. Returns undef if the new instance didn't
+initialise perl, and the terminal object otherwise. The init and
+start hooks will be called before this call returns, and are free to
+refer to global data (which is race free).
Destroy the terminal object (close the window, free resources +etc.). Please note that rxvt will not exit as long as any event +watchers (timers, io watchers) are still active.
+Works like the combination of the fork/exec builtins, which executes
+(``starts'') programs in the background. This function takes care of setting
+the user environment before exec'ing the command (e.g. PATH) and should
+be preferred over explicit calls to exec or system.
Returns the pid of the subprocess or undef on error.
Returns true if the option specified by $optval is enabled, and
+optionally change it. All option values are stored by name in the hash
+%urxvt::OPTION. Options not enabled in this binary are not in the hash.
Here is a a likely non-exhaustive list of option names, please see the +source file /src/optinc.h to see the actual list:
++ borderLess console cursorBlink cursorUnderline hold iconic insecure + intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage + override-redirect pastableTabs pointerBlank reverseVideo scrollBar + scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput + scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs + transparent tripleclickwords utmpInhibit visualBell+
Returns the current resource value associated with a given name and
optionally sets a new value. Setting values is most useful in the init
-hook. Unset resources are returned and accepted as undef.
+hook. Unset resources are returned and accepted as undef.
The new value must be properly encoded to a suitable character encoding @@ -408,8 +1115,8 @@
Here is a a likely non-exhaustive list of resource names, not all of which -are supported in every build, please see the source to see the actual -list:
+are supported in every build, please see the source file /src/rsinc.h +to see the actual list:@@ -417,75 +1124,98 @@ borderLess color cursorBlink cursorUnderline cutchars delete_key display_name embed ext_bwidth fade font geometry hold iconName imFont imLocale inputMethod insecure int_bwidth intensityStyles - italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier - mouseWheelScrollPage name pastableTabs path perl_eval perl_ext - perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd - reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating - scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput - scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle - shade term_name title transparent transparent_all tripleclickwords - utmpInhibit visualBell+ italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier + mouseWheelScrollPage name override_redirect pastableTabs path perl_eval + perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay + preeditType print_pipe pty_fd reverseVideo saveLines scrollBar + scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness + scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle + secondaryScreen secondaryScroll selectstyle shade term_name title + transient_for transparent transparent_all tripleclickwords utmpInhibit + visualBell
Returns the X-Resource for the given pattern, excluding the program or
+class name, i.e. $term->x_resource ("boldFont") should return the
+same value as used by this instance of rxvt-unicode. Returns undef if no
+resource with that pattern exists.
This method should only be called during the on_start hook, as there is
+only one resource database per display, and later invocations might return
+the wrong resources.
$newtext.
+Adds a keymap translation exactly as specified via a resource. See the
+keysym resource in the rxvt(1) manpage.
#=item $term->overlay ($x, $y, $text) -# -#Create a simple multi-line overlay box. See the next method for details. -# -#=cut
+Return and optionally change the current rendition. Text that is output by +the terminal application will use this style.
sub urxvt::term::scr_overlay { -die; - my ($self, $x, $y, $text) = @_;
+Return the current coordinates of the text cursor position and optionally +set it (which is usually bad as applications don't expect that).
- my @lines = split /\n/, $text;+
Return the current values of the selection mark, begin or end positions, +and optionally set them to new values.
- my $w = 0;
- for (map $self->strwidth ($_), @lines) {
- $w = $_ if $w < $_;
- }
+Tries to make a selection as set by selection_beg and
+selection_end. If $rectangular is true (default: false), a
+rectangular selection will be made. This is the prefered function to make
+a selection.
- $self->scr_overlay_new ($x, $y, $w, scalar @lines); - $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; -}-
Try to request the primary selection text from the server (for example, as
+set by the next method). No visual feedback will be given. This function
+is mostly useful from within on_sel_grab hooks.
Return the current selection text and optionally replace it by $newtext.
Create a simple multi-line overlay box. See the next method for details.
+Create a new (empty) overlay at the given position with the given
width/height. $rstyle defines the initial rendition style
-(default: OVERLAY_RSTYLE).
+(default: OVERLAY_RSTYLE).
If $border is 2 (default), then a decorative border will be put
@@ -503,95 +1233,274 @@
The methods currently supported on urxvt::overlay objects are:
$term->ROW_t and $term->ROW_r in that it puts
+Similar to $term->ROW_t and $term->ROW_r in that it puts
text in rxvt-unicode's special encoding and an array of rendition values
-at a specific position inside the overlay.
+at a specific position inside the overlay.
If visible, hide the overlay, but do not destroy it.
If hidden, display the overlay again.
+Creates a new urxvt::popup object that implements a popup menu. The
+$event must be the event causing the menu to pop up (a button event,
+currently).
Returns the number of screen-cells this string would need. Correctly +accounts for wide and combining characters.
Convert the given text string into the corresponding locale encoding.
Convert the given locale-encoded octets into a perl string.
$data to the tty (i.e. as program input). To
+XORs the rendition values in the given span with the provided value
+(default: RS_RVid), which MUST NOT contain font styles. Useful in
+refresh hooks to provide effects similar to the selection.
Similar to scr_xor_span, but xors a rectangle instead. Trailing
+whitespace will additionally be xored with the $rstyle2, which defaults
+to RS_RVid | RS_Uline, which removes reverse video again and underlines
+it instead. Both styles MUST NOT contain font styles.
Ring the bell!
+Write the given text string to the screen, as if output by the application +running inside the terminal. It may not contain command sequences (escape +codes), but is free to use line feeds, carriage returns and tabs. The +string is a normal text string, not in locale-dependent encoding.
+Normally its not a good idea to use this function, as programs might be
+confused by changes in cursor position or scrolling. Its useful inside a
+on_add_lines hook, though.
Switch to given screen - 0 primary, 1 secondary.
+Similar to scr_add_lines, but the argument must be in the
+locale-specific encoding of the terminal and can contain command sequences
+(escape codes) that will be interpreted.
Write the octets given in $data to the tty (i.e. as program input). To
pass characters instead of octets, you should convert your strings first
-to the locale-specific encoding using $term->locale_encode.
+to the locale-specific encoding using $term->locale_encode.
-geometry, excluding any scrollback).
+Replaces the event mask of the pty watcher by the given event mask. Can
+be used to suppress input and output handling to the pty/tty. See the
+description of urxvt::timer->events. Make sure to always restore
+the previous value.
Returns the master file descriptor for the pty in use, or -1 if no pty
+is used.
0, which displays the normal terminal contents. Larger values scroll
-this many lines into the scrollback buffer.
+Return the window id of the toplevel window.
Return the window id of the terminal window.
+Adds the specified events to the vt event mask. Useful e.g. when you want +to receive pointer events all the times:
++ $term->vt_emask_add (urxvt::PointerMotionMask);+
Deliver various fake events to to terminal.
+Return various integers describing terminal characteristics.
+Return the DISPLAY used by rxvt-unicode.
+Returns the LC_CTYPE category string used by this rxvt-unicode.
+Returns a copy of the environment in effect for the terminal as a hashref
+similar to \%ENV.
Returns the environment as array of strings of the form VAR=VALUE.
Return the argument vector as this terminal, similar to @ARGV, but +includes the program name as first element.
+Return the modifier masks corresponding to the ``ISO Level 3 Shift'' (often +AltGr), the meta key (often Alt) and the num lock key, if applicable.
+Returns the currently displayed screen (0 primary, 1 secondary).
+Returns wether the cursor is currently hidden or not.
+Returns the row number of the topmost displayed line. Maximum value is
+0, which displays the normal terminal contents. Lower values scroll
+this many lines into the scrollback buffer.
Requests a screen refresh. At the next opportunity, rxvt-unicode will compare the on-screen display with its stored representation. If they -differ, it redraws the differences. +differ, it redraws the differences.
Used after changing terminal contents to display them.
$row_number. Row 0
+Returns the text of the entire row with number $row_number. Row 0
is the topmost terminal line, row $term->$ncol-1 is the bottommost
terminal line. The scrollback buffer starts at line -1 and extends to
-line -$term->nsaved. Nothing will be returned if a nonexistent line
-is requested.
+line -$term->nsaved. Nothing will be returned if a nonexistent line
+is requested.
If $new_text is specified, it will replace characters in the current
@@ -600,11 +1509,11 @@
automatically be updated.
$text is in a special encoding: tabs and wide characters that use more
-than one cell when displayed are padded with urxvt::NOCHAR characters
-(chr 65535). Characters with combining characters and other characters
-that do not fit into the normal tetx encoding will be replaced with
-characters in the private use area.
$text is in a special encoding: tabs and wide characters that use more
+than one cell when displayed are padded with $urxvt::NOCHAR (chr 65535)
+characters. Characters with combining characters and other characters that
+do not fit into the normal tetx encoding will be replaced with characters
+in the private use area.
You have to obey this encoding when changing text. The advantage is @@ -612,16 +1521,16 @@ characters.
The methods $term->special_encode and $term->special_decode
+
The methods $term->special_encode and $term->special_decode
can be used to convert normal strings into this encoding and vice versa.
$term->ROW_t, but returns an arrayref with rendition
+Like $term->ROW_t, but returns an arrayref with rendition
bitsets. Rendition bitsets contain information about colour, font, font
-styles and similar information. See also $term->ROW_t.
+styles and similar information. See also $term->ROW_t.
When setting rendition, the font mask will be ignored.
@@ -629,87 +1538,202 @@See the section on RENDITION, above.
Returns the number of screen cells that are in use (``the line
length''). Unlike the urxvt core, this returns $term->ncol if the
-line is joined with the following one.
+line is joined with the following one.
Returns true if the row is part of a multiple-row logical ``line'' (i.e. joined with the following row), which means all characters are in use and it is continued on the next row (and possibly a continuation of the -previous row(s)). +previous row(s)).
urxvt::line object that stores information
+Create and return a new urxvt::line object that stores information
about the logical line that row $row_number is part of. It supports the
-following methods:
+following methods:
ROW_t
+Returns or replaces the full text of the line, similar to ROW_t
ROW_r
+Returns or replaces the full rendition array of the line, similar to ROW_r
ROW_l.
+Returns the length of the line in cells, similar to ROW_l.
Return the row number of the first/last row of the line, respectively.
Returns the character offset of the given row|col pair within the logical +line. Works for rows outside the line, too, and returns corresponding +offsets outside the string.
Translates a string offset into terminal coordinates again.
Converts a perl string into the special encoding used by rxvt-unicode,
where one character corresponds to one screen cell. See
-$term->ROW_t for details.
+$term->ROW_t for details.
Converts rxvt-unicodes text reprsentation into a perl string. See
+$term->ROW_t for details.
Register/unregister a synchronous button grab. See the XGrabButton +manpage.
+Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
+synchronous ($sync is true). Also remembers the grab timestampe.
Calls XAllowEvents with AsyncBoth for the most recent grab.
+Calls XAllowEvents with SyncBoth for the most recent grab.
+Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most +recent grab.
+Calls XUngrab for the most recent grab. Is called automatically on +evaluation errors, as it is better to lose the grab in the error case as +the session.
+Various X or X-related functions. The $term object only serves as
+the source of the display, otherwise those functions map more-or-less
+directory onto the X functions of the same name.
+
+urxvt::popup ClassAdds a non-clickable title to the popup.
+Creates a separator, optionally using the character given as $sepchr.
Adds a clickable button to the popup. $cb is called whenever it is
+selected.
$term->ROW_t for details.
+Adds a toggle/checkbox item to the popup. The callback gets called +whenever it gets toggled, with a boolean indicating its new value as its +first argument.
Displays the popup (which is initially hidden).
+
urxvt::timer ClassCreate a new timer object in started state. It is scheduled to fire +immediately.
Set the callback to be called when the timer triggers.
Return the time this watcher will fire next.
Set the time the event is generated to $tstamp.
$interval is 0), the timer will automatically
+Normally (and when $interval is 0), the timer will automatically
stop after it has fired once. If $interval is non-zero, then the timer
-is automatically rescheduled at the given intervals.
+is automatically rescheduled at the given intervals.
Start the timer.
$tstamp and start the timer.
+Set the event trigger time to $tstamp and start the timer.
Like start, but sets the expiry timer to c<urxvt::NOW + $delay>.
Stop the timer.
+
urxvt::iow ClassCreate a new io watcher object in stopped state.
$reventmask
-is a bitset as described in the events method.
+Set the callback to be called when io events are triggered. $reventmask
+is a bitset as described in the events method.
Set the filedescriptor (not handle) to watch.
1) enables watching for read
-data, Bit #1 (value 2) enables watching for write data.
+Set the event mask to watch. The only allowed values are
+urxvt::EVENT_READ and urxvt::EVENT_WRITE, which might be ORed
+together, or urxvt::EVENT_NONE.
Start watching for requested events on the given handle.
Stop watching for events on the given filehandle.
+
+urxvt::iw ClassThis class implements idle watchers, that get called automatically when +the process is idle. They should return as fast as possible, after doing +some useful work.
+Create a new idle watcher object in stopped state.
+Set the callback to be called when the watcher triggers.
+Start the watcher.
+Stop the watcher.
++
+urxvt::pw ClassThis class implements process watchers. They create an event whenever a +process exits, after which they stop automatically.
+
+ my $pid = fork;
+ ...
+ $term->{pw} = urxvt::pw
+ ->new
+ ->start ($pid)
+ ->cb (sub {
+ my ($pw, $exit_status) = @_;
+ ...
+ });
+Create a new process watcher in stopped state.
+Set the callback to be called when the timer triggers.
+Tells the wqtcher to start watching for process $pid.
Stop the watcher.
+
This variable controls the verbosity level of the perl extension. Higher numbers indicate more verbose output.