--- rxvt-unicode/doc/rxvtperl.3.txt 2006/01/11 02:13:56 1.22 +++ rxvt-unicode/doc/rxvtperl.3.txt 2006/01/18 09:40:53 1.30 @@ -33,12 +33,33 @@ selection (enabled by default) (More) intelligent selection. This extension tries to be more - intelligent when the user extends selections (double-click). Right - now, it tries to select urls and complete shell-quoted arguments, - which is very convenient, too, if your ls supports - "--quoting-style=shell". + intelligent when the user extends selections (double-click and + further clicks). Right now, it tries to select words, urls and + complete shell-quoted arguments, which is very convenient, too, if + your ls supports "--quoting-style=shell". - It also offers the following bindable keyboard command: + 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. + + This extension also offers following bindable keyboard commands: rot13 Rot-13 the selection when activated. Used via keyboard trigger: @@ -57,32 +78,100 @@ searchable-scrollback (enabled by default) Adds regex search functionality to the scrollback buffer, triggered - by a hotkey (default: "M-s"). When in search mode, normal terminal - input/output is suspended. + by a hotkey (default: "M-s"). While in search mode, normal terminal + 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 - "N" jump to the previous match, "G" jumps to the bottom and clears - the history, "enter" leaves search mode at the current position and - "escape" returns to the original position. + Inputting characters appends them to the regex and continues + incremental search. "BackSpace" removes a character from the regex, + "Up" and "Down" search upwards/downwards in the scrollback buffer, + "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 - Displays a digital clock using the built-in overlay. + 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///" + 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 - resource "urlLauncher" (default "x-www-browser") will be started. + 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. 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 @@ -189,7 +278,10 @@ 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. @@ -258,6 +350,11 @@ "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. @@ -318,11 +415,6 @@ 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). @@ -330,6 +422,21 @@ 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 @@ -474,9 +581,17 @@ 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, - as set by the next method). + Try to request the primary selection text from the server (for + 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 @@ -531,15 +646,16 @@ $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 - similar to the selection. + (default: "RS_RVid"), which *MUST NOT* contain font styles. Useful + 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! @@ -578,6 +694,12 @@ $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 @@ -589,7 +711,7 @@ $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 @@ -610,8 +732,8 @@ applicable. $view_start = $term->view_start ([$newvalue]) - Returns the negative row number of the topmost line. Minimum value - is 0, which displays the normal terminal contents. Larger values + 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. $term->want_refresh @@ -689,7 +811,8 @@ $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. @@ -829,7 +952,8 @@ == 0 - fatal messages >= 3 - script loading and management - >=10 - all events received + >=10 - all called hooks + >=11 - hook reutrn values AUTHOR Marc Lehmann