--- rxvt-unicode/doc/rxvtperl.3.txt 2006/01/22 20:39:56 1.35 +++ rxvt-unicode/doc/rxvtperl.3.txt 2006/11/02 17:37:47 1.45 @@ -14,7 +14,7 @@ rxvt --perl-lib $HOME -pe grab_test DESCRIPTION - Everytime a terminal object gets created, extension scripts specified + Every time a terminal object gets created, extension scripts specified via the "perl" resource are loaded and associated with it. Scripts are compiled in a 'use strict' and 'use utf8' environment, and @@ -55,11 +55,18 @@ 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 + be used for the match. For example, the following 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. @@ -74,6 +81,23 @@ 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 @@ -81,11 +105,11 @@ 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. + reference onto "@{ $term-"{selection_popup_hook} }>, which gets + 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 + selection is in $_, which can be used to decide whether 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 @@ -114,9 +138,16 @@ 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 @@ -169,7 +200,7 @@ tabbed This transforms the terminal into a tabbar with additional - terminals, that is, it implements what is commonly refered to as + terminals, that is, it implements what is commonly referred to as "tabbed terminal". The topmost line displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one button per tab. @@ -178,32 +209,106 @@ Shift-Right will switch to the tab left or right of the current one, while Shift-Down creates a new tab. - 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. + 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: + URxvt.tabbed.tabbar-bg: + URxvt.tabbed.tab-fg: + URxvt.tabbed.tab-bg: + + See *COLOR AND GRAPHICS* in the rxvt(1) manpage for valid indices. + + matcher + Uses per-line display filtering ("on_line_update") to underline text + matching a certain pattern and make it clickable. When clicked with + the mouse button specified in the "matcher.button" resource (default + 2, or middle), the program specified in the "matcher.launcher" + resource (default, the "urlLauncher" resource, "sensible-browser") + will be started with the matched text as first argument. The default + configuration is suitable for matching URLs and launching a web + browser, like the former "mark-urls" extension. + + The default pattern to match URLs can be overridden with the + "matcher.pattern.0" resource, and additional patterns can be + specified with numbered patterns, in a manner similar to the + "selection" extension. The launcher can also be overridden on a + per-pattern basis. + + Example configuration: + + URxvt.perl-ext: default,matcher + URxvt.urlLauncher: sensible-browser + URxvt.matcher.button: 1 + URxvt.matcher.pattern.1: \\bwww\\.[\\w-]+\\.[\\w./?&@#-]*[\\w/-] + URxvt.matcher.pattern.2: \\B(/\\S+?):(\\d+)(?=:|$) + URxvt.matcher.launcher.2: gvim +$2 $1 + + 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 + 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 modifiers, 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 - 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: + This is basically a very small 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. Example: 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. + 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. + remote-clipboard + Somewhat of a misnomer, this extension adds two menu entries to the + selection popup that allows one ti run external commands to store + 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 @@ -233,6 +338,16 @@ URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/% + *Note to xrdb users:* xrdb uses the C preprocessor, which might + interpret the double "/" characters as comment start. Use "\057\057" + instead, which works regardless of wether xrdb is used to parse the + resource file or not. + + 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 @@ -264,12 +379,13 @@ locale-specific way. Extension Objects - Very 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. + Every perl extension is a perl class. A separate perl object is created + for each terminal, and each terminal has its own set of extenion + objects, which are passed as the first parameter to hooks. So extensions + can use their $self object without having to think about clashes with + other extensions or other terminals, with the exception of methods and + members that begin with an underscore character "_": these are reserved + for internal use. Although it isn't a "urxvt::term" object, you can call all methods of the "urxvt::term" class on this object. @@ -292,7 +408,7 @@ The following subroutines can be declared in extension files, and will be called whenever the relevant event happens. - The first argument passed to them is an extension oject as described in + The first argument passed to them is an extension object as described in the in the "Extension Objects" section. All of these hooks must return a boolean value. If any of the called @@ -312,12 +428,11 @@ on_start $term Called at the very end of initialisation of a new terminal, just before trying to map (display) the toplevel and returning to the - mainloop. + main loop. on_destroy $term - Called whenever something tries to destroy terminal, before doing - anything yet. If this hook returns true, then destruction is - skipped, but this is rarely a good idea. + Called whenever something tries to destroy terminal, when the + terminal is still fully functional (not for long, though). on_reset $term Called after the screen is "reset" for any reason, such as resizing @@ -346,12 +461,12 @@ queried and changed by calling "$term->selection". Returning a true value aborts selection grabbing. It will still be - hilighted. + highlighted. 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 + operation), or should extend the selection itself and return true to 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 @@ -360,7 +475,7 @@ See the selection example extension. on_view_change $term, $offset - Called whenever the view offset changes, i..e the user or program + Called whenever the view offset changes, i.e. the user or program scrolls. Offset 0 means display the normal terminal, positive values show this many lines of scrollback. @@ -373,7 +488,16 @@ - 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, $string + 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_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 @@ -382,7 +506,7 @@ and this might be enforced in the future. Be careful not ever to trust (in a security sense) the data you - receive, as its source can not easily be controleld (e-mail content, + receive, as its source can not easily be controlled (e-mail content, messages from other users on the same system etc.). on_add_lines $term, $string @@ -419,23 +543,35 @@ on_refresh_end $term Called just after the screen gets redrawn. See "on_refresh_begin". - 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 + on_user_command $term, $string + Called whenever a user-configured event is being activated (e.g. via + a "perl:string" action bound to a key, see description of the 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 calculated, 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. on_focus_out $term - Called wheneever the window loses keyboard focus, before - rxvt-unicode does focus out processing. + Called whenever the window loses keyboard focus, before rxvt-unicode + does focus out processing. on_configure_notify $term, $event on_property_notify $term, $event @@ -483,13 +619,13 @@ object, whenever a callback/hook is executing. @urxvt::TERM_INIT - All coderefs in this array will be called as methods of the next - newly created "urxvt::term" object (during the "on_init" phase). The - array gets cleared before the codereferences that were in it are - being executed, so coderefs can push themselves onto it again if - they so desire. + All code references in this array will be called as methods of the + next newly created "urxvt::term" object (during the "on_init" + phase). The array gets cleared before the code references that were + in it are being executed, so references can push themselves onto it + again if they so desire. - This complements to the perl-eval commandline option, but gets + This complements to the perl-eval command line option, but gets executed first. @urxvt::TERM_EXT @@ -514,6 +650,13 @@ Messages have a size limit of 1023 bytes currently. + @terms = urxvt::termlist + Returns all urxvt::term objects that exist in this process, + regardless of whether 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). @@ -566,6 +709,7 @@ $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. @@ -594,7 +738,8 @@ 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.). @@ -616,8 +761,8 @@ hash %urxvt::OPTION. Options not enabled in this binary are not in the hash. - Here is a a likely non-exhaustive list of option names, please see - the source file /src/optinc.h to see the actual list: + Here is a likely non-exhaustive list of option names, please see the + source file /src/optinc.h to see the actual list: borderLess console cursorBlink cursorUnderline hold iconic insecure intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage @@ -643,7 +788,7 @@ the terminal is destroyed, so changing options frequently will eat memory. - Here is a a likely non-exhaustive list of resource names, not all of + Here is a likely non-exhaustive list of resource names, not all of which are supported in every build, please see the source file /src/rsinc.h to see the actual list: @@ -816,6 +961,12 @@ $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 @@ -840,6 +991,13 @@ 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 @@ -851,7 +1009,7 @@ Returns the currently displayed screen (0 primary, 1 secondary). $cursor_is_hidden = $term->hidden_cursor - Returns wether the cursor is currently hidden or not. + Returns whether the cursor is currently hidden or not. $view_start = $term->view_start ([$newvalue]) Returns the row number of the topmost displayed line. Maximum value @@ -945,15 +1103,18 @@ See "$term->ROW_t" for details. $string = $term->special_decode $text - Converts rxvt-unicodes text reprsentation into a perl string. See + Converts rxvt-unicodes text representation into a perl string. See "$term->ROW_t" for details. - $success = $term->grab_button ($button, $modifiermask) - Registers a synchronous button grab. See the XGrabButton manpage. + $success = $term->grab_button ($button, $modifiermask[, $window = + $term->vt]) + $term->ungrab_button ($button, $modifiermask[, $window = $term->vt]) + 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. + synchronous ($sync is true). Also remembers the grab timestamp. $term->allow_events_async Calls XAllowEvents with AsyncBoth for the most recent grab. @@ -1001,10 +1162,10 @@ Adds a clickable button to the popup. $cb is called whenever it is selected. - $popup->add_toggle ($text, $cb, $initial_value) - Adds a toggle/checkbox item to the popup. Teh callback gets called - whenever it gets toggled, with a boolean indicating its value as its - first argument. + $popup->add_toggle ($text, $initial_value, $cb) + Adds a toggle/checkbox item to the popup. The callback gets called + whenever it gets toggled, with a boolean indicating its new value as + its first argument. $popup->show Displays the popup (which is initially hidden). @@ -1076,7 +1237,7 @@ $reventmask is a bitset as described in the "events" method. $iow = $iow->fd ($fd) - Set the filedescriptor (not handle) to watch. + Set the file descriptor (not handle) to watch. $iow = $iow->events ($eventmask) Set the event mask to watch. The only allowed values are @@ -1087,7 +1248,7 @@ Start watching for requested events on the given handle. $iow = $iow->stop - Stop watching for events on the given filehandle. + Stop watching for events on the given file handle. The "urxvt::iw" Class This class implements idle watchers, that get called automatically when @@ -1127,7 +1288,7 @@ Set the callback to be called when the timer triggers. $pw = $timer->start ($pid) - Tells the wqtcher to start watching for process $pid. + Tells the watcher to start watching for process $pid. $pw = $pw->stop Stop the watcher. @@ -1140,7 +1301,7 @@ == 0 - fatal messages >= 3 - script loading and management >=10 - all called hooks - >=11 - hook reutrn values + >=11 - hook return values AUTHOR Marc Lehmann