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

Comparing rxvt-unicode/doc/rxvtperl.3.txt (file contents):
Revision 1.31 by root, Thu Jan 19 19:26:31 2006 UTC vs.
Revision 1.39 by root, Mon Feb 6 05:55:33 2006 UTC

     can find them in /opt/rxvt/lib/urxvt/perl/.
     You 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
     selection (enabled by default)
         (More) intelligent selection. This extension tries to be more
         intelligent when the user extends selections (double-click and
         further clicks). Right now, it tries to select words, urls and
         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///"
            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.
+    tabbed
+        This transforms the terminal into a tabbar with additional
+        terminals, that is, it implements what is commonly refered to as
+        "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,
+        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.
     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
     be called whenever the relevant event happens.
     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
+    All of these hooks must return a boolean value. If any of the called
-    event counts as being *consumed*, and the invocation of other hooks is
+    hooks returns true, then the event counts as being *consumed*, and the
-    skipped, and the relevant action might not be carried out by the C++
+    relevant action might not be carried out by the C++ code.
-    code.
     *When in doubt, return a false value (preferably "()").*
     on_init $term
         Called after a new terminal object has been initialized, but before
         windows are created or the command gets run. Most methods are unsafe
         to call or deliver senseless data, as terminal size and other
         characteristics have not yet been determined. You can safely query
-        and change resources, though.
+        and change resources and options, though. For many purposes the
+        "on_start" hook is a better place.
+    on_start $term
+        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, when the
+        terminal is still fully functional (not for long, though).
     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.
-    on_start $term
-        Called at the very end of initialisation of a new terminal, just
-        before returning to the mainloop.
     on_child_start $term, $pid
         Called just after the child process has been "fork"ed.
     on_child_exit $term, $status
         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.
+    on_client_message $term, $event
+    on_wm_protocols $term, $event
+    on_wm_delete_window $term, $event
+        Called when various types of ClientMessage events are received (all
+        with format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
   Variables in the "urxvt" Package
     $urxvt::LIBDIR
         The rxvt-unicode library directory, where, among other things, the
         perl modules and scripts are stored.
         The basename of the installed binaries, usually "urxvt".
     $urxvt::TERM
         The current terminal. This variable stores the current "urxvt::term"
         object, whenever a callback/hook is executing.
+    @urxvt::TERM_INIT
+        All coderefs in this array will be called as methods of the next
+        newly created "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.
+    @urxvt::TERM_EXT
+        Works similar to @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.
   Functions in the "urxvt" Package
     urxvt::fatal $errormessage
         Fatally aborts execution with the given error message. Avoid at all
         costs! The only time this is acceptable is when the terminal process
         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
     $background = urxvt::GET_BASEBG $rend
         Return the foreground/background colour index, respectively.
     $rend = urxvt::SET_FGCOLOR $rend, $new_colour
     $rend = urxvt::SET_BGCOLOR $rend, $new_colour
+    $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
         Replace the foreground/background colour in the rendition mask with
         the specified one.
     $value = urxvt::GET_CUSTOM $rend
         Return the "custom" value: Every rendition has 5 bits for use by
         %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.
         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
         Return the window id of the terminal window.
     $term->vt_emask_add ($x_event_mask)
         Adds the specified events to the vt event mask. Useful e.g. when you
         want to receive pointer events all the times:
            $term->vt_emask_add (urxvt::PointerMotionMask);
+    $term->focus_in
+    $term->focus_out
+    $term->key_press ($state, $keycode[, $time])
+    $term->key_release ($state, $keycode[, $time])
+        Deliver various fake events to to terminal.
     $window_width = $term->width
     $window_height = $term->height
     $font_width = $term->fwidth
     $font_height = $term->fheight
     $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.
         Start watching for requested events on the given handle.
     $iow = $iow->stop
         Stop watching for events on the given filehandle.
+  The "urxvt::iw" Class
+    This 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.
+    $iw = new urxvt::iw
+        Create a new idle watcher object in stopped state.
+    $iw = $iw->cb (sub { my ($iw) = @_; ... })
+        Set the callback to be called when the watcher triggers.
+    $timer = $timer->start
+        Start the watcher.
+    $timer = $timer->stop
+        Stop the watcher.
+  The "urxvt::pw" Class
+    This 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) = @_;
+                           ...
+                        });
+    $pw = new urxvt::pw
+        Create a new process watcher in stopped state.
+    $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
+        Set the callback to be called when the timer triggers.
+    $pw = $timer->start ($pid)
+        Tells the wqtcher to start watching for process $pid.
+    $pw = $pw->stop
+        Stop the watcher.
 ENVIRONMENT
   URXVT_PERL_VERBOSITY
     This variable controls the verbosity level of the perl extension. Higher
     numbers indicate more verbose output.

Diff Legend

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

Comparing rxvt-unicode/doc/rxvtperl.3.txt (file contents): Revision 1.31 by root, Thu Jan 19 19:26:31 2006 UTC vs. Revision 1.39 by root, Mon Feb 6 05:55:33 2006 UTC

Diff Legend

Comparing rxvt-unicode/doc/rxvtperl.3.txt (file contents):
Revision 1.31 by root, Thu Jan 19 19:26:31 2006 UTC vs.
Revision 1.39 by root, Mon Feb 6 05:55:33 2006 UTC