--- rxvt-unicode/doc/rxvtperl.3.html 2006/01/11 01:01:52 1.23 +++ rxvt-unicode/doc/rxvtperl.3.html 2006/02/21 01:00:40 1.43 @@ -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
--quoting-style=shell
.
+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: \\|([^|]+)\\|+
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.
It 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 } + : () + };
M-s
). When in search mode, normal terminal
-input/output is suspended.
+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.
/
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.
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.
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.
+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/^([^:[:space:]]+):(\\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/^([^:[: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.
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.
+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
.
See the selection example extension.
@@ -396,13 +720,33 @@ Called just after the screen gets redrawn. Seeon_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
@@ -448,6 +796,17 @@
subwindow.
@@ -478,6 +837,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
.
+@@ -506,12 +886,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
$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.
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.
+on_sel_grab
hooks.
RS_RVid
). Useful in refresh hooks to provide effects similar
-to the selection.
+(default: RS_RVid
), which MUST NOT contain font styles. 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.
+it instead. Both styles MUST NOT contain font styles.
on_add_lines
hook, though.
+-1
if no pty
+is used.
++ $term->vt_emask_add (urxvt::PointerMotionMask);+
\%ENV
.
VAR=VALUE
.
+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 @@ -1063,7 +1561,8 @@
$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.
+@@ -1150,12 +1684,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
.
++
@@ -1301,7 +1912,9 @@