[ViewVC] Diff of: cvs/rxvt-unicode/doc/rxvtperl.3.txt

Comparing rxvt-unicode/doc/rxvtperl.3.txt (file contents):
Revision 1.32 by root, Fri Jan 20 16:02:20 2006 UTC vs.
Revision 1.38 by root, Sun Jan 29 21:45:47 2006 UTC

         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.
         This extension also offers following bindable keyboard commands:
         options at runtime.
     selection-popup (enabled by default)
         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
+        unescaping, perl evaluation, web-browser starting etc.), depending
-        content.
+        on content.
         Other extensions can extend this popup menu by pushing a code
         reference onto "@{ $term-"{selection_popup_hook} }>, that is called
         whenever the popup is displayed.
         "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.
+    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
         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///"
         "tabbed terminal". The topmost line displays a "[NEW]" button,
         which, when clicked, will add a new tab, followed by one 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.
+        Shift-Right will switch to the tab left or right of the current one,
+        while Shift-Down creates a new tab.
     mark-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.
+    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
         This is basically a one-line extension that dynamically changes the
         background pixmap offset to the window position, in effect creating
         the same effect as pseudo transparency with a custom pixmap. No
         scaling is supported in this mode. Exmaple:
         U+259F) by a similar-looking ascii character.
     digital-clock
         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
+        Somewhat of a misnomer, this extension adds two menu entries to the
-        the window. Illustrates overwriting the refresh callbacks to create
+        selection popup that allows one ti run external commands to store
-        your own overlays or changes.
+        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
         This is a little rarely useful extension that Uploads the selection
         as textfile to a remote site (or does other things). (The
         implementation is not currently secure for use in a multiuser
         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/%
+    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.
 API DOCUMENTATION
   General API Considerations
     All objects (such as terminals, time watchers etc.) are typical
     reference-to-hash objects. The hash can be used to store anything you
         Called at the very end of initialisation of a new terminal, just
         before trying to map (display) the toplevel and returning to the
         mainloop.
     on_destroy $term
-        Called whenever something tries to destroy terminal, before doing
+        Called whenever something tries to destroy terminal, when the
-        anything yet. If this hook returns true, then destruction is
+        terminal is still fully functional (not for long, though).
-        skipped, but this is rarely a good idea.
     on_reset $term
         Called after the screen is "reset" for any reason, such as resizing
         or control sequences. Here is where you can react on changes to
         size-related variables.
         display code is run after this hook, and takes precedence.
     on_refresh_end $term
         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
+        Called whenever the a user-configured event is being activated (e.g.
-        "perl:string" action bound to it (see description of the keysym
+        via a "perl:string" action bound to a key, see description of the
-        resource in the rxvt(1) manpage).
+        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
         Called on every X event received on the vt window (and possibly
         other windows). Should only be used as a last resort. Most event
         structure members are not passed.
     on_focus_out $term
         Called wheneever the window loses keyboard focus, before
         rxvt-unicode does focus out processing.
     on_configure_notify $term, $event
+    on_property_notify $term, $event
     on_key_press $term, $event, $keysym, $octets
     on_key_release $term, $event, $keysym
     on_button_press $term, $event
     on_button_release $term, $event
     on_motion_notify $term, $event
         terminal If the hook returns true, then the even will be ignored by
         rxvt-unicode.
         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.
+        are the (real, not screen-based) 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.
         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.
+    @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
         Returns the "current time" (as per the event loop).
     urxvt::CurrentTime
         %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.
+        "start" hooks will be called before this call returns, and are free
+        to refer to global data (which is race free).
     $term->destroy
         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.
         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.
+    $term->scr_change_screen ($screen)
+        Switch to given screen - 0 primary, 1 secondary.
     $term->cmd_parse ($octets)
         Similar to "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.
     $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.
+    $fd = $term->pty_fd
+        Returns the master file descriptor for the pty in use, or -1 if no
+        pty is used.
     $windowid = $term->parent
         Return the window id of the toplevel window.
     $windowid = $term->vt
     $modifiermask = $term->ModNumLockMask
         Return the modifier masks corresponding to the "ISO Level 3 Shift"
         (often 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])
         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.
         line, starting at column $start_col (default 0), which is useful to
         replace only parts of a line. The font index in the rendition will
         automatically be updated.
         $text is in a special encoding: tabs and wide characters that use
-        more than one cell when displayed are padded with urxvt::NOCHAR
+        more than one cell when displayed are padded with $urxvt::NOCHAR
-        characters ("chr 65535"). Characters with combining characters and
+        (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
         that "substr" and similar functions work on screen cells and not on
     $string = $term->special_decode $text
         Converts rxvt-unicodes text reprsentation into a perl string. See
         "$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])
         Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
         synchronous ($sync is true). Also remembers the grab timestampe.
     $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.
+    $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.
   The "urxvt::popup" Class
     $popup->add_title ($title)
         Adds a non-clickable title to the popup.

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing rxvt-unicode/doc/rxvtperl.3.txt (file contents): Revision 1.32 by root, Fri Jan 20 16:02:20 2006 UTC vs. Revision 1.38 by root, Sun Jan 29 21:45:47 2006 UTC

Diff Legend

Comparing rxvt-unicode/doc/rxvtperl.3.txt (file contents):
Revision 1.32 by root, Fri Jan 20 16:02:20 2006 UTC vs.
Revision 1.38 by root, Sun Jan 29 21:45:47 2006 UTC