--- rxvt-unicode/doc/rxvtperl.3.html 2006/01/04 21:37:55 1.13 +++ rxvt-unicode/doc/rxvtperl.3.html 2006/01/10 18:09:22 1.20 @@ -15,15 +15,19 @@
urxvt
Packageurxvt
Packageurxvt::anyevent
Classurxvt::term
Classurxvt::popup
Classurxvt::timer
Classurxvt::iow
ClassEverytime 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 scripts will be shared (but not enabled) for all terminals.
-
This section describes the extensiosn delivered with this version. You can +
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>
--quoting-style=shell
.
+(More) 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:
+It also offers the following bindable keyboard command:
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.
on_line_update
) to underline urls.
++
+
All objects (such as terminals, time watchers etc.) are typical reference-to-hash objects. The hash can be used to store anything you @@ -126,26 +178,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:
++
+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
object associated with this instance of the
+extension. This member must not be changed in any way.
+on_
prefix) for
+this extension, replacing any previous hook. This is useful when you want
+to overwrite time-critical hooks only temporarily.
+
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 ()
). >
See the selection example extension.
-program(s)
running in the urxvt window send output.
-$term->scr_add_lines
yourself. Please note that this
+might be very slow, however, as your hook is called for all text being
+output.
+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.
+perl:string
action bound to it (see description of the keysym
resource in the rxvt(1)
manpage).
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 +456,24 @@
urxvt::term
object.
+The current terminal. This variable stores the current urxvt::term
+object, whenever a callback/hook is executing.
urxvt
Packagesystem $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.
+@@ -383,8 +582,43 @@
+
urxvt::anyevent
ClassThe 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.
+
urxvt::term
Class$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+
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 +661,18 @@ utmpInhibit visualBell
keysym
resource in the rxvt(1)
manpage.
+$newtext
.
#=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.
urxvt::popup
object that implements a popup menu. The
+$event
must be the event causing the menu to pop up (a button event,
+currently).
+RS_RVid
). Useful in refresh hooks to provide effects similar
+to the selection.
+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.
+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.
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->locale_encode
.
urxvt::timer->events
. Make sure to always restore
+the previous value.
+$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 +954,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.
ROW_t
+Returns or replaces the full text of the line, similar to ROW_t
ROW_r
+Returns or replaces the full rendition array of the line, similar to ROW_r
$term->ROW_t
for details.
$sync
is true). Also remembers the grab timestampe.
++
urxvt::popup
Class+
urxvt::timer
ClassThis class implements timer watchers/events. Time is represented as a fractional number of seconds since the epoch. Example:
@@ -812,7 +1169,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 +1200,9 @@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
.
This variable controls the verbosity level of the perl extension. Higher numbers indicate more verbose output.