--- rxvt-unicode/doc/rxvtperl.3.html 2006/01/02 15:59:25 1.1
+++ rxvt-unicode/doc/rxvtperl.3.html 2006/02/21 01:00:40 1.43
@@ -15,13 +15,29 @@
NAME
SYNOPSIS
DESCRIPTION
+ PREPACKAGED EXTENSIONS
+ API DOCUMENTATION
+
+ ENVIRONMENT
+
AUTHOR
@@ -31,43 +47,532 @@
+
rxvtperl - rxvt-unicode's embedded perl interpreter
-* Put your scripts into /opt/rxvt/lib/urxvt/perl-ext/, they will be loaded automatically.
-* Each script will only be loaded once, even in urxvtd, and will be valid
-globally.
-* Scripts are evaluated in a 'use strict' and 'use utf8' environment, and
-thus must be encoded as UTF-8.
+
+ # create a file grab_test in $HOME:
sub on_sel_grab {
warn "you selected ", $_[0]->selection;
()
}
- 1
+ # start a rxvt using it:
+
+ rxvt --perl-lib $HOME -pe grab_test
+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 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
+
+- selection (enabled by default)
+
+-
+(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
.
+
+-
+
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
+ ...
+
+-
+
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:
+
+
+- rot13
+
+-
+Rot-13 the selection when activated. Used via keyboard trigger:
+
+-
+
+ URxvt.keysym.C-M-r: perl:selection:rot13
+
+
+- option-popup (enabled by default)
+
+-
+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] })
+ };
+
+
+- selection-popup (enabled by default)
+
+-
+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 a
s in
+the selection to b
s, but only if the selection currently contains any
+a
s:
+
+-
+
+ push @{ $self->{term}{selection_popup_hook} }, sub {
+ /a/ ? ("a to be" => sub { s/a/b/g }
+ : ()
+ };
+
+
+- searchable-scrollback<hotkey> (enabled by default)
+
+-
+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.
+
+
+- readline (enabled by default)
+
+-
+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 tty is in ICANON state.
+
+- - the text cursor is visible.
+
+- - the primary screen is currently being displayed.
+
+- - the mouse is on the same (multi-row-) line as the text cursor.
+
+
+The normal selection mechanism isn't disabled, so quick successive clicks
+might interfere with selection creation in harmless ways.
+- selection-autotransform
+
+-
+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.
+
+
+- tabbed
+
+-
+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.
+
+
+- mark-urls
+
+-
+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.
+
+
+- xim-onthespot
+
+-
+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
+
+
+- automove-background
+
+-
+This is basically a one-line 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
+
+
+- block-graphics-to-ascii
+
+-
+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.
+
+
+- digital-clock
+
+-
+Displays a digital clock using the built-in overlay.
+
+
+- remote-clipboard
+
+-
+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'
+
+
+- selection-pastebin
+
+-
+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/%
+
+
+- example-refresh-hooks
+
+-
+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.
+
+
+
+
+
+
+
+
+
+All objects (such as terminals, time watchers etc.) are typical
+reference-to-hash objects. The hash can be used to store anything you
+like. All members starting with an underscore (such as _ptr
or
+_hook
) are reserved for internal uses and MUST NOT be accessed or
+modified).
+When objects are destroyed on the C++ side, the perl object hashes are
+emptied, so its best to store related objects such as time watchers and
+the like inside the terminal object so they get destroyed as soon as the
+terminal is destroyed.
+Argument names also often indicate the type of a parameter. Here are some
+hints on what they mean:
+
+- $text
+
+-
+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.
+
+
+- $string
+
+-
+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.
+
+
+- $octets
+
+-
+Either binary data or - more common - a text string encoded in a
+locale-specific way.
+
+
+
+
+
+Very 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:
+
+- $urxvt_term = $self->{term}
+
+-
+Returns the
urxvt::term
object associated with this instance of the
+extension. This member must not be changed in any way.
+
+
+- $self->enable ($hook_name => $cb, [$hook_name => $cb..])
+
+-
+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.
+
+
+- $self->disable ($hook_name[, $hook_name..])
+
+-
+Dynamically disable the given hooks.
+
+
-The following subroutines can be declared in loaded scripts, and will be called
-whenever the relevant event happens.
-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 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 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 ()
). >
- on_init $term
-
Called after a new terminal object has been initialized, but before
-windows are created or the command gets run.
+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.
+
+
+- on_start $term
+
+-
+Called at the very end of initialisation of a new terminal, just before
+trying to map (display) the toplevel and returning to the mainloop.
+
+
+- on_destroy $term
+
+-
+Called whenever something tries to destroy terminal, when the terminal is
+still fully functional (not for long, though).
- on_reset $term
@@ -78,11 +583,17 @@
variables.
-- on_start $term
+- on_child_start $term, $pid
-
-Called at the very end of initialisation of a new terminal, just before
-returning to the mainloop.
+Called just after the child process has been
fork
ed.
+
+
+- on_child_exit $term, $status
+
+-
+Called just after the child process has exited.
$status
is the status
+from waitpid
.
- on_sel_make $term, $eventtime
@@ -108,18 +619,18 @@
Returning a true value aborts selection grabbing. It will still be hilighted.
-- on_focus_in $term
+- on_sel_extend $term
-
-Called whenever the window gets the keyboard focus, before urxvt does
-focus in processing.
+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. 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.
-
-- on_focus_out $term
-
-
-Called wheneever the window loses keyboard focus, before urxvt does focus
-out processing.
+
See the selection example extension.
- on_view_change $term, $offset
@@ -143,10 +654,55 @@
number of lines that will be in the scrollback buffer.
-- on_tty_activity $term *NYI*
+- on_osc_seq $term, $string
-
-Called whenever the
program(s)
running in the urxvt window send output.
+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.
+
+-
+
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.).
+
+
+- on_add_lines $term, $string
+
+-
+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.
+
+
+- on_tt_write $term, $octets
+
+-
+Called whenever some data is written to the tty/pty and can be used to
+suppress or filter tty input.
+
+
+- on_line_update $term, $row
+
+-
+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.
- on_refresh_begin $term
@@ -163,6 +719,145 @@
-
Called just after the screen gets redrawn. See
on_refresh_begin
.
+
+- on_user_command $term, $string
+
+-
+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.
+
+
+- on_resize_all_windows $tern, $new_width, $new_height
+
+-
+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.
+
+
+- on_x_event $term, $event
+
+-
+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.
+
+
+- on_focus_in $term
+
+-
+Called whenever the window gets the keyboard focus, before rxvt-unicode
+does focus in processing.
+
+
+- on_focus_out $term
+
+-
+Called wheneever the window loses keyboard focus, before rxvt-unicode does
+focus out processing.
+
+
+- on_configure_notify $term, $event
+
+- on_property_notify $term, $event
+
+- on_key_press $term, $event, $keysym, $octets
+
+- on_key_release $term, $event, $keysym
+
+- on_button_press $term, $event
+
+- on_button_release $term, $event
+
+- on_motion_notify $term, $event
+
+- on_map_notify $term, $event
+
+- on_unmap_notify $term, $event
+
+-
+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.
+
+
+- on_client_message $term, $event
+
+- on_wm_protocols $term, $event
+
+- on_wm_delete_window $term, $event
+
+-
+Called when various types of ClientMessage events are received (all with
+format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
+
+
+
+
+
+
+- $urxvt::LIBDIR
+
+-
+The rxvt-unicode library directory, where, among other things, the perl
+modules and scripts are stored.
+
+
+- $urxvt::RESCLASS, $urxvt::RESCLASS
+
+-
+The resource class and name rxvt-unicode uses to look up X resources.
+
+
+- $urxvt::RXVTNAME
+
+-
+The basename of the installed binaries, usually
urxvt
.
+
+
+- $urxvt::TERM
+
+-
+The current terminal. This variable stores the current
urxvt::term
+object, whenever a callback/hook is executing.
+
+
+- @urxvt::TERM_INIT
+
+-
+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.
+
+
+- @urxvt::TERM_EXT
+
+-
+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
.
+
@@ -179,7 +874,7 @@
urxvt::warn $string
-Calls rxvt_warn
witht eh 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.
@@ -187,12 +882,17 @@
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.
+
-$cellwidth = urxvt::wcswidth $string
+@terms = urxvt::termlist
-Returns the number of screen-cells this string would need. Correctly
-accounts for wide and combining characters.
+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).
$time = urxvt::NOW
@@ -200,11 +900,244 @@
Returns the ``current time'' (as per the event loop).
+
+urxvt::CurrentTime
+
+urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
+Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
+Button4Mask, Button5Mask, AnyModifier
+
+urxvt::NoEventMask, KeyPressMask, KeyReleaseMask,
+ButtonPressMask, ButtonReleaseMask, EnterWindowMask, LeaveWindowMask,
+PointerMotionMask, PointerMotionHintMask, Button1MotionMask, Button2MotionMask,
+Button3MotionMask, Button4MotionMask, Button5MotionMask, ButtonMotionMask,
+KeymapStateMask, ExposureMask, VisibilityChangeMask, StructureNotifyMask,
+ResizeRedirectMask, SubstructureNotifyMask, SubstructureRedirectMask,
+FocusChangeMask, PropertyChangeMask, ColormapChangeMask, OwnerGrabButtonMask
+
+urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify,
+EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose,
+GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify, DestroyNotify,
+UnmapNotify, MapNotify, MapRequest, ReparentNotify, ConfigureNotify,
+ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify,
+CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest,
+SelectionNotify, ColormapNotify, ClientMessage, MappingNotify
+
+
+Various constants for use in X calls and event processing.
+
+
+Rendition bitsets contain information about colour, font, font styles and
+similar information for each screen cell.
+The following ``macros'' deal with changes in rendition sets. You should
+never just create a bitset, you should always modify an existing one,
+as they contain important information required for correct operation of
+rxvt-unicode.
+
+- $rend = urxvt::DEFAULT_RSTYLE
+
+-
+Returns the default rendition, as used when the terminal is starting up or
+being reset. Useful as a base to start when creating renditions.
+
+
+- $rend = urxvt::OVERLAY_RSTYLE
+
+-
+Return the rendition mask used for overlays by default.
+
+
+- $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
+
+-
+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.
+
+
+- $foreground = urxvt::GET_BASEFG $rend
+
+- $background = urxvt::GET_BASEBG $rend
+
+-
+Return the foreground/background colour index, respectively.
+
+
+- $rend = urxvt::SET_FGCOLOR $rend, $new_colour
+
+- $rend = urxvt::SET_BGCOLOR $rend, $new_colour
+
+- $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
+
+-
+Replace the foreground/background colour in the rendition mask with the
+specified one.
+
+
+- $value = urxvt::GET_CUSTOM $rend
+
+-
+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.
+
+
+- $rend = urxvt::SET_CUSTOM $rend, $new_value
+
+-
+Change the custom value.
+
+
+
+
+
+The 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.
+
+
+- $term = new urxvt::term $envhashref, $rxvtname, [arg...]
+
+-
+Creates 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).
+
+
+- $term->destroy
+
+-
+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.
+
+
+- $term->exec_async ($cmd[, @args])
+
+-
+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.
+
+
+- $isset = $term->option ($optval[, $set])
+
+-
+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
+
+
+- $value = $term->resource ($name[, $newval])
+
+-
+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
.
+
+-
+
The new value must be properly encoded to a suitable character encoding
+before passing it to this method. Similarly, the returned value may need
+to be converted from the used encoding to text.
+
+-
+
Resource names are as defined in src/rsinc.h. Colours can be specified
+as resource names of the form color+<index>
, e.g. color+5
. (will
+likely change).
+
+-
+
Please note that resource strings will currently only be freed when the
+terminal is destroyed, so changing options frequently will eat memory.
+
+-
+
Here is a a likely non-exhaustive list of resource names, not all of which
+are supported in every build, please see the source file /src/rsinc.h
+to see the actual list:
+
+-
+
+ answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
+ 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 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
+
+
+- $value = $term->x_resource ($pattern)
+
+-
+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.
+
+
+- $success = $term->parse_keysym ($keysym_spec, $command_string)
+
+-
+Adds a keymap translation exactly as specified via a resource. See the
+
keysym
resource in the rxvt(1)
manpage.
+
+
+- $rend = $term->rstyle ([$new_rstyle])
+
+-
+Return and optionally change the current rendition. Text that is output by
+the terminal application will use this style.
+
+
+- ($row, $col) = $term->screen_cur ([$row, $col])
+
+-
+Return the current coordinates of the text cursor position and optionally
+set it (which is usually bad as applications don't expect that).
+
+
- ($row, $col) = $term->selection_mark ([$row, $col])
- ($row, $col) = $term->selection_beg ([$row, $col])
@@ -216,51 +1149,553 @@
and optionally set them to new values.
+- $term->selection_make ($eventtime[, $rectangular])
+
+ -
+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.
+
+
- $success = $term->selection_grab ($eventtime)
-
-Try to request the primary selection from the server (for example, as set
-by the next method).
+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.
-- $oldtext = $term->selection ([$newtext])
+- $oldtext = $term->selection ([$newtext])
-
Return the current selection text and optionally replace it by
$newtext
.
-- $term->scr_overlay ($x, $y, $text)
+- $term->overlay_simple ($x, $y, $text)
-
Create a simple multi-line overlay box. See the next method for details.
-- $term->scr_overlay_new ($x, $y, $width, $height)
+- $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
-
Create a new (empty) overlay at the given position with the given
-width/height. A border will be put around the box. If either
$x
or
-$y
is negative, then this is counted from the right/bottom side,
-respectively.
+width/height. $rstyle
defines the initial rendition style
+(default: OVERLAY_RSTYLE
).
+
+-
+
If $border
is 2
(default), then a decorative border will be put
+around the box.
+
+-
+
If either $x
or $y
is negative, then this is counted from the
+right/bottom side, respectively.
+
+-
+
This method returns an urxvt::overlay object. The overlay will be visible
+as long as the perl object is referenced.
+
+-
+
The methods currently supported on urxvt::overlay
objects are:
+
+
+- $overlay->set ($x, $y, $text, $rend)
+
+-
+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.
+
+
+- $overlay->hide
+
+-
+If visible, hide the overlay, but do not destroy it.
+
+
+- $overlay->show
+
+-
+If hidden, display the overlay again.
+
+
+- $popup = $term->popup ($event)
+
+-
+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).
+
+
+- $cellwidth = $term->strwidth ($string)
+
+-
+Returns the number of screen-cells this string would need. Correctly
+accounts for wide and combining characters.
+
+
+- $octets = $term->locale_encode ($string)
+
+-
+Convert the given text string into the corresponding locale encoding.
+
+
+- $string = $term->locale_decode ($octets)
+
+-
+Convert the given locale-encoded octets into a perl string.
+
+
+- $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
+
+-
+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.
+
+
+- $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, $rstyle2]])
+
+-
+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.
+
+
+- $term->scr_bell
+
+-
+Ring the bell!
+
+
+- $term->scr_add_lines ($string)
+
+-
+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.
+
+
+- $term->scr_change_screen ($screen)
+
+-
+Switch to given screen - 0 primary, 1 secondary.
+
+
+- $term->cmd_parse ($octets)
+
+-
+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.
+
+
+- $term->tt_write ($octets)
+
+-
+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
.
+
+
+- $old_events = $term->pty_ev_events ([$new_events])
+
+-
+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.
+
+
+- $fd = $term->pty_fd
+
+-
+Returns the master file descriptor for the pty in use, or
-1
if no pty
+is used.
+
+
+- $windowid = $term->parent
+
+-
+Return the window id of the toplevel window.
+
+
+- $windowid = $term->vt
+
+-
+Return the window id of the terminal window.
+
+
+- $term->vt_emask_add ($x_event_mask)
+
+-
+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);
+
+
+- $term->focus_in
+
+- $term->focus_out
+
+- $term->key_press ($state, $keycode[, $time])
+
+- $term->key_release ($state, $keycode[, $time])
+
+-
+Deliver various fake events to to terminal.
+
+
+- $window_width = $term->width
+
+- $window_height = $term->height
+
+- $font_width = $term->fwidth
+
+- $font_height = $term->fheight
+
+- $font_ascent = $term->fbase
+
+- $terminal_rows = $term->nrow
+
+- $terminal_columns = $term->ncol
+
+- $has_focus = $term->focus
+
+- $is_mapped = $term->mapped
+
+- $max_scrollback = $term->saveLines
+
+- $nrow_plus_saveLines = $term->total_rows
+
+- $topmost_scrollback_row = $term->top_row
+
+-
+Return various integers describing terminal characteristics.
+
+
+- $x_display = $term->display_id
+
+-
+Return the DISPLAY used by rxvt-unicode.
+
+
+- $lc_ctype = $term->locale
+
+-
+Returns the LC_CTYPE category string used by this rxvt-unicode.
+
+
+- $env = $term->env
+
+-
+Returns a copy of the environment in effect for the terminal as a hashref
+similar to
\%ENV
.
+
+
+- @envv = $term->envv
+
+-
+Returns the environment as array of strings of the form
VAR=VALUE
.
+
+
+- @argv = $term->argv
+
+-
+Return the argument vector as this terminal, similar to @ARGV, but
+includes the program name as first element.
+
+
+- $modifiermask = $term->ModLevel3Mask
+
+- $modifiermask = $term->ModMetaMask
+
+- $modifiermask = $term->ModNumLockMask
+
+-
+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.
+
+
+- $screen = $term->current_screen
+
+-
+Returns the currently displayed screen (0 primary, 1 secondary).
+
+
+- $cursor_is_hidden = $term->hidden_cursor
+
+-
+Returns wether the cursor is currently hidden or not.
+
+
+- $view_start = $term->view_start ([$newvalue])
+
+-
+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.
+
+
+- $term->want_refresh
+
+-
+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.
+
+-
+
Used after changing terminal contents to display them.
+
+
+- $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
+
+-
+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.
+
+-
+
If $new_text
is specified, it will replace characters in the current
+line, starting at column $start_col
(default 0
), which is useful
+to replace only parts of a line. The font index in the rendition will
+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
(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
+that substr
and similar functions work on screen cells and not on
+characters.
+
+-
+
The methods $term->special_encode
and $term->special_decode
+can be used to convert normal strings into this encoding and vice versa.
-- $term->scr_overlay_off
+- $rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])
-
-Switch the overlay off again.
+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
.
+
+-
+
When setting rendition, the font mask will be ignored.
+
+-
+
See the section on RENDITION, above.
-- $term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE)
+- $length = $term->ROW_l ($row_number[, $new_length])
-
-Put a single character (specified numerically) at the given overlay
-position.
+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.
-- $term->scr_overlay_set ($x, $y, $text)
+- $bool = $term->is_longer ($row_number)
-
-Write a string at the given position into the overlay.
+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)).
+
+
+- $line = $term->line ($row_number)
+
+-
+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:
+
+
+- $text = $line->t ([$new_text])
+
+-
+Returns or replaces the full text of the line, similar to
ROW_t
+
+
+- $rend = $line->r ([$new_rend])
+
+-
+Returns or replaces the full rendition array of the line, similar to
ROW_r
+
+
+- $length = $line->l
+
+-
+Returns the length of the line in cells, similar to
ROW_l
.
+
+
+- $rownum = $line->beg
+
+- $rownum = $line->end
+
+-
+Return the row number of the first/last row of the line, respectively.
+
+
+- $offset = $line->offset_of ($row, $col)
+
+-
+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.
+
+
+- ($row, $col) = $line->coord_of ($offset)
+
+-
+Translates a string offset into terminal coordinates again.
+
+
+- $text = $term->special_encode $string
+
+-
+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.
+
+
+- $string = $term->special_decode $text
+
+-
+Converts rxvt-unicodes text reprsentation into a perl string. See
+
$term->ROW_t
for details.
+
+
+- $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
+
+- $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
+
+-
+Register/unregister a synchronous button grab. See the XGrabButton
+manpage.
+
+
+- $success = $term->grab ($eventtime[, $sync])
+
+-
+Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
+synchronous (
$sync
is true). Also remembers the grab timestampe.
+
+
+- $term->allow_events_async
+
+-
+Calls XAllowEvents with AsyncBoth for the most recent grab.
+
+
+- $term->allow_events_sync
+
+-
+Calls XAllowEvents with SyncBoth for the most recent grab.
+
+
+- $term->allow_events_replay
+
+-
+Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most
+recent grab.
+
+
+- $term->ungrab
+
+-
+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.
+
+
+- $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
+
+- $atom_name = $term->XGetAtomName ($atom)
+
+- @atoms = $term->XListProperties ($window)
+
+- ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
+
+- $term->XChangeWindowProperty ($window, $property, $type, $format, $octets)
+
+- $term->XDeleteProperty ($window, $property)
+
+- $window = $term->DefaultRootWindow
+
+- $term->XReparentWindow ($window, $parent, [$x, $y])
+
+- $term->XMapWindow ($window)
+
+- $term->XUnmapWindow ($window)
+
+- $term->XMoveResizeWindow ($window, $x, $y, $width, $height)
+
+- ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x, $y)
+
+- $term->XChangeInput ($window, $add_events[, $del_events])
+
+-
+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.
+
+
+
+
+
+
+- $popup->add_title ($title)
+
+-
+Adds a non-clickable title to the popup.
+
+
+- $popup->add_separator ([$sepchr])
+
+-
+Creates a separator, optionally using the character given as
$sepchr
.
+
+
+- $popup->add_button ($text, $cb)
+
+-
+Adds a clickable button to the popup.
$cb
is called whenever it is
+selected.
+
+
+- $popup->add_toggle ($text, $initial_value, $cb)
+
+-
+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.
+
+
+- $popup->show
+
+-
+Displays the popup (which is initially hidden).
@@ -269,22 +1704,20 @@
This class implements timer watchers/events. Time is represented as a
fractional number of seconds since the epoch. Example:
- # create a digital clock display in upper right corner
+ $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
$term->{timer} = urxvt::timer
->new
- ->start (urxvt::NOW)
+ ->interval (1)
->cb (sub {
- my ($timer) = @_;
- my $time = $timer->at;
- $timer->start ($time + 1);
- $self->scr_overlay (-1, 0,
- POSIX::strftime "%H:%M:%S", localtime $time);
+ $term->{overlay}->set (0, 0,
+ sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
});
- $timer = new urxvt::timer
-
-Create a new timer object in stopped state.
+Create a new timer object in started state. It is scheduled to fire
+immediately.
- $timer = $timer->cb (sub { my ($timer) = @_; ... })
@@ -299,12 +1732,20 @@
Return the time this watcher will fire next.
-- $timer = $timer->set ($tstamp)
+- $timer = $timer->set ($tstamp)
-
Set the time the event is generated to $tstamp.
+- $timer = $timer->interval ($interval)
+
+-
+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.
+
+
- $timer = $timer->start
-
@@ -317,6 +1758,12 @@
Set the event trigger time to
$tstamp
and start the timer.
+- $timer = $timer->after ($delay)
+
+-
+Like
start
, but sets the expiry timer to c<urxvt::NOW + $delay>.
+
+
- $timer = $timer->stop
-
@@ -332,7 +1779,7 @@
$term->{iow} = urxvt::iow
->new
->fd (fileno $term->{socket})
- ->events (1) # wait for read data
+ ->events (urxvt::EVENT_READ)
->start
->cb (sub {
my ($iow, $revents) = @_;
@@ -363,8 +1810,9 @@
- $iow = $iow->events ($eventmask)
-
-Set the event mask to watch. Bit #0 (value
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
.
- $iow = $iow->start
@@ -381,6 +1829,96 @@
+
+This 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.
+
+- $iw = new urxvt::iw
+
+-
+Create a new idle watcher object in stopped state.
+
+
+- $iw = $iw->cb (sub { my ($iw) = @_; ... })
+
+-
+Set the callback to be called when the watcher triggers.
+
+
+- $timer = $timer->start
+
+-
+Start the watcher.
+
+
+- $timer = $timer->stop
+
+-
+Stop the watcher.
+
+
+
+
+
+This 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) = @_;
+ ...
+ });
+
+- $pw = new urxvt::pw
+
+-
+Create a new process watcher in stopped state.
+
+
+- $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
+
+-
+Set the callback to be called when the timer triggers.
+
+
+- $pw = $timer->start ($pid)
+
+-
+Tells the wqtcher to start watching for process
$pid
.
+
+
+- $pw = $pw->stop
+
+-
+Stop the watcher.
+
+
+
+
+
+
+
+
+
+This variable controls the verbosity level of the perl extension. Higher
+numbers indicate more verbose output.
+
+- == 0 - fatal messages
+
+- >= 3 - script loading and management
+
+- >=10 - all called hooks
+
+- >=11 - hook reutrn values
+
+
+
+