--- rxvt-unicode/doc/rxvtperl.3.txt 2006/01/20 22:49:34 1.33 +++ rxvt-unicode/doc/rxvtperl.3.txt 2006/02/06 05:55:33 1.39 @@ -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. @@ -114,6 +121,24 @@ stay at the current position and additionally stores the first match in the current line into the primary selection. + 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 + 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 + wide characters). + + To avoid too many false positives, this is only done when: + + - the tty is in ICANON state. + - the text cursor is visible. + - the primary screen is currently being displayed. + - the mouse is on the same (multi-row-) line as the text cursor. + + The normal selection mechanism isn't disabled, so quick successive + clicks might interfere with selection creation in harmless ways. + selection-autotransform This selection allows you to do automatic transforms on a selection whenever a selection is made. @@ -149,20 +174,6 @@ of every error message as a selection pattern, and the second line transforms the message into vi commands to load the file. - readline - A support package that tries to make editing with readline easier. - At the moment, it reacts to clicking with the 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 - wide characters). - - It only works when clicking into the same line (possibly extended - over multiple rows) as the text cursor and on the primary screen, to - reduce the risk of misinterpreting. The normal selection isn't - disabled, so quick successive clicks might interfere with selection - creation in harmless ways. - tabbed This transforms the terminal into a tabbar with additional terminals, that is, it implements what is commonly refered to as @@ -174,12 +185,34 @@ 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 + automove-background This is basically a one-line extension that dynamically changes the background pixmap offset to the window position, in effect creating @@ -196,10 +229,24 @@ 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 @@ -229,6 +276,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 @@ -311,9 +363,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 @@ -415,10 +466,13 @@ 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_x_event $term, $event Called on every X event received on the vt window (and possibly @@ -510,6 +564,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). @@ -562,6 +623,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. @@ -590,7 +652,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.). @@ -796,6 +859,10 @@ See the description of "urxvt::timer->events". Make sure to always restore the previous value. + $fd = $term->pty_fd + Returns the master file descriptor for the pty in use, or -1 if no + pty is used. + $windowid = $term->parent Return the window id of the toplevel window. @@ -808,6 +875,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 @@ -842,6 +915,9 @@ $screen = $term->current_screen Returns the currently displayed screen (0 primary, 1 secondary). + $cursor_is_hidden = $term->hidden_cursor + Returns wether the cursor is currently hidden or not. + $view_start = $term->view_start ([$newvalue]) Returns the row number of the topmost displayed line. Maximum value is 0, which displays the normal terminal contents. Lower values @@ -868,9 +944,9 @@ $text is in a special encoding: tabs and wide characters that use more than one cell when displayed are padded with $urxvt::NOCHAR - characters. Characters with combining characters and other - characters that do not fit into the normal tetx encoding will be - replaced with characters in the private use area. + (chr 65535) characters. Characters with combining characters and + other characters that do not fit into the normal tetx encoding will + be replaced with characters in the private use area. You have to obey this encoding when changing text. The advantage is that "substr" and similar functions work on screen cells and not on @@ -937,8 +1013,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