--- rxvt-unicode/doc/rxvtperl.3.txt 2006/01/10 19:46:28 1.19 +++ rxvt-unicode/doc/rxvtperl.3.txt 2006/01/19 19:26:31 1.31 @@ -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: @@ -55,33 +76,130 @@ unescaping, perl evalution, 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 + whenever the popup is 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 + reference will be called when the button gets activated and should + transform $_. + + The following will add an entry "a to b" that transforms all "a"s in + the selection to "b"s, but only if the selection currently contains + any "a"s: + + push @{ $self->{term}{selection_popup_hook} }, sub { + /a/ ? ("a to be" => sub { s/a/b/g } + : () + }; + 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+):?$/: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+)[,.]$/: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. + 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. + + 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: + + 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 .. 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 @@ -100,7 +218,7 @@ $text Rxvt-unicodes special way of encoding text, where one "unicode" - character always represents one screen cell. See row_t for a + character always represents one screen cell. See ROW_t for a discussion of this format. $string @@ -167,6 +285,13 @@ 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 + Called just after the child process has exited. $status is the + status from "waitpid". + on_sel_make $term, $eventtime Called whenever a selection has been made by the user, but before the selection text is copied, so changes to the beginning, end or @@ -188,7 +313,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. @@ -257,6 +385,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. @@ -265,6 +398,7 @@ Called wheneever the window loses keyboard focus, before rxvt-unicode does focus out processing. + on_configure_notify $term, $event on_key_press $term, $event, $keysym, $octets on_key_release $term, $event, $keysym on_button_press $term, $event @@ -301,17 +435,7 @@ The current terminal. This variable stores the current "urxvt::term" object, whenever a callback/hook is executing. - * - Functions in the "urxvt" Package - $term = new urxvt [arg...] - Creates a new terminal, very similar as if you had started it with - "system $binfile, arg...". 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 the - call. - 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 @@ -325,10 +449,7 @@ Using this function has the advantage that its output ends up in the correct place, e.g. on stderr of the connecting urxvtc client. - $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. + Messages have a size limit of 1023 bytes currently. $time = urxvt::NOW Returns the "current time" (as per the event loop). @@ -337,6 +458,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 @@ -387,11 +523,30 @@ should work. The "urxvt::term" Class + $term = new urxvt::term $envhashref, $rxvtname, [arg...] + Creates a new terminal, very similar as if you had started it with + system "$rxvtname, arg...". $envhashref must be a reference to a + %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. + $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. + $term->exec_async ($cmd[, @args]) + Works like the combination of the "fork"/"exec" builtins, which + executes ("starts") programs in the background. This function takes + care of setting the user environment before exec'ing the command + (e.g. "PATH") and should be preferred over explicit calls to "exec" + or "system". + + Returns the pid of the subprocess or "undef" on error. + $isset = $term->option ($optval[, $set]) Returns true if the option specified by $optval is enabled, and optionally change it. All option values are stored by name in the @@ -403,10 +558,10 @@ borderLess console cursorBlink cursorUnderline hold iconic insecure intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage - pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating - scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer - secondaryScreen secondaryScroll skipBuiltinGlyphs transparent - tripleclickwords utmpInhibit visualBell + override-redirect pastableTabs pointerBlank reverseVideo scrollBar + scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput + scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs + transparent tripleclickwords utmpInhibit visualBell $value = $term->resource ($name[, $newval]) Returns the current resource value associated with a given name and @@ -433,14 +588,25 @@ borderLess color cursorBlink cursorUnderline cutchars delete_key display_name embed ext_bwidth fade font geometry hold iconName imFont imLocale inputMethod insecure int_bwidth intensityStyles - italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier - mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2 - perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd - reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating - scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput - scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle - shade term_name title transparent transparent_all tripleclickwords - utmpInhibit visualBell + italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier + mouseWheelScrollPage name override_redirect pastableTabs path perl_eval + perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay + preeditType print_pipe pty_fd reverseVideo saveLines scrollBar + scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness + scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle + secondaryScreen secondaryScroll selectstyle shade term_name title + transient_for transparent transparent_all tripleclickwords utmpInhibit + visualBell + + $value = $term->x_resource ($pattern) + Returns the X-Resource for the given pattern, excluding the program + or class name, i.e. "$term->x_resource ("boldFont")" should return + the same value as used by this instance of rxvt-unicode. Returns + "undef" if no resource with that pattern exists. + + This method should only be called during the "on_start" hook, as + there is only one resource database per display, and later + invocations might return the wrong resources. $success = $term->parse_keysym ($keysym_spec, $command_string) Adds a keymap translation exactly as specified via a resource. See @@ -461,9 +627,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 @@ -518,15 +692,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! @@ -565,6 +740,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 @@ -576,14 +757,18 @@ $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. + $lc_ctype = $term->locale Returns the LC_CTYPE category string used by this rxvt-unicode. - $x_display = $term->display_id - Return the DISPLAY used by rxvt-unicode. + $env = $term->env + Returns a copy of the environment in effect for the terminal as a + hashref similar to "\%ENV". $modifiermask = $term->ModLevel3Mask $modifiermask = $term->ModMetaMask @@ -593,8 +778,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 @@ -672,7 +857,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. @@ -729,92 +915,96 @@ Displays the popup (which is initially hidden). The "urxvt::timer" Class - This class implements timer watchers/events. Time is represented as - a fractional number of seconds since the epoch. Example: + This class implements timer watchers/events. Time is represented as a + fractional number of seconds since the epoch. Example: - $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0); - $term->{timer} = urxvt::timer - ->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. - - $timer = $timer->cb (sub { my ($timer) = @_; ... }) - Set the callback to be called when the timer triggers. - - $tstamp = $timer->at - Return the time this watcher will fire next. - - $timer = $timer->set ($tstamp) - Set the time the event is generated to $tstamp. - - $timer = $timer->interval ($interval) - Normally (and when $interval is 0), the timer will automatically - stop after it has fired once. If $interval is non-zero, then the - timer is automatically rescheduled at the given intervals. + $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0); + $term->{timer} = urxvt::timer + ->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. + + $timer = $timer->cb (sub { my ($timer) = @_; ... }) + Set the callback to be called when the timer triggers. + + $tstamp = $timer->at + Return the time this watcher will fire next. + + $timer = $timer->set ($tstamp) + Set the time the event is generated to $tstamp. + + $timer = $timer->interval ($interval) + Normally (and when $interval is 0), the timer will automatically + stop after it has fired once. If $interval is non-zero, then the + timer is automatically rescheduled at the given intervals. + + $timer = $timer->start + Start the timer. - $timer = $timer->start - Start the timer. + $timer = $timer->start ($tstamp) + Set the event trigger time to $tstamp and start the timer. - $timer = $timer->start ($tstamp) - Set the event trigger time to $tstamp and start the timer. + $timer = $timer->after ($delay) + Like "start", but sets the expiry timer to c. - $timer = $timer->stop - Stop the timer. + $timer = $timer->stop + Stop the timer. The "urxvt::iow" Class - This class implements io watchers/events. Example: + This class implements io watchers/events. Example: - $term->{socket} = ... - $term->{iow} = urxvt::iow - ->new - ->fd (fileno $term->{socket}) - ->events (urxvt::EVENT_READ) - ->start - ->cb (sub { - my ($iow, $revents) = @_; - # $revents must be 1 here, no need to check - sysread $term->{socket}, my $buf, 8192 - or end-of-file; - }); - - $iow = new urxvt::iow - Create a new io watcher object in stopped state. - - $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... }) - Set the callback to be called when io events are triggered. - $reventmask is a bitset as described in the "events" method. - - $iow = $iow->fd ($fd) - Set the filedescriptor (not handle) to watch. - - $iow = $iow->events ($eventmask) - Set the event mask to watch. The only allowed values are - "urxvt::EVENT_READ" and "urxvt::EVENT_WRITE", which might be - ORed together, or "urxvt::EVENT_NONE". + $term->{socket} = ... + $term->{iow} = urxvt::iow + ->new + ->fd (fileno $term->{socket}) + ->events (urxvt::EVENT_READ) + ->start + ->cb (sub { + my ($iow, $revents) = @_; + # $revents must be 1 here, no need to check + sysread $term->{socket}, my $buf, 8192 + or end-of-file; + }); + + $iow = new urxvt::iow + Create a new io watcher object in stopped state. + + $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... }) + Set the callback to be called when io events are triggered. + $reventmask is a bitset as described in the "events" method. + + $iow = $iow->fd ($fd) + Set the filedescriptor (not handle) to watch. + + $iow = $iow->events ($eventmask) + Set the event mask to watch. The only allowed values are + "urxvt::EVENT_READ" and "urxvt::EVENT_WRITE", which might be ORed + together, or "urxvt::EVENT_NONE". - $iow = $iow->start - Start watching for requested events on the given handle. + $iow = $iow->start + Start watching for requested events on the given handle. - $iow = $iow->stop - Stop watching for events on the given filehandle. + $iow = $iow->stop + Stop watching for events on the given filehandle. ENVIRONMENT URXVT_PERL_VERBOSITY - This variable controls the verbosity level of the perl extension. - Higher numbers indicate more verbose output. + 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 + == 0 - fatal messages + >= 3 - script loading and management + >=10 - all called hooks + >=11 - hook reutrn values AUTHOR - Marc Lehmann - http://software.schmorp.de/pkg/rxvt-unicode + Marc Lehmann + http://software.schmorp.de/pkg/rxvt-unicode