--- rxvt-unicode/doc/rxvtperl.3.txt 2006/01/11 02:13:56 1.22 +++ rxvt-unicode/doc/rxvtperl.3.txt 2006/01/12 12:15:10 1.25 @@ -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 the following bindable keyboard command: rot13 Rot-13 the selection when activated. Used via keyboard trigger: @@ -57,27 +78,57 @@ 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. + + 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. + + 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/^(\\S+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/ - "/" 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. + And this example matches the same,but replaces it with vi-commands + you can paste directly into your (vi :) editor: - digital-clock - Displays a digital clock using the built-in overlay. + URxvt.selection-autotransform.0: s/^(S+):(d+):?$/\\x1b:e \\Q$1\\E\\x0d:$2\\x0d/ + + Of course, this can be modified to suit your needs and your editor + :) 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 @@ -189,7 +240,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. @@ -474,9 +528,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 +593,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! @@ -689,7 +752,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 +893,8 @@ == 0 - fatal messages >= 3 - script loading and management - >=10 - all events received + >=10 - all called hooks + >=11 - hook reutrn values AUTHOR Marc Lehmann