--- rxvt-unicode/doc/rxvtperl.3.html 2006/01/12 12:10:06 1.26 +++ rxvt-unicode/doc/rxvtperl.3.html 2006/02/06 06:14:55 1.42 @@ -30,6 +30,8 @@
urxvt::popup
Classurxvt::timer
Classurxvt::iow
Classurxvt::iw
Classurxvt::pw
ClassYou can activate them like this:
rxvt -pe <extensionname>+
Or by adding them to the resource for extensions loaded by default:
++ URxvt.perl-ext-common: default,automove-background,selection-autotransform
Another example: Programs I use often output ``absolute path: '' at the +beginning of a line when they process multiple files. The following +pattern matches the filename (note, there is a single space at the very +end):
++ URxvt.selection.pattern-0: ^(/[^:]+):\+
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:
+This extension also offers following bindable keyboard commands:
Other extensions can extend this popup menu by pushing a code reference
+onto @{ $term-
{option_popup_hook} }>, which gets called whenever the
+popup is being displayed.
It's sole argument is the popup menu, which can be modified. It should +either return nothing or a string, the initial boolean value and a code +reference. The string will be used as button text and the code reference +will be called when the toggle changes, with the new boolean value as +first argument.
+The following will add an entry myoption
that changes
+$self-
{myoption}>:
+ push @{ $self->{term}{option_popup_hook} }, sub { + ("my option" => $myoption, sub { $self->{myoption} = $_[0] }) + };+
Other extensions can extend this popup menu by pushing a code reference
+onto @{ $term-
{selection_popup_hook} }>, which gets called whenever the
+popup is being displayed.
It's sole argument is the popup menu, which can be modified. The selection
+is in $_
, which can be used to decide wether to add something or not.
+It should either return nothing or a string and a code reference. The
+string will be used as button text and the code reference will be called
+when the button gets activated and should transform $_
.
The following will add an entry a to b
that transforms all a
s in
+the selection to b
s, but only if the selection currently contains any
+a
s:
+ push @{ $self->{term}{selection_popup_hook} }, sub { + /a/ ? ("a to be" => sub { s/a/b/g } + : () + };
To avoid too many false positives, this is only done when:
+The normal selection mechanism isn't disabled, so quick successive clicks +might interfere with selection creation in harmless ways.
- URxvt.selection-autotransform.0: s/^(\\S+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/+ URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
And this example matches the same,but replaces it with vi-commands you can @@ -199,7 +284,54 @@
- URxvt.selection-autotransform.0: s/^(S+):(d+):?$/\\x1b:e \\Q$1\\E\\x0d:$2\\x0d/+ URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/ +
Of course, this can be modified to suit your needs and your editor :)
+To expand the example above to typical perl error messages (``XXX at +FILENAME line YYY.''), you need a slightly more elaborate solution:
++ URxvt.selection.pattern-0: ( at .*? line \\d+[,.]) + URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/+
The first line tells the selection code to treat the unchanging part of +every error message as a selection pattern, and the second line transforms +the message into vi commands to load the file.
+Clicking a button will activate that tab. Pressing Shift-Left and +Shift-Right will switch to the tab left or right of the current one, +while Shift-Down creates a new tab.
+The tabbar itself can be configured similarly to a normal terminal, but
+with a resource class of URxvt.tabbed
. In addition, it supports the
+following four resources (shown with defaults):
+ URxvt.tabbed.tabbar-fg: <colour-index, default 3> + URxvt.tabbed.tabbar-bg: <colour-index, default 0> + URxvt.tabbed.tab-fg: <colour-index, default 0> + URxvt.tabbed.tab-bg: <colour-index, default 1>+
See COLOR AND GRAPHICS in the rxvt(1)
manpage for valid
+indices.
You enable it by specifying this extension and a preedit style of
+OnTheSpot
, i.e.:
+ rxvt -pt OnTheSpot -pe xim-onthespot+
+ rxvt -pixmap background.xpm -pe automove-background+
We use it to implement a ``distributed selection mechanism'', which just +means that one command uploads the file to a remote server, and another +reads it.
+The commands can be set using the URxvt.remote-selection.store
and
+URxvt.remote-selection.fetch
resources. The first should read the
+selection to store from STDIN (always in UTF-8), the second should provide
+the selection data on STDOUT (also in UTF-8).
The defaults (which are likely useless to you) use rsh and cat:
++ URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection' + URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'+
It listens to the selection-pastebin:remote-pastebin
keyboard command,
+i.e.
+ URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin+
Pressing this combination runs a command with %
replaced by the name of
+the textfile. This command can be set via a resource:
+ URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.+
And the default is likely not useful to anybody but the few people around +here :)
+The name of the textfile is the hex encoded md5 sum of the selection, so +the same content should lead to the same filename.
+After a successful upload the selection will be replaced by the text given
+in the selection-pastebin-url
resource (again, the % is the placeholder
+for the filename):
+ URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%+
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.
+All of these hooks must return a boolean value. If any of the called +hooks returns true, then the event counts as being consumed, and the +relevant action might not be carried out by the C++ code.
When in doubt, return a false value (preferably ()
). >
on_start
hook is a better
+place.
+fork
ed.
+$status
is the status
+from waitpid
.
on_refresh_begin
.
-perl:string
action bound to it (see description of the keysym
+Called whenever the a user-configured event is being activated (e.g. via
+a perl:string
action bound to a key, see description of the keysym
resource in the rxvt(1)
manpage).
The event is simply the action string. This interface is assumed to change +slightly in the future.
+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.
row
and col
, which are the
+(real, not screen-based) row and column under the mouse cursor.
on_key_press
additionally receives the string rxvt-unicode would
@@ -521,6 +788,17 @@
subwindow.
@@ -551,6 +829,27 @@ The current terminal. This variable stores the current
urxvt::term
object, whenever a callback/hook is executing.
+
+urxvt::term
object (during the on_init
phase). The array
+gets cleared before the codereferences that were in it are being executed,
+so coderefs can push themselves onto it again if they so desire.
+This complements to the perl-eval commandline option, but gets executed +first.
+@TERM_INIT
, but contains perl package/class names, which
+get registered as normal extensions after calling the hooks in @TERM_INIT
+but before other extensions. Gets cleared just like @TERM_INIT
.
+@@ -579,12 +878,13 @@
Messages have a size limit of 1023 bytes currently.
-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.
start
hooks will be called before this call returns, and are free to
+refer to global data (which is race free).
fork
/exec
builtins, which executes
+(``starts'') programs in the background. This function takes care of setting
+the user environment before exec'ing the command (e.g. PATH
) and should
+be preferred over explicit calls to exec
or system
.
+Returns the pid of the subprocess or undef
on error.
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+ override-redirect pastableTabs pointerBlank reverseVideo scrollBar + scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput + scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs + transparent tripleclickwords utmpInhibit visualBell
on_add_lines
hook, though.
+-1
if no pty
+is used.
++ $term->vt_emask_add (urxvt::PointerMotionMask);+
0
, which displays the normal terminal contents. Larger values scroll
+Returns the row number of the topmost displayed line. Maximum value is
+0
, which displays the normal terminal contents. Lower values scroll
this many lines into the scrollback buffer.
$row_number
. Row 0
is the topmost terminal line, row $term->$ncol-1
is the bottommost
terminal line. The scrollback buffer starts at line -1
and extends to
-line -$term->nsaved
. Nothing will be returned if a nonexistent line
+line -$term->nsaved
. Nothing will be returned if a nonexistent line
is requested.
$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
-characters in the private use area.
$urxvt::NOCHAR
(chr 65535)
+characters. Characters with combining characters and other characters that
+do not fit into the normal tetx encoding will be replaced with characters
+in the private use area.
You have to obey this encoding when changing text. The advantage is
@@ -1185,10 +1565,13 @@
$term->ROW_t
for details.
$term
object only serves as
+the source of the display, otherwise those functions map more-or-less
+directory onto the X functions of the same name.
+@@ -1248,12 +1663,12 @@ selected. -
$tstamp
and start the timer.
+start
, but sets the expiry timer to c<urxvt::NOW + $delay>.
++
+urxvt::iw
ClassThis class implements idle watchers, that get called automatically when +the process is idle. They should return as fast as possible, after doing +some useful work.
++
+urxvt::pw
ClassThis class implements process watchers. They create an event whenever a +process exits, after which they stop automatically.
++ my $pid = fork; + ... + $term->{pw} = urxvt::pw + ->new + ->start ($pid) + ->cb (sub { + my ($pw, $exit_status) = @_; + ... + });+
$pid
.
+