--- rxvt-unicode/doc/rxvtperl.3.txt 2006/01/22 20:39:56 1.35 +++ rxvt-unicode/doc/rxvtperl.3.txt 2006/07/17 19:20:29 1.43 @@ -60,6 +60,13 @@ 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,8 +105,8 @@ 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 @@ -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 @@ -178,32 +209,87 @@ Shift-Right will switch to the tab left or right of the current one, while Shift-Down creates a new tab. + 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. + 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. + 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 modifers, 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. 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. + 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 +319,11 @@ URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/% + 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,7 +355,7 @@ locale-specific way. Extension Objects - Very perl extension is a perl class. A separate perl object is created + Every 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 @@ -315,9 +406,8 @@ mainloop. 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 @@ -373,7 +463,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 @@ -419,16 +518,28 @@ 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 - resource in the rxvt(1) manpage). + on_user_command $term, $string + Called whenever the 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 calculcated, 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. @@ -514,6 +625,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 wether 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 +684,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 +713,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.). @@ -816,6 +936,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 +966,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 @@ -948,8 +1081,11 @@ Converts rxvt-unicodes text reprsentation 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 @@ -1001,10 +1137,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). @@ -1020,7 +1156,7 @@ ->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 @@ -1118,7 +1254,7 @@ ->cb (sub { my ($pw, $exit_status) = @_; ... - }); + }); $pw = new urxvt::pw Create a new process watcher in stopped state.