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.145 by root, Thu Aug 10 22:53:20 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
… …
370=back 395=back
371 396
372=head2 Extension Objects 397=head2 Extension Objects
373 398
374Every perl extension is a perl class. A separate perl object is created 399Every perl extension is a perl class. A separate perl object is created
375for each terminal and each extension and passed as the first parameter to 400for each terminal, and each terminal has its own set of extenion objects,
376hooks. So extensions can use their C<$self> object without having to think 401which are passed as the first parameter to hooks. So extensions can use
377about other extensions, with the exception of methods and members that 402their C<$self> object without having to think about clashes with other
403extensions or other terminals, with the exception of methods and members
378begin with an underscore character C<_>: these are reserved for internal 404that begin with an underscore character C<_>: these are reserved for
379use. 405internal use.
380 406
381Although it isn't a C<urxvt::term> object, you can call all methods of the 407Although it isn't a C<urxvt::term> object, you can call all methods of the
382C<urxvt::term> class on this object. 408C<urxvt::term> class on this object.
383 409
384It has the following methods and data members: 410It has the following methods and data members:
… …
405=head2 Hooks 431=head2 Hooks
406 432
407The following subroutines can be declared in extension files, and will be 433The following subroutines can be declared in extension files, and will be
408called whenever the relevant event happens. 434called whenever the relevant event happens.
409 435
410The first argument passed to them is an extension oject as described in 436The first argument passed to them is an extension object as described in
411the in the C<Extension Objects> section. 437the in the C<Extension Objects> section.
412 438
413B<All> of these hooks must return a boolean value. If any of the called 439B<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 440hooks returns true, then the event counts as being I<consumed>, and the
415relevant action might not be carried out by the C++ code. 441relevant action might not be carried out by the C++ code.
… …
428place. 454place.
429 455
430=item on_start $term 456=item on_start $term
431 457
432Called at the very end of initialisation of a new terminal, just before 458Called at the very end of initialisation of a new terminal, just before
433trying to map (display) the toplevel and returning to the mainloop. 459trying to map (display) the toplevel and returning to the main loop.
434 460
435=item on_destroy $term 461=item on_destroy $term
436 462
437Called whenever something tries to destroy terminal, when the terminal is 463Called whenever something tries to destroy terminal, when the terminal is
438still fully functional (not for long, though). 464still fully functional (not for long, though).
… …
465 491
466Called whenever a selection has been copied, but before the selection is 492Called whenever a selection has been copied, but before the selection is
467requested from the server. The selection text can be queried and changed 493requested from the server. The selection text can be queried and changed
468by calling C<< $term->selection >>. 494by calling C<< $term->selection >>.
469 495
470Returning a true value aborts selection grabbing. It will still be hilighted. 496Returning a true value aborts selection grabbing. It will still be highlighted.
471 497
472=item on_sel_extend $term 498=item on_sel_extend $term
473 499
474Called whenever the user tries to extend the selection (e.g. with a double 500Called whenever the user tries to extend the selection (e.g. with a double
475click) and is either supposed to return false (normal operation), or 501click) and is either supposed to return false (normal operation), or
476should extend the selection itelf and return true to suppress the built-in 502should extend the selection itself and return true to suppress the built-in
477processing. This can happen multiple times, as long as the callback 503processing. 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 504returns true, it will be called on every further click by the user and is
479supposed to enlarge the selection more and more, if possible. 505supposed to enlarge the selection more and more, if possible.
480 506
481See the F<selection> example extension. 507See the F<selection> example extension.
482 508
483=item on_view_change $term, $offset 509=item on_view_change $term, $offset
484 510
485Called whenever the view offset changes, i..e the user or program 511Called whenever the view offset changes, i.e. the user or program
486scrolls. Offset C<0> means display the normal terminal, positive values 512scrolls. Offset C<0> means display the normal terminal, positive values
487show this many lines of scrollback. 513show this many lines of scrollback.
488 514
489=item on_scroll_back $term, $lines, $saved 515=item on_scroll_back $term, $lines, $saved
490 516
… …
514string should start with the extension name and a colon, to distinguish 540string should start with the extension name and a colon, to distinguish
515it from commands for other extensions, and this might be enforced in the 541it from commands for other extensions, and this might be enforced in the
516future. 542future.
517 543
518Be careful not ever to trust (in a security sense) the data you receive, 544Be 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 545as its source can not easily be controlled (e-mail content, messages from
520other users on the same system etc.). 546other users on the same system etc.).
521 547
522=item on_add_lines $term, $string 548=item on_add_lines $term, $string
523 549
524Called whenever text is about to be output, with the text as argument. You 550Called whenever text is about to be output, with the text as argument. You
… …
557 583
558Called just after the screen gets redrawn. See C<on_refresh_begin>. 584Called just after the screen gets redrawn. See C<on_refresh_begin>.
559 585
560=item on_user_command $term, $string 586=item on_user_command $term, $string
561 587
562Called whenever the a user-configured event is being activated (e.g. via 588Called 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> 589a C<perl:string> action bound to a key, see description of the B<keysym>
564resource in the @@RXVT_NAME@@(1) manpage). 590resource in the @@RXVT_NAME@@(1) manpage).
565 591
566The event is simply the action string. This interface is assumed to change 592The event is simply the action string. This interface is assumed to change
567slightly in the future. 593slightly in the future.
568 594
569=item on_resize_all_windows $tern, $new_width, $new_height 595=item on_resize_all_windows $tern, $new_width, $new_height
570 596
571Called just after the new window size has been calculcated, but before 597Called just after the new window size has been calculated, but before
572windows are actually being resized or hints are being set. If this hook 598windows are actually being resized or hints are being set. If this hook
573returns TRUE, setting of the window hints is being skipped. 599returns TRUE, setting of the window hints is being skipped.
574 600
575=item on_x_event $term, $event 601=item on_x_event $term, $event
576 602
577Called on every X event received on the vt window (and possibly other 603Called on every X event received on the vt window (and possibly other
578windows). Should only be used as a last resort. Most event structure 604windows). Should only be used as a last resort. Most event structure
579members are not passed. 605members are not passed.
580 606
607=item on_root_event $term, $event
608
609Like C<on_x_event>, but is called for events on the root window.
610
581=item on_focus_in $term 611=item on_focus_in $term
582 612
583Called whenever the window gets the keyboard focus, before rxvt-unicode 613Called whenever the window gets the keyboard focus, before rxvt-unicode
584does focus in processing. 614does focus in processing.
585 615
586=item on_focus_out $term 616=item on_focus_out $term
587 617
588Called wheneever the window loses keyboard focus, before rxvt-unicode does 618Called whenever the window loses keyboard focus, before rxvt-unicode does
589focus out processing. 619focus out processing.
590 620
591=item on_configure_notify $term, $event 621=item on_configure_notify $term, $event
592 622
593=item on_property_notify $term, $event 623=item on_property_notify $term, $event
… …
676The current terminal. This variable stores the current C<urxvt::term> 706The current terminal. This variable stores the current C<urxvt::term>
677object, whenever a callback/hook is executing. 707object, whenever a callback/hook is executing.
678 708
679=item @urxvt::TERM_INIT 709=item @urxvt::TERM_INIT
680 710
681All coderefs in this array will be called as methods of the next newly 711All 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 712created C<urxvt::term> object (during the C<on_init> phase). The array
683gets cleared before the codereferences that were in it are being executed, 713gets cleared before the code references that were in it are being executed,
684so coderefs can push themselves onto it again if they so desire. 714so references can push themselves onto it again if they so desire.
685 715
686This complements to the perl-eval commandline option, but gets executed 716This complements to the perl-eval command line option, but gets executed
687first. 717first.
688 718
689=item @urxvt::TERM_EXT 719=item @urxvt::TERM_EXT
690 720
691Works similar to C<@TERM_INIT>, but contains perl package/class names, which 721Works similar to C<@TERM_INIT>, but contains perl package/class names, which
… …
716Messages have a size limit of 1023 bytes currently. 746Messages have a size limit of 1023 bytes currently.
717 747
718=item @terms = urxvt::termlist 748=item @terms = urxvt::termlist
719 749
720Returns all urxvt::term objects that exist in this process, regardless of 750Returns all urxvt::term objects that exist in this process, regardless of
721wether they are started, being destroyed etc., so be careful. Only term 751whether they are started, being destroyed etc., so be careful. Only term
722objects that have perl extensions attached will be returned (because there 752objects that have perl extensions attached will be returned (because there
723is no urxvt::term objet associated with others). 753is no urxvt::term objet associated with others).
724 754
725=item $time = urxvt::NOW 755=item $time = urxvt::NOW
726 756
… …
1164 1194
1165Returns true if the option specified by C<$optval> is enabled, and 1195Returns true if the option specified by C<$optval> is enabled, and
1166optionally change it. All option values are stored by name in the hash 1196optionally 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. 1197C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
1168 1198
1169Here is a a likely non-exhaustive list of option names, please see the 1199Here is a likely non-exhaustive list of option names, please see the
1170source file F</src/optinc.h> to see the actual list: 1200source file F</src/optinc.h> to see the actual list:
1171 1201
1172 borderLess console cursorBlink cursorUnderline hold iconic insecure 1202 borderLess console cursorBlink cursorUnderline hold iconic insecure
1173 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 1203 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
1174 override-redirect pastableTabs pointerBlank reverseVideo scrollBar 1204 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
… …
1191likely change). 1221likely change).
1192 1222
1193Please note that resource strings will currently only be freed when the 1223Please note that resource strings will currently only be freed when the
1194terminal is destroyed, so changing options frequently will eat memory. 1224terminal is destroyed, so changing options frequently will eat memory.
1195 1225
1196Here is a a likely non-exhaustive list of resource names, not all of which 1226Here 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> 1227are supported in every build, please see the source file F</src/rsinc.h>
1198to see the actual list: 1228to see the actual list:
1199 1229
1200 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1230 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
1201 borderLess color cursorBlink cursorUnderline cutchars delete_key 1231 borderLess color cursorBlink cursorUnderline cutchars delete_key
… …
1513 1543
1514Returns the currently displayed screen (0 primary, 1 secondary). 1544Returns the currently displayed screen (0 primary, 1 secondary).
1515 1545
1516=item $cursor_is_hidden = $term->hidden_cursor 1546=item $cursor_is_hidden = $term->hidden_cursor
1517 1547
1518Returns wether the cursor is currently hidden or not. 1548Returns whether the cursor is currently hidden or not.
1519 1549
1520=item $view_start = $term->view_start ([$newvalue]) 1550=item $view_start = $term->view_start ([$newvalue])
1521 1551
1522Returns the row number of the topmost displayed line. Maximum value is 1552Returns the row number of the topmost displayed line. Maximum value is
1523C<0>, which displays the normal terminal contents. Lower values scroll 1553C<0>, which displays the normal terminal contents. Lower values scroll
… …
1700where one character corresponds to one screen cell. See 1730where one character corresponds to one screen cell. See
1701C<< $term->ROW_t >> for details. 1731C<< $term->ROW_t >> for details.
1702 1732
1703=item $string = $term->special_decode $text 1733=item $string = $term->special_decode $text
1704 1734
1705Converts rxvt-unicodes text reprsentation into a perl string. See 1735Converts rxvt-unicodes text representation into a perl string. See
1706C<< $term->ROW_t >> for details. 1736C<< $term->ROW_t >> for details.
1707 1737
1708=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt]) 1738=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1709 1739
1710=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt]) 1740=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
… …
1713manpage. 1743manpage.
1714 1744
1715=item $success = $term->grab ($eventtime[, $sync]) 1745=item $success = $term->grab ($eventtime[, $sync])
1716 1746
1717Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1747Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1718synchronous (C<$sync> is true). Also remembers the grab timestampe. 1748synchronous (C<$sync> is true). Also remembers the grab timestamp.
1719 1749
1720=item $term->allow_events_async 1750=item $term->allow_events_async
1721 1751
1722Calls XAllowEvents with AsyncBoth for the most recent grab. 1752Calls XAllowEvents with AsyncBoth for the most recent grab.
1723 1753
… …
1990Set the callback to be called when io events are triggered. C<$reventmask> 2020Set the callback to be called when io events are triggered. C<$reventmask>
1991is a bitset as described in the C<events> method. 2021is a bitset as described in the C<events> method.
1992 2022
1993=item $iow = $iow->fd ($fd) 2023=item $iow = $iow->fd ($fd)
1994 2024
1995Set the filedescriptor (not handle) to watch. 2025Set the file descriptor (not handle) to watch.
1996 2026
1997=item $iow = $iow->events ($eventmask) 2027=item $iow = $iow->events ($eventmask)
1998 2028
1999Set the event mask to watch. The only allowed values are 2029Set the event mask to watch. The only allowed values are
2000C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed 2030C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed
… …
2004 2034
2005Start watching for requested events on the given handle. 2035Start watching for requested events on the given handle.
2006 2036
2007=item $iow = $iow->stop 2037=item $iow = $iow->stop
2008 2038
2009Stop watching for events on the given filehandle. 2039Stop watching for events on the given file handle.
2010 2040
2011=back 2041=back
2012 2042
2013=head2 The C<urxvt::iw> Class 2043=head2 The C<urxvt::iw> Class
2014 2044
… …
2061 2091
2062Set the callback to be called when the timer triggers. 2092Set the callback to be called when the timer triggers.
2063 2093
2064=item $pw = $timer->start ($pid) 2094=item $pw = $timer->start ($pid)
2065 2095
2066Tells the wqtcher to start watching for process C<$pid>. 2096Tells the watcher to start watching for process C<$pid>.
2067 2097
2068=item $pw = $pw->stop 2098=item $pw = $pw->stop
2069 2099
2070Stop the watcher. 2100Stop the watcher.
2071 2101
… …
2084 2114
2085=item >= 3 - script loading and management 2115=item >= 3 - script loading and management
2086 2116
2087=item >=10 - all called hooks 2117=item >=10 - all called hooks
2088 2118
2089=item >=11 - hook reutrn values 2119=item >=11 - hook return values
2090 2120
2091=back 2121=back
2092 2122
2093=head1 AUTHOR 2123=head1 AUTHOR
2094 2124

Diff Legend

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