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

Comparing rxvt-unicode/doc/rxvtperl.3.txt (file contents):
Revision 1.35 by root, Sun Jan 22 20:39:56 2006 UTC vs.
Revision 1.43 by root, Mon Jul 17 19:20:29 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:
                URxvt.keysym.C-M-r: perl:selection:rot13
     option-popup (enabled by default)
         Binds a popup menu to Ctrl-Button2 that lets you toggle (some)
         options at runtime.
+        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] })
+           };
     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 evaluation, web-browser starting etc.), depending
         on content.
         Other extensions can extend this popup menu by pushing a code
-        reference onto "@{ $term-"{selection_popup_hook} }>, that is called
+        reference onto "@{ $term-"{selection_popup_hook} }>, which gets
-        whenever the popup is displayed.
+        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
         "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.
+        The regex defaults to "(?i)", resulting in a case-insensitive
+        search. To get a case-sensitive search you can delete this prefix
+        using "BackSpace" or simply use an uppercase character which removes
+        the "(?i)" prefix.
+        See perlre for more info about perl regular expression syntax.
     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
+        At the moment, it reacts to clicking shift-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).
         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
+    kuake<hotkey>
+        A very primitive quake-console-like extension. It was inspired by a
+        description of how the programs "kuake" and "yakuake" work: Whenever
+        the user presses a global accelerator key (by default "F10"), the
+        terminal will show or hide itself. Another press of the accelerator
+        key will hide or show it again.
+        Initially, the window will not be shown when using this extension.
+        This is useful if you need a single terminal thats not using any
+        desktop space most of the time but is quickly available at the press
+        of a key.
+        The accelerator key is grabbed regardless of any modifers, so this
+        extension will actually grab a physical key just for this function.
+        If you want a quake-like animation, tell your window manager to do
+        so (fvwm can do it).
     automove-background
-        This is basically a one-line extension that dynamically changes the
+        This is basically a very small extension that dynamically changes
-        background pixmap offset to the window position, in effect creating
+        the background pixmap offset to the window position, in effect
-        the same effect as pseudo transparency with a custom pixmap. No
+        creating the same effect as pseudo transparency with a custom
-        scaling is supported in this mode. Exmaple:
+        pixmap. No scaling is supported in this mode. Exmaple:
            rxvt -pixmap background.xpm -pe automove-background
     block-graphics-to-ascii
         A not very useful example of filtering all text output to the
-        terminal, by replacing all line-drawing characters (U+2500 ..
+        terminal by replacing all line-drawing characters (U+2500 .. U+259F)
-        U+259F) by a similar-looking ascii character.
+        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
     $octets
         Either binary data or - more common - a text string encoded in a
         locale-specific way.
   Extension Objects
-    Very perl extension is a perl class. A separate perl object is created
+    Every perl extension is a perl class. A separate perl object is created
     for each terminal and each extension and passed as the first parameter
     to hooks. So extensions can use their $self object without having to
     think about other extensions, with the exception of methods and members
     that begin with an underscore character "_": these are reserved for
     internal use.
         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.
         It is called before lines are scrolled out (so rows 0 .. min ($lines
         - 1, $nrow - 1) represent the lines to be scrolled out). $saved is
         the total number of lines that will be in the scrollback buffer.
+    on_osc_seq $term, $op, $args
+        Called on every OSC sequence and can be used to suppress it or
+        modify its behaviour. The default should be to return an empty list.
+        A true value suppresses execution of the request completely. Make
+        sure you don't get confused by recursive invocations when you output
+        an osc sequence within this callback.
+        "on_osc_seq_perl" should be used for new behaviour.
-    on_osc_seq $term, $string
+    on_osc_seq_perl $term, $string
         Called whenever the ESC ] 777 ; string ST command sequence (OSC =
         operating system command) is processed. Cursor position and other
         state information is up-to-date when this happens. For
         interoperability, the string should start with the extension name
         and a colon, to distinguish it from commands for other extensions,
         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_resize_all_windows $tern, $new_width, $new_height
+        Called just after the new window size has been calculcated, but
+        before windows are actually being resized or hints are being set. If
+        this hook returns TRUE, setting of the window hints is being
+        skipped.
     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_root_event $term, $event
+        Like "on_x_event", but is called for events on the root window.
     on_focus_in $term
         Called whenever the window gets the keyboard focus, before
         rxvt-unicode does focus in processing.
         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.
         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
     $font_ascent = $term->fbase
     $env = $term->env
         Returns a copy of the environment in effect for the terminal as a
         hashref similar to "\%ENV".
+    @envv = $term->envv
+        Returns the environment as array of strings of the form "VAR=VALUE".
+    @argv = $term->argv
+        Return the argument vector as this terminal, similar to @ARGV, but
+        includes the program name as first element.
     $modifiermask = $term->ModLevel3Mask
     $modifiermask = $term->ModMetaMask
     $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
     $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.
     $popup->add_button ($text, $cb)
         Adds a clickable button to the popup. $cb is called whenever it is
         selected.
-    $popup->add_toggle ($text, $cb, $initial_value)
+    $popup->add_toggle ($text, $initial_value, $cb)
-        Adds a toggle/checkbox item to the popup. Teh callback gets called
+        Adds a toggle/checkbox item to the popup. The callback gets called
-        whenever it gets toggled, with a boolean indicating its value as its
+        whenever it gets toggled, with a boolean indicating its new value as
-        first argument.
+        its first argument.
     $popup->show
         Displays the popup (which is initially hidden).
   The "urxvt::timer" Class
                         ->new
                         ->interval (1)
                         ->cb (sub {
                            $term->{overlay}->set (0, 0,
                               sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
                         });
     $timer = new urxvt::timer
         Create a new timer object in started state. It is scheduled to fire
         immediately.
                         ->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) = @_; ... })

Diff Legend

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

Comparing rxvt-unicode/doc/rxvtperl.3.txt (file contents): Revision 1.35 by root, Sun Jan 22 20:39:56 2006 UTC vs. Revision 1.43 by root, Mon Jul 17 19:20:29 2006 UTC

Diff Legend

Comparing rxvt-unicode/doc/rxvtperl.3.txt (file contents):
Revision 1.35 by root, Sun Jan 22 20:39:56 2006 UTC vs.
Revision 1.43 by root, Mon Jul 17 19:20:29 2006 UTC