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

Comparing rxvt-unicode/doc/rxvtperl.3.txt (file contents):
Revision 1.22 by root, Wed Jan 11 02:13:56 2006 UTC vs.
Revision 1.30 by root, Wed Jan 18 09:40:53 2006 UTC

       rxvt -pe <extensionname>
     selection (enabled by default)
         (More) intelligent selection. This extension tries to be more
-        intelligent when the user extends selections (double-click). Right
+        intelligent when the user extends selections (double-click and
-        now, it tries to select urls and complete shell-quoted arguments,
+        further clicks). Right now, it tries to select words, urls and
-        which is very convenient, too, if your ls supports
+        complete shell-quoted arguments, which is very convenient, too, if
-        "--quoting-style=shell".
+        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: \\|([^|]+)\\|
+        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:
         rot13
             Rot-13 the selection when activated. Used via keyboard trigger:
                URxvt.keysym.C-M-r: perl:selection:rot13
         unescaping, perl evalution, web-browser starting etc.), depending on
         content.
     searchable-scrollback<hotkey> (enabled by default)
         Adds regex search functionality to the scrollback buffer, triggered
-        by a hotkey (default: "M-s"). When in search mode, normal terminal
+        by a hotkey (default: "M-s"). While in search mode, normal terminal
-        input/output is suspended.
+        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
+        Inputting characters appends them to the regex and continues
-        "N" jump to the previous match, "G" jumps to the bottom and clears
+        incremental search. "BackSpace" removes a character from the regex,
-        the history, "enter" leaves search mode at the current position and
+        "Up" and "Down" search upwards/downwards in the scrollback buffer,
-        "escape" returns to the original position.
+        "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.
-    digital-clock
+    selection-autotransform
-        Displays a digital clock using the built-in overlay.
+        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///"
+        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+):?$/\\x1b: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+)\\.$/\x1b: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.
     mark-urls
         Uses per-line display filtering ("on_line_update") to underline urls
-        and make them clickable. When clicked, the program specified in the
+        and make them clickable. When middle-clicked, the program specified
-        resource "urlLauncher" (default "x-www-browser") will be started.
+        in the resource "urlLauncher" (default "x-www-browser") will be
+        started with the URL as first argument.
     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 ..
         U+259F) by a similar-looking ascii character.
+    digital-clock
+        Displays a digital clock using the built-in overlay.
     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.
+    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
+        environment as it writes to /tmp directly.).
+        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/%
 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
     on_sel_extend $term
         Called whenever the user tries to extend the selection (e.g. with a
         double click) and is either supposed to return false (normal
         operation), or should extend the selection itelf and return true to
-        suppress the built-in processing.
+        suppress the built-in processing. This can happen multiple times, as
+        long as the callback returns true, it will be called on every
+        further click by the user and is supposed to enlarge the selection
+        more and more, if possible.
         See the selection example extension.
     on_view_change $term, $offset
         Called whenever the view offset changes, i..e the user or program
     on_keyboard_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
         resource in the rxvt(1) manpage).
+    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_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.
-    $is_safe = urxvt::safe
-        Returns true when it is safe to do potentially unsafe things, such
-        as evaluating perl code specified by the user. This is true when
-        urxvt was started setuid or setgid.
     $time = urxvt::NOW
         Returns the "current time" (as per the event loop).
     urxvt::CurrentTime
     urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask,
     Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask,
     Button5Mask, AnyModifier
+    urxvt::NoEventMask, KeyPressMask, KeyReleaseMask, ButtonPressMask,
+    ButtonReleaseMask, EnterWindowMask, LeaveWindowMask, PointerMotionMask,
+    PointerMotionHintMask, Button1MotionMask, Button2MotionMask,
+    Button3MotionMask, Button4MotionMask, Button5MotionMask,
+    ButtonMotionMask, KeymapStateMask, ExposureMask, VisibilityChangeMask,
+    StructureNotifyMask, ResizeRedirectMask, SubstructureNotifyMask,
+    SubstructureRedirectMask, FocusChangeMask, PropertyChangeMask,
+    ColormapChangeMask, OwnerGrabButtonMask
+    urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify,
+    EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose,
+    GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify, DestroyNotify,
+    UnmapNotify, MapNotify, MapRequest, ReparentNotify, ConfigureNotify,
+    ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify,
+    CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest,
+    SelectionNotify, ColormapNotify, ClientMessage, MappingNotify
         Various constants for use in X calls and event processing.
   RENDITION
     Rendition bitsets contain information about colour, font, font styles
     and similar information for each screen cell.
     ($row, $col) = $term->selection_beg ([$row, $col])
     ($row, $col) = $term->selection_end ([$row, $col])
         Return the current values of the selection mark, begin or end
         positions, and optionally set them to new values.
+    $term->selection_make ($eventtime[, $rectangular])
+        Tries to make a selection as set by "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.
     $success = $term->selection_grab ($eventtime)
-        Try to request the primary selection from the server (for example,
+        Try to request the primary selection text from the server (for
-        as set by the next method).
+        example, as set by the next method). No visual feedback will be
+        given. This function is mostly useful from within "on_sel_grab"
+        hooks.
     $oldtext = $term->selection ([$newtext])
         Return the current selection text and optionally replace it by
         $newtext.
     $string = $term->locale_decode ($octets)
         Convert the given locale-encoded octets into a perl string.
     $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
         XORs the rendition values in the given span with the provided value
-        (default: "RS_RVid"). Useful in refresh hooks to provide effects
+        (default: "RS_RVid"), which *MUST NOT* contain font styles. Useful
-        similar to the selection.
+        in refresh hooks to provide effects similar to the selection.
     $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[,
     $rstyle2]])
         Similar to "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.
+        and underlines it instead. Both styles *MUST NOT* contain font
+        styles.
     $term->scr_bell
         Ring the bell!
     $term->scr_add_lines ($string)
     $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);
     $window_width = $term->width
     $window_height = $term->height
     $font_width = $term->fwidth
     $font_height = $term->fheight
     $terminal_columns = $term->ncol
     $has_focus = $term->focus
     $is_mapped = $term->mapped
     $max_scrollback = $term->saveLines
     $nrow_plus_saveLines = $term->total_rows
-    $lines_in_scrollback = $term->nsaved
+    $topmost_scrollback_row = $term->top_row
         Return various integers describing terminal characteristics.
     $x_display = $term->display_id
         Return the DISPLAY used by rxvt-unicode.
         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.
     $view_start = $term->view_start ([$newvalue])
-        Returns the negative row number of the topmost line. Minimum value
+        Returns the row number of the topmost displayed line. Maximum value
-        is 0, which displays the normal terminal contents. Larger values
+        is 0, which displays the normal terminal contents. Lower values
         scroll this many lines into the scrollback buffer.
     $term->want_refresh
         Requests a screen refresh. At the next opportunity, rxvt-unicode
         will compare the on-screen display with its stored representation.
             Return the row number of the first/last row of the line,
             respectively.
         $offset = $line->offset_of ($row, $col)
             Returns the character offset of the given row|col pair within
-            the logical line.
+            the logical line. Works for rows outside the line, too, and
+            returns corresponding offsets outside the string.
         ($row, $col) = $line->coord_of ($offset)
             Translates a string offset into terminal coordinates again.
     $text = $term->special_encode $string
     This variable controls the verbosity level of the perl extension. Higher
     numbers indicate more verbose output.
     == 0 - fatal messages
     >= 3 - script loading and management
-    >=10 - all events received
+    >=10 - all called hooks
+    >=11 - hook reutrn values
 AUTHOR
      Marc Lehmann <pcg@goof.com>
      http://software.schmorp.de/pkg/rxvt-unicode

Diff Legend

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

Comparing rxvt-unicode/doc/rxvtperl.3.txt (file contents): Revision 1.22 by root, Wed Jan 11 02:13:56 2006 UTC vs. Revision 1.30 by root, Wed Jan 18 09:40:53 2006 UTC

Diff Legend

Comparing rxvt-unicode/doc/rxvtperl.3.txt (file contents):
Revision 1.22 by root, Wed Jan 11 02:13:56 2006 UTC vs.
Revision 1.30 by root, Wed Jan 18 09:40:53 2006 UTC