--- rxvt-unicode/doc/rxvtperl.3.html 2006/01/04 21:37:55 1.13
+++ rxvt-unicode/doc/rxvtperl.3.html 2006/01/08 00:20:12 1.15
@@ -24,6 +24,7 @@
Functions in the urxvt Package
RENDITION
The urxvt::term Class
+ The urxvt::popup Class
The urxvt::timer Class
The urxvt::iow Class
@@ -63,8 +64,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
@@ -106,6 +107,20 @@
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,16 +141,42 @@
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.
+
+
-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
+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.
+member. It is, however, blessed intot he package of the extension script,
+so for all practical purposes you can treat an extension script as a class.
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.
@@ -145,7 +186,10 @@
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 +242,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
@@ -255,6 +285,34 @@
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_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 +335,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, $octets
+
+on_key_release $term, $event
+
+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 +388,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
-
@@ -318,6 +431,16 @@
-
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 events.
+
@@ -385,6 +508,33 @@
+- $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 +558,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 +577,11 @@
utmpInhibit visualBell
-- $rend = $term->screen_rstyle ([$new_rstyle])
+- $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])
@@ -469,29 +619,21 @@
#
#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;
-}
+#=cut
+#
+#sub urxvt::term::scr_overlay {
+# 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;
+#}
- $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
@@ -537,25 +679,55 @@
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_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 +736,18 @@
to the locale-specific encoding using $term->locale_encode.
+$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 +776,17 @@
Return various integers describing terminal characteristics.
+$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 +822,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
@@ -682,16 +877,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
@@ -739,6 +934,9 @@
+
+
+
This class implements timer watchers/events. Time is represented as a
fractional number of seconds since the epoch. Example: