ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/rxvt-unicode/src/urxvt.pm
(Generate patch)

Comparing rxvt-unicode/src/urxvt.pm (file contents):
Revision 1.140 by root, Mon Jul 3 19:10:09 2006 UTC vs.
Revision 1.144 by root, Mon Aug 7 15:59:44 2006 UTC

… …
17 17
18 @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test 18 @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test
19 19
20=head1 DESCRIPTION 20=head1 DESCRIPTION
21 21
22Everytime a terminal object gets created, extension scripts specified via 22Every time a terminal object gets created, extension scripts specified via
23the C<perl> resource are loaded and associated with it. 23the C<perl> resource are loaded and associated with it.
24 24
25Scripts are compiled in a 'use strict' and 'use utf8' environment, and 25Scripts are compiled in a 'use strict' and 'use utf8' environment, and
26thus must be encoded as UTF-8. 26thus must be encoded as UTF-8.
27 27
… …
62 URxvt.selection.pattern-1: perl-regex 62 URxvt.selection.pattern-1: perl-regex
63 ... 63 ...
64 64
65The index number (0, 1...) must not have any holes, and each regex must 65The index number (0, 1...) must not have any holes, and each regex must
66contain at least one pair of capturing parentheses, which will be used for 66contain at least one pair of capturing parentheses, which will be used for
67the match. For example, the followign adds a regex that matches everything 67the match. For example, the following adds a regex that matches everything
68between two vertical bars: 68between two vertical bars:
69 69
70 URxvt.selection.pattern-0: \\|([^|]+)\\| 70 URxvt.selection.pattern-0: \\|([^|]+)\\|
71 71
72Another example: Programs I use often output "absolute path: " at the 72Another example: Programs I use often output "absolute path: " at the
… …
122Other extensions can extend this popup menu by pushing a code reference 122Other extensions can extend this popup menu by pushing a code reference
123onto C<@{ $term->{selection_popup_hook} }>, which gets called whenever the 123onto C<@{ $term->{selection_popup_hook} }>, which gets called whenever the
124popup is being displayed. 124popup is being displayed.
125 125
126It's sole argument is the popup menu, which can be modified. The selection 126It's sole argument is the popup menu, which can be modified. The selection
127is in C<$_>, which can be used to decide wether to add something or not. 127is in C<$_>, which can be used to decide whether to add something or not.
128It should either return nothing or a string and a code reference. The 128It should either return nothing or a string and a code reference. The
129string will be used as button text and the code reference will be called 129string will be used as button text and the code reference will be called
130when the button gets activated and should transform C<$_>. 130when the button gets activated and should transform C<$_>.
131 131
132The following will add an entry C<a to b> that transforms all C<a>s in 132The following will add an entry C<a to b> that transforms all C<a>s in
… …
151bottom. C<Escape> leaves search mode and returns to the point where search 151bottom. C<Escape> leaves search mode and returns to the point where search
152was started, while C<Enter> or C<Return> stay at the current position and 152was started, while C<Enter> or C<Return> stay at the current position and
153additionally stores the first match in the current line into the primary 153additionally stores the first match in the current line into the primary
154selection. 154selection.
155 155
156The regex defaults to "(?i)", resulting in a case-insensitive search. To
157get a case-sensitive search you can delete this prefix using C<BackSpace>
158or simply use an uppercase character which removes the "(?i)" prefix.
159
160See L<perlre> for more info about perl regular expression syntax.
161
156=item readline (enabled by default) 162=item readline (enabled by default)
157 163
158A support package that tries to make editing with readline easier. At 164A support package that tries to make editing with readline easier. At
159the moment, it reacts to clicking shift-left mouse button by trying to 165the moment, it reacts to clicking shift-left mouse button by trying to
160move the text cursor to this position. It does so by generating as many 166move the text cursor to this position. It does so by generating as many
… …
214the message into vi commands to load the file. 220the message into vi commands to load the file.
215 221
216=item tabbed 222=item tabbed
217 223
218This transforms the terminal into a tabbar with additional terminals, that 224This transforms the terminal into a tabbar with additional terminals, that
219is, it implements what is commonly refered to as "tabbed terminal". The topmost line 225is, it implements what is commonly referred to as "tabbed terminal". The topmost line
220displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one 226displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one
221button per tab. 227button per tab.
222 228
223Clicking a button will activate that tab. Pressing B<Shift-Left> and 229Clicking a button will activate that tab. Pressing B<Shift-Left> and
224B<Shift-Right> will switch to the tab left or right of the current one, 230B<Shift-Right> will switch to the tab left or right of the current one,
… …
253You enable it by specifying this extension and a preedit style of 259You enable it by specifying this extension and a preedit style of
254C<OnTheSpot>, i.e.: 260C<OnTheSpot>, i.e.:
255 261
256 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot 262 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot
257 263
264=item kuake<hotkey>
265
266A very primitive quake-console-like extension. It was inspired by a
267description of how the programs C<kuake> and C<yakuake> work: Whenever the
268user presses a global accelerator key (by default C<F10>), the terminal
269will show or hide itself. Another press of the accelerator key will hide
270or show it again.
271
272Initially, the window will not be shown when using this extension.
273
274This is useful if you need a single terminal thats not using any desktop
275space most of the time but is quickly available at the press of a key.
276
277The accelerator key is grabbed regardless of any modifiers, so this
278extension will actually grab a physical key just for this function.
279
280If you want a quake-like animation, tell your window manager to do so
281(fvwm can do it).
282
258=item automove-background 283=item automove-background
259 284
260This is basically a very small extension that dynamically changes the 285This is basically a very small extension that dynamically changes the
261background pixmap offset to the window position, in effect creating the 286background pixmap offset to the window position, in effect creating the
262same effect as pseudo transparency with a custom pixmap. No scaling is 287same effect as pseudo transparency with a custom pixmap. No scaling is
263supported in this mode. Exmaple: 288supported in this mode. Example:
264 289
265 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background 290 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background
266 291
267=item block-graphics-to-ascii 292=item block-graphics-to-ascii
268 293
269A not very useful example of filtering all text output to the terminal, 294A not very useful example of filtering all text output to the terminal
270by replacing all line-drawing characters (U+2500 .. U+259F) by a 295by replacing all line-drawing characters (U+2500 .. U+259F) by a
271similar-looking ascii character. 296similar-looking ascii character.
272 297
273=item digital-clock 298=item digital-clock
274 299
… …
405=head2 Hooks 430=head2 Hooks
406 431
407The following subroutines can be declared in extension files, and will be 432The following subroutines can be declared in extension files, and will be
408called whenever the relevant event happens. 433called whenever the relevant event happens.
409 434
410The first argument passed to them is an extension oject as described in 435The first argument passed to them is an extension object as described in
411the in the C<Extension Objects> section. 436the in the C<Extension Objects> section.
412 437
413B<All> of these hooks must return a boolean value. If any of the called 438B<All> of these hooks must return a boolean value. If any of the called
414hooks returns true, then the event counts as being I<consumed>, and the 439hooks returns true, then the event counts as being I<consumed>, and the
415relevant action might not be carried out by the C++ code. 440relevant action might not be carried out by the C++ code.
… …
428place. 453place.
429 454
430=item on_start $term 455=item on_start $term
431 456
432Called at the very end of initialisation of a new terminal, just before 457Called at the very end of initialisation of a new terminal, just before
433trying to map (display) the toplevel and returning to the mainloop. 458trying to map (display) the toplevel and returning to the main loop.
434 459
435=item on_destroy $term 460=item on_destroy $term
436 461
437Called whenever something tries to destroy terminal, when the terminal is 462Called whenever something tries to destroy terminal, when the terminal is
438still fully functional (not for long, though). 463still fully functional (not for long, though).
… …
465 490
466Called whenever a selection has been copied, but before the selection is 491Called whenever a selection has been copied, but before the selection is
467requested from the server. The selection text can be queried and changed 492requested from the server. The selection text can be queried and changed
468by calling C<< $term->selection >>. 493by calling C<< $term->selection >>.
469 494
470Returning a true value aborts selection grabbing. It will still be hilighted. 495Returning a true value aborts selection grabbing. It will still be highlighted.
471 496
472=item on_sel_extend $term 497=item on_sel_extend $term
473 498
474Called whenever the user tries to extend the selection (e.g. with a double 499Called whenever the user tries to extend the selection (e.g. with a double
475click) and is either supposed to return false (normal operation), or 500click) and is either supposed to return false (normal operation), or
476should extend the selection itelf and return true to suppress the built-in 501should extend the selection itself and return true to suppress the built-in
477processing. This can happen multiple times, as long as the callback 502processing. This can happen multiple times, as long as the callback
478returns true, it will be called on every further click by the user and is 503returns true, it will be called on every further click by the user and is
479supposed to enlarge the selection more and more, if possible. 504supposed to enlarge the selection more and more, if possible.
480 505
481See the F<selection> example extension. 506See the F<selection> example extension.
482 507
483=item on_view_change $term, $offset 508=item on_view_change $term, $offset
484 509
485Called whenever the view offset changes, i..e the user or program 510Called whenever the view offset changes, i.e. the user or program
486scrolls. Offset C<0> means display the normal terminal, positive values 511scrolls. Offset C<0> means display the normal terminal, positive values
487show this many lines of scrollback. 512show this many lines of scrollback.
488 513
489=item on_scroll_back $term, $lines, $saved 514=item on_scroll_back $term, $lines, $saved
490 515
… …
514string should start with the extension name and a colon, to distinguish 539string should start with the extension name and a colon, to distinguish
515it from commands for other extensions, and this might be enforced in the 540it from commands for other extensions, and this might be enforced in the
516future. 541future.
517 542
518Be careful not ever to trust (in a security sense) the data you receive, 543Be careful not ever to trust (in a security sense) the data you receive,
519as its source can not easily be controleld (e-mail content, messages from 544as its source can not easily be controlled (e-mail content, messages from
520other users on the same system etc.). 545other users on the same system etc.).
521 546
522=item on_add_lines $term, $string 547=item on_add_lines $term, $string
523 548
524Called whenever text is about to be output, with the text as argument. You 549Called whenever text is about to be output, with the text as argument. You
… …
557 582
558Called just after the screen gets redrawn. See C<on_refresh_begin>. 583Called just after the screen gets redrawn. See C<on_refresh_begin>.
559 584
560=item on_user_command $term, $string 585=item on_user_command $term, $string
561 586
562Called whenever the a user-configured event is being activated (e.g. via 587Called whenever a user-configured event is being activated (e.g. via
563a C<perl:string> action bound to a key, see description of the B<keysym> 588a C<perl:string> action bound to a key, see description of the B<keysym>
564resource in the @@RXVT_NAME@@(1) manpage). 589resource in the @@RXVT_NAME@@(1) manpage).
565 590
566The event is simply the action string. This interface is assumed to change 591The event is simply the action string. This interface is assumed to change
567slightly in the future. 592slightly in the future.
568 593
569=item on_resize_all_windows $tern, $new_width, $new_height 594=item on_resize_all_windows $tern, $new_width, $new_height
570 595
571Called just after the new window size has been calculcated, but before 596Called just after the new window size has been calculated, but before
572windows are actually being resized or hints are being set. If this hook 597windows are actually being resized or hints are being set. If this hook
573returns TRUE, setting of the window hints is being skipped. 598returns TRUE, setting of the window hints is being skipped.
574 599
575=item on_x_event $term, $event 600=item on_x_event $term, $event
576 601
577Called on every X event received on the vt window (and possibly other 602Called on every X event received on the vt window (and possibly other
578windows). Should only be used as a last resort. Most event structure 603windows). Should only be used as a last resort. Most event structure
579members are not passed. 604members are not passed.
580 605
606=item on_root_event $term, $event
607
608Like C<on_x_event>, but is called for events on the root window.
609
581=item on_focus_in $term 610=item on_focus_in $term
582 611
583Called whenever the window gets the keyboard focus, before rxvt-unicode 612Called whenever the window gets the keyboard focus, before rxvt-unicode
584does focus in processing. 613does focus in processing.
585 614
586=item on_focus_out $term 615=item on_focus_out $term
587 616
588Called wheneever the window loses keyboard focus, before rxvt-unicode does 617Called whenever the window loses keyboard focus, before rxvt-unicode does
589focus out processing. 618focus out processing.
590 619
591=item on_configure_notify $term, $event 620=item on_configure_notify $term, $event
592 621
593=item on_property_notify $term, $event 622=item on_property_notify $term, $event
… …
676The current terminal. This variable stores the current C<urxvt::term> 705The current terminal. This variable stores the current C<urxvt::term>
677object, whenever a callback/hook is executing. 706object, whenever a callback/hook is executing.
678 707
679=item @urxvt::TERM_INIT 708=item @urxvt::TERM_INIT
680 709
681All coderefs in this array will be called as methods of the next newly 710All code references in this array will be called as methods of the next newly
682created C<urxvt::term> object (during the C<on_init> phase). The array 711created C<urxvt::term> object (during the C<on_init> phase). The array
683gets cleared before the codereferences that were in it are being executed, 712gets cleared before the code references that were in it are being executed,
684so coderefs can push themselves onto it again if they so desire. 713so references can push themselves onto it again if they so desire.
685 714
686This complements to the perl-eval commandline option, but gets executed 715This complements to the perl-eval command line option, but gets executed
687first. 716first.
688 717
689=item @urxvt::TERM_EXT 718=item @urxvt::TERM_EXT
690 719
691Works similar to C<@TERM_INIT>, but contains perl package/class names, which 720Works similar to C<@TERM_INIT>, but contains perl package/class names, which
… …
716Messages have a size limit of 1023 bytes currently. 745Messages have a size limit of 1023 bytes currently.
717 746
718=item @terms = urxvt::termlist 747=item @terms = urxvt::termlist
719 748
720Returns all urxvt::term objects that exist in this process, regardless of 749Returns all urxvt::term objects that exist in this process, regardless of
721wether they are started, being destroyed etc., so be careful. Only term 750whether they are started, being destroyed etc., so be careful. Only term
722objects that have perl extensions attached will be returned (because there 751objects that have perl extensions attached will be returned (because there
723is no urxvt::term objet associated with others). 752is no urxvt::term objet associated with others).
724 753
725=item $time = urxvt::NOW 754=item $time = urxvt::NOW
726 755
… …
1164 1193
1165Returns true if the option specified by C<$optval> is enabled, and 1194Returns true if the option specified by C<$optval> is enabled, and
1166optionally change it. All option values are stored by name in the hash 1195optionally change it. All option values are stored by name in the hash
1167C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash. 1196C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
1168 1197
1169Here is a a likely non-exhaustive list of option names, please see the 1198Here is a likely non-exhaustive list of option names, please see the
1170source file F</src/optinc.h> to see the actual list: 1199source file F</src/optinc.h> to see the actual list:
1171 1200
1172 borderLess console cursorBlink cursorUnderline hold iconic insecure 1201 borderLess console cursorBlink cursorUnderline hold iconic insecure
1173 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 1202 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
1174 override-redirect pastableTabs pointerBlank reverseVideo scrollBar 1203 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
… …
1191likely change). 1220likely change).
1192 1221
1193Please note that resource strings will currently only be freed when the 1222Please note that resource strings will currently only be freed when the
1194terminal is destroyed, so changing options frequently will eat memory. 1223terminal is destroyed, so changing options frequently will eat memory.
1195 1224
1196Here is a a likely non-exhaustive list of resource names, not all of which 1225Here is a likely non-exhaustive list of resource names, not all of which
1197are supported in every build, please see the source file F</src/rsinc.h> 1226are supported in every build, please see the source file F</src/rsinc.h>
1198to see the actual list: 1227to see the actual list:
1199 1228
1200 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1229 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
1201 borderLess color cursorBlink cursorUnderline cutchars delete_key 1230 borderLess color cursorBlink cursorUnderline cutchars delete_key
… …
1513 1542
1514Returns the currently displayed screen (0 primary, 1 secondary). 1543Returns the currently displayed screen (0 primary, 1 secondary).
1515 1544
1516=item $cursor_is_hidden = $term->hidden_cursor 1545=item $cursor_is_hidden = $term->hidden_cursor
1517 1546
1518Returns wether the cursor is currently hidden or not. 1547Returns whether the cursor is currently hidden or not.
1519 1548
1520=item $view_start = $term->view_start ([$newvalue]) 1549=item $view_start = $term->view_start ([$newvalue])
1521 1550
1522Returns the row number of the topmost displayed line. Maximum value is 1551Returns the row number of the topmost displayed line. Maximum value is
1523C<0>, which displays the normal terminal contents. Lower values scroll 1552C<0>, which displays the normal terminal contents. Lower values scroll
… …
1700where one character corresponds to one screen cell. See 1729where one character corresponds to one screen cell. See
1701C<< $term->ROW_t >> for details. 1730C<< $term->ROW_t >> for details.
1702 1731
1703=item $string = $term->special_decode $text 1732=item $string = $term->special_decode $text
1704 1733
1705Converts rxvt-unicodes text reprsentation into a perl string. See 1734Converts rxvt-unicodes text representation into a perl string. See
1706C<< $term->ROW_t >> for details. 1735C<< $term->ROW_t >> for details.
1707 1736
1708=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt]) 1737=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1709 1738
1710=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt]) 1739=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
… …
1713manpage. 1742manpage.
1714 1743
1715=item $success = $term->grab ($eventtime[, $sync]) 1744=item $success = $term->grab ($eventtime[, $sync])
1716 1745
1717Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1746Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1718synchronous (C<$sync> is true). Also remembers the grab timestampe. 1747synchronous (C<$sync> is true). Also remembers the grab timestamp.
1719 1748
1720=item $term->allow_events_async 1749=item $term->allow_events_async
1721 1750
1722Calls XAllowEvents with AsyncBoth for the most recent grab. 1751Calls XAllowEvents with AsyncBoth for the most recent grab.
1723 1752
… …
1990Set the callback to be called when io events are triggered. C<$reventmask> 2019Set the callback to be called when io events are triggered. C<$reventmask>
1991is a bitset as described in the C<events> method. 2020is a bitset as described in the C<events> method.
1992 2021
1993=item $iow = $iow->fd ($fd) 2022=item $iow = $iow->fd ($fd)
1994 2023
1995Set the filedescriptor (not handle) to watch. 2024Set the file descriptor (not handle) to watch.
1996 2025
1997=item $iow = $iow->events ($eventmask) 2026=item $iow = $iow->events ($eventmask)
1998 2027
1999Set the event mask to watch. The only allowed values are 2028Set the event mask to watch. The only allowed values are
2000C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed 2029C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed
… …
2004 2033
2005Start watching for requested events on the given handle. 2034Start watching for requested events on the given handle.
2006 2035
2007=item $iow = $iow->stop 2036=item $iow = $iow->stop
2008 2037
2009Stop watching for events on the given filehandle. 2038Stop watching for events on the given file handle.
2010 2039
2011=back 2040=back
2012 2041
2013=head2 The C<urxvt::iw> Class 2042=head2 The C<urxvt::iw> Class
2014 2043
… …
2061 2090
2062Set the callback to be called when the timer triggers. 2091Set the callback to be called when the timer triggers.
2063 2092
2064=item $pw = $timer->start ($pid) 2093=item $pw = $timer->start ($pid)
2065 2094
2066Tells the wqtcher to start watching for process C<$pid>. 2095Tells the watcher to start watching for process C<$pid>.
2067 2096
2068=item $pw = $pw->stop 2097=item $pw = $pw->stop
2069 2098
2070Stop the watcher. 2099Stop the watcher.
2071 2100
… …
2084 2113
2085=item >= 3 - script loading and management 2114=item >= 3 - script loading and management
2086 2115
2087=item >=10 - all called hooks 2116=item >=10 - all called hooks
2088 2117
2089=item >=11 - hook reutrn values 2118=item >=11 - hook return values
2090 2119
2091=back 2120=back
2092 2121
2093=head1 AUTHOR 2122=head1 AUTHOR
2094 2123

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines