--- rxvt-unicode/doc/rxvtperl.3.html 2006/01/03 21:15:22 1.9
+++ rxvt-unicode/doc/rxvtperl.3.html 2006/01/07 04:19:43 1.14
@@ -81,8 +81,10 @@
selection
-Intelligent selection. This etxension tries to be more intelligent when the user
-extends selections (double-click).
+Intelligent selection. This extension tries to be more intelligent when
+the user extends selections (double-click). Right now, it tries to select
+urls and complete shell-quoted arguments, which is very convenient, too,
+if your ls supports --quoting-style=shell.
It also offers the following bindable event:
@@ -104,6 +106,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
@@ -124,10 +140,35 @@
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
@@ -143,7 +184,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
@@ -237,6 +281,50 @@
Called whenever the program(s) running in the urxvt window send output.
+on_osc_seq $term, $string
+
+
+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_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
@@ -259,6 +347,33 @@
perl:string action bound to it (see description of the keysym
resource in the rxvt(1) manpage).
+
+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
+
+
+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.
+
@@ -267,14 +382,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
-
@@ -367,6 +492,12 @@
+- $term->destroy
+
+-
+Destroy the terminal object (close the window, free resources etc.).
+
+
- $value = $term->resource ($name[, $newval])
-
@@ -400,7 +531,7 @@
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
+ mouseWheelScrollPage name 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
@@ -409,6 +540,20 @@
utmpInhibit visualBell
+- $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])
@@ -437,29 +582,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]])
@@ -505,25 +642,47 @@
If hidden, display the overlay again.
-$cellwidth = $term->strwidth $string
+$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)
@@ -532,19 +691,44 @@
to the locale-specific encoding using $term->locale_encode.
-$nrow = $term->nrow
+$windowid = $term->parent
-$ncol = $term->ncol
+
+Return the window id of the toplevel window.
+
+
+$windowid = $term->vt
-Return the number of rows/columns of the terminal window (i.e. as
-specified by -geometry, excluding any scrollback).
+Return the window id of the terminal window.
-$nsaved = $term->nsaved
+$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
+
+$lines_in_scrollback = $term->nsaved
-Returns the number of lines in the scrollback buffer.
+Return various integers describing terminal characteristics.
$view_start = $term->view_start ([$newvalue])
@@ -582,7 +766,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
@@ -637,16 +821,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
@@ -823,14 +1007,14 @@
This variable controls the verbosity level of the perl extension. Higher
numbers indicate more verbose output.
-
-- - only fatal messages
-
-- - script loading and management
-
-- - all events received
-
-
+
+- =0 - only fatal messages
+
+- =3 - script loading and management
+
+- =10 - all events received
+
+