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.143 by root, Thu Jul 6 23:48:11 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
… …
220the message into vi commands to load the file. 220the message into vi commands to load the file.
221 221
222=item tabbed 222=item tabbed
223 223
224This transforms the terminal into a tabbar with additional terminals, that 224This transforms the terminal into a tabbar with additional terminals, that
225is, 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
226displays 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
227button per tab. 227button per tab.
228 228
229Clicking a button will activate that tab. Pressing B<Shift-Left> and 229Clicking a button will activate that tab. Pressing B<Shift-Left> and
230B<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,
… …
272Initially, the window will not be shown when using this extension. 272Initially, the window will not be shown when using this extension.
273 273
274This is useful if you need a single terminal thats not using any desktop 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. 275space most of the time but is quickly available at the press of a key.
276 276
277The accelerator key is grabbed regardless of any modifers, so this 277The accelerator key is grabbed regardless of any modifiers, so this
278extension will actually grab a physical key just for this function. 278extension will actually grab a physical key just for this function.
279 279
280If you want a quake-like animation, tell your window manager to do so 280If you want a quake-like animation, tell your window manager to do so
281(fvwm can do it). 281(fvwm can do it).
282 282
283=item automove-background 283=item automove-background
284 284
285This is basically a very small extension that dynamically changes the 285This is basically a very small extension that dynamically changes the
286background pixmap offset to the window position, in effect creating the 286background pixmap offset to the window position, in effect creating the
287same effect as pseudo transparency with a custom pixmap. No scaling is 287same effect as pseudo transparency with a custom pixmap. No scaling is
288supported in this mode. Exmaple: 288supported in this mode. Example:
289 289
290 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background 290 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background
291 291
292=item block-graphics-to-ascii 292=item block-graphics-to-ascii
293 293
… …
430=head2 Hooks 430=head2 Hooks
431 431
432The following subroutines can be declared in extension files, and will be 432The following subroutines can be declared in extension files, and will be
433called whenever the relevant event happens. 433called whenever the relevant event happens.
434 434
435The 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
436the in the C<Extension Objects> section. 436the in the C<Extension Objects> section.
437 437
438B<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
439hooks 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
440relevant action might not be carried out by the C++ code. 440relevant action might not be carried out by the C++ code.
… …
453place. 453place.
454 454
455=item on_start $term 455=item on_start $term
456 456
457Called 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
458trying to map (display) the toplevel and returning to the mainloop. 458trying to map (display) the toplevel and returning to the main loop.
459 459
460=item on_destroy $term 460=item on_destroy $term
461 461
462Called whenever something tries to destroy terminal, when the terminal is 462Called whenever something tries to destroy terminal, when the terminal is
463still fully functional (not for long, though). 463still fully functional (not for long, though).
… …
490 490
491Called whenever a selection has been copied, but before the selection is 491Called whenever a selection has been copied, but before the selection is
492requested from the server. The selection text can be queried and changed 492requested from the server. The selection text can be queried and changed
493by calling C<< $term->selection >>. 493by calling C<< $term->selection >>.
494 494
495Returning a true value aborts selection grabbing. It will still be hilighted. 495Returning a true value aborts selection grabbing. It will still be highlighted.
496 496
497=item on_sel_extend $term 497=item on_sel_extend $term
498 498
499Called 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
500click) and is either supposed to return false (normal operation), or 500click) and is either supposed to return false (normal operation), or
501should 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
502processing. This can happen multiple times, as long as the callback 502processing. This can happen multiple times, as long as the callback
503returns 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
504supposed to enlarge the selection more and more, if possible. 504supposed to enlarge the selection more and more, if possible.
505 505
506See the F<selection> example extension. 506See the F<selection> example extension.
507 507
508=item on_view_change $term, $offset 508=item on_view_change $term, $offset
509 509
510Called whenever the view offset changes, i..e the user or program 510Called whenever the view offset changes, i.e. the user or program
511scrolls. Offset C<0> means display the normal terminal, positive values 511scrolls. Offset C<0> means display the normal terminal, positive values
512show this many lines of scrollback. 512show this many lines of scrollback.
513 513
514=item on_scroll_back $term, $lines, $saved 514=item on_scroll_back $term, $lines, $saved
515 515
… …
539string should start with the extension name and a colon, to distinguish 539string should start with the extension name and a colon, to distinguish
540it 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
541future. 541future.
542 542
543Be 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,
544as 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
545other users on the same system etc.). 545other users on the same system etc.).
546 546
547=item on_add_lines $term, $string 547=item on_add_lines $term, $string
548 548
549Called 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
… …
582 582
583Called just after the screen gets redrawn. See C<on_refresh_begin>. 583Called just after the screen gets redrawn. See C<on_refresh_begin>.
584 584
585=item on_user_command $term, $string 585=item on_user_command $term, $string
586 586
587Called whenever the a user-configured event is being activated (e.g. via 587Called whenever a user-configured event is being activated (e.g. via
588a 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>
589resource in the @@RXVT_NAME@@(1) manpage). 589resource in the @@RXVT_NAME@@(1) manpage).
590 590
591The 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
592slightly in the future. 592slightly in the future.
593 593
594=item on_resize_all_windows $tern, $new_width, $new_height 594=item on_resize_all_windows $tern, $new_width, $new_height
595 595
596Called just after the new window size has been calculcated, but before 596Called just after the new window size has been calculated, but before
597windows 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
598returns TRUE, setting of the window hints is being skipped. 598returns TRUE, setting of the window hints is being skipped.
599 599
600=item on_x_event $term, $event 600=item on_x_event $term, $event
601 601
… …
612Called whenever the window gets the keyboard focus, before rxvt-unicode 612Called whenever the window gets the keyboard focus, before rxvt-unicode
613does focus in processing. 613does focus in processing.
614 614
615=item on_focus_out $term 615=item on_focus_out $term
616 616
617Called wheneever the window loses keyboard focus, before rxvt-unicode does 617Called whenever the window loses keyboard focus, before rxvt-unicode does
618focus out processing. 618focus out processing.
619 619
620=item on_configure_notify $term, $event 620=item on_configure_notify $term, $event
621 621
622=item on_property_notify $term, $event 622=item on_property_notify $term, $event
… …
705The current terminal. This variable stores the current C<urxvt::term> 705The current terminal. This variable stores the current C<urxvt::term>
706object, whenever a callback/hook is executing. 706object, whenever a callback/hook is executing.
707 707
708=item @urxvt::TERM_INIT 708=item @urxvt::TERM_INIT
709 709
710All 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
711created 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
712gets cleared before the codereferences that were in it are being executed, 712gets cleared before the code references that were in it are being executed,
713so coderefs can push themselves onto it again if they so desire. 713so references can push themselves onto it again if they so desire.
714 714
715This complements to the perl-eval commandline option, but gets executed 715This complements to the perl-eval command line option, but gets executed
716first. 716first.
717 717
718=item @urxvt::TERM_EXT 718=item @urxvt::TERM_EXT
719 719
720Works 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
… …
745Messages have a size limit of 1023 bytes currently. 745Messages have a size limit of 1023 bytes currently.
746 746
747=item @terms = urxvt::termlist 747=item @terms = urxvt::termlist
748 748
749Returns all urxvt::term objects that exist in this process, regardless of 749Returns all urxvt::term objects that exist in this process, regardless of
750wether they are started, being destroyed etc., so be careful. Only term 750whether they are started, being destroyed etc., so be careful. Only term
751objects that have perl extensions attached will be returned (because there 751objects that have perl extensions attached will be returned (because there
752is no urxvt::term objet associated with others). 752is no urxvt::term objet associated with others).
753 753
754=item $time = urxvt::NOW 754=item $time = urxvt::NOW
755 755
… …
1193 1193
1194Returns true if the option specified by C<$optval> is enabled, and 1194Returns true if the option specified by C<$optval> is enabled, and
1195optionally 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
1196C<%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.
1197 1197
1198Here 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
1199source file F</src/optinc.h> to see the actual list: 1199source file F</src/optinc.h> to see the actual list:
1200 1200
1201 borderLess console cursorBlink cursorUnderline hold iconic insecure 1201 borderLess console cursorBlink cursorUnderline hold iconic insecure
1202 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 1202 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
1203 override-redirect pastableTabs pointerBlank reverseVideo scrollBar 1203 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
… …
1220likely change). 1220likely change).
1221 1221
1222Please note that resource strings will currently only be freed when the 1222Please note that resource strings will currently only be freed when the
1223terminal is destroyed, so changing options frequently will eat memory. 1223terminal is destroyed, so changing options frequently will eat memory.
1224 1224
1225Here 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
1226are 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>
1227to see the actual list: 1227to see the actual list:
1228 1228
1229 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1229 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
1230 borderLess color cursorBlink cursorUnderline cutchars delete_key 1230 borderLess color cursorBlink cursorUnderline cutchars delete_key
… …
1542 1542
1543Returns the currently displayed screen (0 primary, 1 secondary). 1543Returns the currently displayed screen (0 primary, 1 secondary).
1544 1544
1545=item $cursor_is_hidden = $term->hidden_cursor 1545=item $cursor_is_hidden = $term->hidden_cursor
1546 1546
1547Returns wether the cursor is currently hidden or not. 1547Returns whether the cursor is currently hidden or not.
1548 1548
1549=item $view_start = $term->view_start ([$newvalue]) 1549=item $view_start = $term->view_start ([$newvalue])
1550 1550
1551Returns the row number of the topmost displayed line. Maximum value is 1551Returns the row number of the topmost displayed line. Maximum value is
1552C<0>, which displays the normal terminal contents. Lower values scroll 1552C<0>, which displays the normal terminal contents. Lower values scroll
… …
1729where one character corresponds to one screen cell. See 1729where one character corresponds to one screen cell. See
1730C<< $term->ROW_t >> for details. 1730C<< $term->ROW_t >> for details.
1731 1731
1732=item $string = $term->special_decode $text 1732=item $string = $term->special_decode $text
1733 1733
1734Converts rxvt-unicodes text reprsentation into a perl string. See 1734Converts rxvt-unicodes text representation into a perl string. See
1735C<< $term->ROW_t >> for details. 1735C<< $term->ROW_t >> for details.
1736 1736
1737=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt]) 1737=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1738 1738
1739=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt]) 1739=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
… …
1742manpage. 1742manpage.
1743 1743
1744=item $success = $term->grab ($eventtime[, $sync]) 1744=item $success = $term->grab ($eventtime[, $sync])
1745 1745
1746Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1746Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1747synchronous (C<$sync> is true). Also remembers the grab timestampe. 1747synchronous (C<$sync> is true). Also remembers the grab timestamp.
1748 1748
1749=item $term->allow_events_async 1749=item $term->allow_events_async
1750 1750
1751Calls XAllowEvents with AsyncBoth for the most recent grab. 1751Calls XAllowEvents with AsyncBoth for the most recent grab.
1752 1752
… …
2019Set 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>
2020is a bitset as described in the C<events> method. 2020is a bitset as described in the C<events> method.
2021 2021
2022=item $iow = $iow->fd ($fd) 2022=item $iow = $iow->fd ($fd)
2023 2023
2024Set the filedescriptor (not handle) to watch. 2024Set the file descriptor (not handle) to watch.
2025 2025
2026=item $iow = $iow->events ($eventmask) 2026=item $iow = $iow->events ($eventmask)
2027 2027
2028Set the event mask to watch. The only allowed values are 2028Set the event mask to watch. The only allowed values are
2029C<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
… …
2033 2033
2034Start watching for requested events on the given handle. 2034Start watching for requested events on the given handle.
2035 2035
2036=item $iow = $iow->stop 2036=item $iow = $iow->stop
2037 2037
2038Stop watching for events on the given filehandle. 2038Stop watching for events on the given file handle.
2039 2039
2040=back 2040=back
2041 2041
2042=head2 The C<urxvt::iw> Class 2042=head2 The C<urxvt::iw> Class
2043 2043
… …
2090 2090
2091Set the callback to be called when the timer triggers. 2091Set the callback to be called when the timer triggers.
2092 2092
2093=item $pw = $timer->start ($pid) 2093=item $pw = $timer->start ($pid)
2094 2094
2095Tells the wqtcher to start watching for process C<$pid>. 2095Tells the watcher to start watching for process C<$pid>.
2096 2096
2097=item $pw = $pw->stop 2097=item $pw = $pw->stop
2098 2098
2099Stop the watcher. 2099Stop the watcher.
2100 2100
… …
2113 2113
2114=item >= 3 - script loading and management 2114=item >= 3 - script loading and management
2115 2115
2116=item >=10 - all called hooks 2116=item >=10 - all called hooks
2117 2117
2118=item >=11 - hook reutrn values 2118=item >=11 - hook return values
2119 2119
2120=back 2120=back
2121 2121
2122=head1 AUTHOR 2122=head1 AUTHOR
2123 2123

Diff Legend

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