--- rxvt-unicode/doc/rxvtperl.3.html 2006/01/08 06:35:38 1.16
+++ rxvt-unicode/doc/rxvtperl.3.html 2006/01/12 12:15:10 1.27
@@ -15,10 +15,12 @@
NAME
SYNOPSIS
DESCRIPTION
+ PREPACKAGED EXTENSIONS
+ API DOCUMENTATION
@@ -83,13 +86,43 @@
selection (enabled by default)
-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.
+(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: \\|([^|]+)\\|
-It also offers the following bindable event:
+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 the following bindable keyboard command:
- rot13
@@ -105,20 +138,80 @@
- option-popup (enabled by default)
-
-Binds a popup menu to Ctrl-Button3 that lets you toggle (some) options at
+Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at
runtime.
-- digital-clock
+- selection-popup (enabled by default)
-
-Displays a digital clock using the built-in overlay.
+Binds a popup menu to Ctrl-Button3 that lets you convert the selection
+text into various other formats/action (such as uri unescaping, perl
+evalution, web-browser starting etc.), depending on content.
+
+
+- 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.
+
+
+- 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/^(\\S+):(\\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/^(S+):(d+):?$/\\x1b:e \\Q$1\\E\\x0d:$2\\x0d/
+
+-
+
Of course, this can be modified to suit your needs and your editor :)
- mark-urls
-
-Uses per-line display filtering (
on_line_update) to underline 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.
- block-graphics-to-ascii
@@ -129,6 +222,12 @@
similar-looking ascii character.
+- digital-clock
+
+ -
+Displays a digital clock using the built-in overlay.
+
+
- example-refresh-hooks
-
@@ -139,6 +238,10 @@
+
+
+
+
All objects (such as terminals, time watchers etc.) are typical
reference-to-hash objects. The hash can be used to store anything you
@@ -156,7 +259,7 @@
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.
+always represents one screen cell. See ROW_t for a discussion of this format.
$string
@@ -176,19 +279,49 @@
+
+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 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. 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.
-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
@@ -244,7 +377,9 @@
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.
@@ -271,12 +406,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
-
@@ -303,6 +432,13 @@
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
-
@@ -358,9 +494,9 @@
focus out processing.
-- on_key_press $term, $event, $octets
+- on_key_press $term, $event, $keysym, $octets
-- on_key_release $term, $event
+- on_key_release $term, $event, $keysym
- on_button_press $term, $event
@@ -393,6 +529,25 @@
+- $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
-
@@ -404,16 +559,6 @@
-- $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
-
@@ -433,6 +578,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.
+
+
+- $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
@@ -489,16 +645,16 @@
Return the foreground/background colour index, respectively.
-- $rend = urxvt::SET_FGCOLOR ($rend, $new_colour)
+- $rend = urxvt::SET_FGCOLOR $rend, $new_colour
-- $rend = urxvt::SET_BGCOLOR ($rend, $new_colour)
+- $rend = urxvt::SET_BGCOLOR $rend, $new_colour
-
Replace the foreground/background colour in the rendition mask with the
specified one.
-- $value = urxvt::GET_CUSTOM ($rend)
+- $value = urxvt::GET_CUSTOM $rend
-
Return the ``custom'' value: Every rendition has 5 bits for use by
@@ -506,7 +662,7 @@
zero.
-- $rend = urxvt::SET_CUSTOM ($rend, $new_value)
+- $rend = urxvt::SET_CUSTOM $rend, $new_value
-
Change the custom value.
@@ -517,17 +673,34 @@
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.
+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 during this call.
+
+
- $term->destroy
-
-Destroy the terminal object (close the window, free resources etc.).
+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.
- $isset = $term->option ($optval[, $set])
@@ -593,6 +766,27 @@
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])
-
@@ -618,11 +812,21 @@
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])
@@ -630,26 +834,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 {
-# 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]])
@@ -722,6 +911,29 @@
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)
-
@@ -752,6 +964,15 @@
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
-
@@ -792,6 +1013,25 @@
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.
+
+
- $modifiermask = $term->ModLevel3Mask
- $modifiermask = $term->ModMetaMask
@@ -850,7 +1090,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.
@@ -923,7 +1163,8 @@
-
Returns the character offset of the given row|col pair within the logical
-line.
+line. Works for rows outside the line, too, and returns corresponding
+offsets outside the string.
- ($row, $col) = $line->coord_of ($offset)
@@ -932,8 +1173,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,
@@ -947,10 +1187,84 @@
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.
+
+
+- $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, $cb, $initial_value)
+
+-
+Adds a toggle/checkbox item to the popup. Teh callback gets called
+whenever it gets toggled, with a boolean indicating its value as its first
+argument.
+
+
+- $popup->show
+
+-
+Displays the popup (which is initially hidden).
+
+
@@ -1026,7 +1340,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) = @_;
@@ -1057,8 +1371,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
@@ -1083,11 +1398,13 @@
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 called hooks
-- =10 - all events received
+- >=11 - hook reutrn values