--- rxvt-unicode/doc/rxvtperl.3.html 2006/01/04 21:37:55 1.13
+++ rxvt-unicode/doc/rxvtperl.3.html 2006/01/10 04:26:54 1.19
@@ -19,11 +19,14 @@
Prepackaged Extensions
General API Considerations
+ Extension Objects
Hooks
Variables in the urxvt
Package
Functions in the urxvt
Package
RENDITION
+ The urxvt::anyevent
Class
The urxvt::term
Class
+ The urxvt::popup
Class
The urxvt::timer
Class
The urxvt::iow
Class
@@ -63,8 +66,8 @@
-Everytime 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
@@ -78,7 +81,7 @@
rxvt -pe <extensionname>
-- selection
+- selection (enabled by default)
-
Intelligent selection. This extension tries to be more intelligent when
@@ -100,12 +103,54 @@
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.
+
+
+selection-popup (enabled by default)
+
+
+Binds a popup menu to Ctrl-Button3 that lets you convert the selection
+text into various other formats/action.
+
+
+searchable-scrollback<hotkey> (enabled by default)
+
+
+Adds regex search functionality to the scrollback buffer, triggered
+by a hotkey (default: M-s
). When in search mode, normal terminal
+input/output is suspended.
+
+
+/
starts an incremental regex search, n
searches further, p
or
+N
jump to the previous match, G
jumps to the bottom and clears the
+history, enter
leaves search mode at the current position and escape
+returns to the original position.
+
+
digital-clock
Displays a digital clock using the built-in overlay.
+mark-urls
+
+
+Uses per-line display filtering (on_line_update
) to underline urls.
+
+
+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.
+
+
example-refresh-hooks
@@ -126,26 +171,85 @@
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
+
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 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 ()
). >
- 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,
+though.
- on_reset $term
@@ -198,20 +302,6 @@
See the selection example extension.
-on_focus_in $term
-
-
-Called whenever the window gets the keyboard focus, before urxvt does
-focus in processing.
-
-
-on_focus_out $term
-
-
-Called wheneever the window loses keyboard focus, before urxvt does focus
-out processing.
-
-
on_view_change $term, $offset
@@ -233,12 +323,6 @@
number of lines that will be in the scrollback buffer.
-on_tty_activity $term *NYI*
-
-
-Called whenever the program(s)
running in the urxvt window send output.
-
-
on_osc_seq $term, $string
@@ -255,6 +339,41 @@
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
@@ -277,6 +396,51 @@
perl:string
action bound to it (see description of the keysym
resource in the rxvt(1)
manpage).
+
+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_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 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.
+
@@ -285,14 +449,24 @@
$urxvt::TERM
-The current terminal. Whenever a callback/Hook is bein executed, this
-variable stores the current urxvt::term
object.
+The current terminal. This variable stores the current urxvt::term
+object, whenever a callback/hook is executing.
+- $term = new urxvt [arg...]
+
+-
+Creates a new terminal, very similar as if you had started it with
+
system $binfile, arg...
. 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 during the call.
+
+
- urxvt::fatal $errormessage
-
@@ -313,11 +487,29 @@
correct place, e.g. on stderr of the connecting urxvtc client.
+- $is_safe = urxvt::safe
+
+-
+Returns true when it is safe to do potentially unsafe things, such as
+evaluating perl code specified by the user. This is true when urxvt was
+started setuid or setgid.
+
+
- $time = urxvt::NOW
-
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
+
+-
+Various constants for use in X calls and event processing.
+
@@ -383,8 +575,43 @@
+
+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 work. 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->destroy
+
+-
+Destroy the terminal object (close the window, free resources etc.).
+
+
+- $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
+ pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating
+ scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer
+ secondaryScreen secondaryScroll skipBuiltinGlyphs transparent
+ tripleclickwords utmpInhibit visualBell
+
+
- $value = $term->resource ($name[, $newval])
-
@@ -408,8 +635,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:
-
@@ -427,11 +654,18 @@
utmpInhibit visualBell
-- $rend = $term->screen_rstyle ([$new_rstyle])
+- $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 thta is output by
-the temrianl application will use this style.
+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])
@@ -464,34 +698,11 @@
-
Return the current selection text and optionally replace it by
$newtext
.
+
+- $term->overlay_simple ($x, $y, $text)
+
-
-
#=item $term->overlay ($x, $y, $text)
-#
-#Create a simple multi-line overlay box. See the next method for details.
-#
-#=cut
-
--
-
sub urxvt::term::scr_overlay {
-die;
- my ($self, $x, $y, $text) = @_;
-
--
-
- my @lines = split /\n/, $text;
-
--
-
- my $w = 0;
- for (map $self->strwidth ($_), @lines) {
- $w = $_ if $w < $_;
- }
-
--
-
- $self->scr_overlay_new ($x, $y, $w, scalar @lines);
- $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
-}
+Create a simple multi-line overlay box. See the next method for details.
- $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
@@ -537,25 +748,78 @@
If hidden, display the overlay again.
-$cellwidth = $term->strwidth $string
+$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
+$octets = $term->locale_encode ($string)
Convert the given text string into the corresponding locale encoding.
-$string = $term->locale_decode $octets
+$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
). 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.
+
+
+$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->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)
@@ -564,6 +828,27 @@
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.
+
+
+$windowid = $term->parent
+
+
+Return the window id of the toplevel window.
+
+
+$windowid = $term->vt
+
+
+Return the window id of the terminal window.
+
+
$window_width = $term->width
$window_height = $term->height
@@ -592,6 +877,29 @@
Return various integers describing terminal characteristics.
+$lc_ctype = $term->locale
+
+
+Returns the LC_CTYPE category string used by this rxvt-unicode.
+
+
+$x_display = $term->display_id
+
+
+Return the DISPLAY used by rxvt-unicode.
+
+
+$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.
+
+
$view_start = $term->view_start ([$newvalue])
@@ -627,7 +935,7 @@
automatically be updated.
-$text
is in a special encoding: tabs and wide characters that use more
+
$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
@@ -639,7 +947,7 @@
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.
@@ -682,16 +990,16 @@
following methods:
-- $text = $line->t
+- $text = $line->t ([$new_text])
-
-Returns the full text of the line, similar to
ROW_t
+Returns or replaces the full text of the line, similar to ROW_t
-- $rend = $line->r
+- $rend = $line->r ([$new_rend])
-
-Returns the full rendition array of the line, similar to
ROW_r
+Returns or replaces the full rendition array of the line, similar to ROW_r
- $length = $line->l
@@ -721,8 +1029,7 @@
Translates a string offset into terminal coordinates again.
-($row, $col) = $line->coord_of ($offset)
-=item $text = $term->special_encode $string
+$text = $term->special_encode $string
Converts a perl string into the special encoding used by rxvt-unicode,
@@ -736,9 +1043,52 @@
Converts rxvt-unicodes text reprsentation into a perl string. See
$term->ROW_t
for details.
+
+$success = $term->grab_button ($button, $modifiermask)
+
+
+Registers 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.
+
+
+
+
This class implements timer watchers/events. Time is represented as a
fractional number of seconds since the epoch. Example:
@@ -812,7 +1162,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) = @_;
@@ -843,8 +1193,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
@@ -869,11 +1220,11 @@
This variable controls the verbosity level of the perl extension. Higher
numbers indicate more verbose output.
-- =0 - only fatal messages
+- == 0 - fatal messages
-- =3 - script loading and management
+- >= 3 - script loading and management
-- =10 - all events received
+- >=10 - all events received