--- rxvt-unicode/doc/rxvtperl.3.html 2006/01/20 16:02:20 1.34
+++ rxvt-unicode/doc/rxvtperl.3.html 2006/01/29 21:45:47 1.40
@@ -123,6 +123,16 @@
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.
@@ -152,7 +162,7 @@
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.
+evaluation, web-browser starting etc.), depending on content.
Other extensions can extend this popup menu by pushing a code reference
@@ -197,6 +207,30 @@
selection.
+readline (enabled by default)
+
+
+A support package that tries to make editing with readline easier. At the
+moment, it reacts to clicking with the left mouse button by trying to
+move the text cursor to this position. It does so by generating as many
+cursor-left or cursor-right keypresses as required (the this only works
+for programs that correctly support wide characters).
+
+
+To avoid too many false positives, this is only done when:
+
+
+- - the tty is in ICANON state.
+
+- - the text cursor is visible.
+
+- - the primary screen is currently being displayed.
+
+- - the mouse is on the same (multi-row-) line as the text cursor.
+
+
+The normal selection mechanism isn't disabled, so quick successive clicks
+might interfere with selection creation in harmless ways.
selection-autotransform
@@ -257,8 +291,9 @@
button per tab.
-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.
+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.
mark-urls
@@ -270,6 +305,23 @@
the URL as first argument.
+xim-onthespot
+
+
+This (experimental) perl extension implements OnTheSpot editing. It does
+not work perfectly, and some input methods don't seem to work well with
+OnTheSpot editing in general, but it seems to work at leats for SCIM and
+kinput2.
+
+
+You enable it by specifying this extension and a preedit style of
+OnTheSpot, i.e.:
+
+
+
+ rxvt -pt OnTheSpot -pe xim-onthespot
+
+
automove-background
@@ -296,12 +348,31 @@
Displays a digital clock using the built-in overlay.
-example-refresh-hooks
+remote-clipboard
-Displays a very simple digital clock in the upper right corner of the
-window. Illustrates overwriting the refresh callbacks to create your own
-overlays or changes.
+Somewhat of a misnomer, this extension adds two menu entries to the
+selection popup that allows one ti run external commands to store the
+selection somewhere and fetch it again.
+
+
+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'
selection-pastebin
@@ -345,6 +416,14 @@
URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
+
+example-refresh-hooks
+
+
+Displays a very simple digital clock in the upper right corner of the
+window. Illustrates overwriting the refresh callbacks to create your own
+overlays or changes.
+
@@ -454,9 +533,8 @@
on_destroy $term
-Called whenever something tries to destroy terminal, before doing anything
-yet. If this hook returns true, then destruction is skipped, but this is
-rarely a good idea.
+Called whenever something tries to destroy terminal, when the terminal is
+still fully functional (not for long, though).
on_reset $term
@@ -604,13 +682,17 @@
Called just after the screen gets redrawn. See on_refresh_begin.
-on_keyboard_command $term, $string
+on_user_command $term, $string
-Called whenever the user presses a key combination that has a
-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.
+
on_x_event $term, $event
@@ -636,6 +718,8 @@
on_configure_notify $term, $event
+on_property_notify $term, $event
+
on_key_press $term, $event, $keysym, $octets
on_key_release $term, $event, $keysym
@@ -656,8 +740,8 @@
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.
+manpage), with the additional members 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
@@ -756,6 +840,15 @@
Messages have a size limit of 1023 bytes currently.
+@terms = urxvt::termlist
+
+
+Returns all urxvt::term objects that exist in this process, regardless of
+wether they are started, being destroyed etc., so be careful. Only term
+objects that have perl extensions attached will be returned (because there
+is no urxvt::term objet associated with others).
+
+
$time = urxvt::NOW
@@ -874,7 +967,8 @@
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).
$term->destroy
@@ -1143,6 +1237,12 @@
on_add_lines hook, though.
+$term->scr_change_screen ($screen)
+
+
+Switch to given screen - 0 primary, 1 secondary.
+
+
$term->cmd_parse ($octets)
@@ -1168,6 +1268,13 @@
the previous value.
+$fd = $term->pty_fd
+
+
+Returns the master file descriptor for the pty in use, or -1 if no pty
+is used.
+
+
$windowid = $term->parent
@@ -1249,6 +1356,18 @@
AltGr), the meta key (often Alt) and the num lock key, if applicable.
+$screen = $term->current_screen
+
+
+Returns the currently displayed screen (0 primary, 1 secondary).
+
+
+$cursor_is_hidden = $term->hidden_cursor
+
+
+Returns wether the cursor is currently hidden or not.
+
+
$view_start = $term->view_start ([$newvalue])
@@ -1285,10 +1404,10 @@
$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.
+than one cell when displayed are padded with $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
@@ -1394,10 +1513,13 @@
$term->ROW_t for details.
-$success = $term->grab_button ($button, $modifiermask)
+$success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
+
+$term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
-Registers a synchronous button grab. See the XGrabButton manpage.
+Register/unregister a synchronous button grab. See the XGrabButton
+manpage.
$success = $term->grab ($eventtime[, $sync])
@@ -1433,6 +1555,38 @@
evaluation errors, as it is better to lose the grab in the error case as
the session.
+
+$atom = $term->XInternAtom ($atom_name[, $only_if_exists])
+
+$atom_name = $term->XGetAtomName ($atom)
+
+@atoms = $term->XListProperties ($window)
+
+($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
+
+$term->XChangeWindowProperty ($window, $property, $type, $format, $octets)
+
+$term->XDeleteProperty ($window, $property)
+
+$window = $term->DefaultRootWindow
+
+$term->XReparentWindow ($window, $parent, [$x, $y])
+
+$term->XMapWindow ($window)
+
+$term->XUnmapWindow ($window)
+
+$term->XMoveResizeWindow ($window, $x, $y, $width, $height)
+
+($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x, $y)
+
+$term->XChangeInput ($window, $add_events[, $del_events])
+
+
+Various X or X-related functions. The $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.
+