ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/rxvt-unicode/doc/rxvtperl.3.html
(Generate patch)

Comparing rxvt-unicode/doc/rxvtperl.3.html (file contents):
Revision 1.45 by root, Mon Jul 17 19:20:29 2006 UTC vs.
Revision 1.46 by root, Mon Aug 7 16:17:30 2006 UTC

… …
69 rxvt --perl-lib $HOME -pe grab_test</pre> 69 rxvt --perl-lib $HOME -pe grab_test</pre>
70<p> 70<p>
71</p> 71</p>
72<hr /> 72<hr />
73<h1><a name="description">DESCRIPTION</a></h1> 73<h1><a name="description">DESCRIPTION</a></h1>
74<p>Everytime a terminal object gets created, extension scripts specified via 74<p>Every time a terminal object gets created, extension scripts specified via
75the <code>perl</code> resource are loaded and associated with it.</p> 75the <code>perl</code> resource are loaded and associated with it.</p>
76<p>Scripts are compiled in a 'use strict' and 'use utf8' environment, and 76<p>Scripts are compiled in a 'use strict' and 'use utf8' environment, and
77thus must be encoded as UTF-8.</p> 77thus must be encoded as UTF-8.</p>
78<p>Each script will only ever be loaded once, even in rxvtd, where 78<p>Each script will only ever be loaded once, even in rxvtd, where
79scripts will be shared (but not enabled) for all terminals.</p> 79scripts will be shared (but not enabled) for all terminals.</p>
… …
115 ...</pre> 115 ...</pre>
116</dd> 116</dd>
117<dd> 117<dd>
118<p>The index number (0, 1...) must not have any holes, and each regex must 118<p>The index number (0, 1...) must not have any holes, and each regex must
119contain at least one pair of capturing parentheses, which will be used for 119contain at least one pair of capturing parentheses, which will be used for
120the match. For example, the followign adds a regex that matches everything 120the match. For example, the following adds a regex that matches everything
121between two vertical bars:</p> 121between two vertical bars:</p>
122</dd> 122</dd>
123<dd> 123<dd>
124<pre> 124<pre>
125 URxvt.selection.pattern-0: \\|([^|]+)\\|</pre> 125 URxvt.selection.pattern-0: \\|([^|]+)\\|</pre>
… …
194onto <code>@{ $term-</code>{selection_popup_hook} }&gt;, which gets called whenever the 194onto <code>@{ $term-</code>{selection_popup_hook} }&gt;, which gets called whenever the
195popup is being displayed.</p> 195popup is being displayed.</p>
196</dd> 196</dd>
197<dd> 197<dd>
198<p>It's sole argument is the popup menu, which can be modified. The selection 198<p>It's sole argument is the popup menu, which can be modified. The selection
199is in <code>$_</code>, which can be used to decide wether to add something or not. 199is in <code>$_</code>, which can be used to decide whether to add something or not.
200It should either return nothing or a string and a code reference. The 200It should either return nothing or a string and a code reference. The
201string will be used as button text and the code reference will be called 201string will be used as button text and the code reference will be called
202when the button gets activated and should transform <code>$_</code>.</p> 202when the button gets activated and should transform <code>$_</code>.</p>
203</dd> 203</dd>
204<dd> 204<dd>
… …
317</li> 317</li>
318<dt><strong><a name="item_tabbed">tabbed</a></strong> 318<dt><strong><a name="item_tabbed">tabbed</a></strong>
319 319
320<dd> 320<dd>
321<p>This transforms the terminal into a tabbar with additional terminals, that 321<p>This transforms the terminal into a tabbar with additional terminals, that
322is, it implements what is commonly refered to as ``tabbed terminal''. The topmost line 322is, it implements what is commonly referred to as ``tabbed terminal''. The topmost line
323displays a ``[NEW]'' button, which, when clicked, will add a new tab, followed by one 323displays a ``[NEW]'' button, which, when clicked, will add a new tab, followed by one
324button per tab.</p> 324button per tab.</p>
325</dd> 325</dd>
326<dd> 326<dd>
327<p>Clicking a button will activate that tab. Pressing <strong>Shift-Left</strong> and 327<p>Clicking a button will activate that tab. Pressing <strong>Shift-Left</strong> and
… …
386<dd> 386<dd>
387<p>This is useful if you need a single terminal thats not using any desktop 387<p>This is useful if you need a single terminal thats not using any desktop
388space most of the time but is quickly available at the press of a key.</p> 388space most of the time but is quickly available at the press of a key.</p>
389</dd> 389</dd>
390<dd> 390<dd>
391<p>The accelerator key is grabbed regardless of any modifers, so this 391<p>The accelerator key is grabbed regardless of any modifiers, so this
392extension will actually grab a physical key just for this function.</p> 392extension will actually grab a physical key just for this function.</p>
393</dd> 393</dd>
394<dd> 394<dd>
395<p>If you want a quake-like animation, tell your window manager to do so 395<p>If you want a quake-like animation, tell your window manager to do so
396(fvwm can do it).</p> 396(fvwm can do it).</p>
… …
400 400
401<dd> 401<dd>
402<p>This is basically a very small extension that dynamically changes the 402<p>This is basically a very small extension that dynamically changes the
403background pixmap offset to the window position, in effect creating the 403background pixmap offset to the window position, in effect creating the
404same effect as pseudo transparency with a custom pixmap. No scaling is 404same effect as pseudo transparency with a custom pixmap. No scaling is
405supported in this mode. Exmaple:</p> 405supported in this mode. Example:</p>
406</dd> 406</dd>
407<dd> 407<dd>
408<pre> 408<pre>
409 rxvt -pixmap background.xpm -pe automove-background</pre> 409 rxvt -pixmap background.xpm -pe automove-background</pre>
410</dd> 410</dd>
… …
581<p> 581<p>
582</p> 582</p>
583<h2><a name="hooks">Hooks</a></h2> 583<h2><a name="hooks">Hooks</a></h2>
584<p>The following subroutines can be declared in extension files, and will be 584<p>The following subroutines can be declared in extension files, and will be
585called whenever the relevant event happens.</p> 585called whenever the relevant event happens.</p>
586<p>The first argument passed to them is an extension oject as described in 586<p>The first argument passed to them is an extension object as described in
587the in the <code>Extension Objects</code> section.</p> 587the in the <code>Extension Objects</code> section.</p>
588<p><strong>All</strong> of these hooks must return a boolean value. If any of the called 588<p><strong>All</strong> of these hooks must return a boolean value. If any of the called
589hooks returns true, then the event counts as being <em>consumed</em>, and the 589hooks returns true, then the event counts as being <em>consumed</em>, and the
590relevant action might not be carried out by the C++ code.</p> 590relevant action might not be carried out by the C++ code.</p>
591<p><em>When in doubt, return a false value (preferably <code>()</code>). </em>&gt;</p> 591<p><em>When in doubt, return a false value (preferably <code>()</code>). </em>&gt;</p>
… …
603</li> 603</li>
604<dt><strong><a name="item_on_start__24term">on_start $term</a></strong> 604<dt><strong><a name="item_on_start__24term">on_start $term</a></strong>
605 605
606<dd> 606<dd>
607<p>Called at the very end of initialisation of a new terminal, just before 607<p>Called at the very end of initialisation of a new terminal, just before
608trying to map (display) the toplevel and returning to the mainloop.</p> 608trying to map (display) the toplevel and returning to the main loop.</p>
609</dd> 609</dd>
610</li> 610</li>
611<dt><strong><a name="item_on_destroy__24term">on_destroy $term</a></strong> 611<dt><strong><a name="item_on_destroy__24term">on_destroy $term</a></strong>
612 612
613<dd> 613<dd>
… …
654<p>Called whenever a selection has been copied, but before the selection is 654<p>Called whenever a selection has been copied, but before the selection is
655requested from the server. The selection text can be queried and changed 655requested from the server. The selection text can be queried and changed
656by calling <a href="#item_selection"><code>$term-&gt;selection</code></a>.</p> 656by calling <a href="#item_selection"><code>$term-&gt;selection</code></a>.</p>
657</dd> 657</dd>
658<dd> 658<dd>
659<p>Returning a true value aborts selection grabbing. It will still be hilighted.</p> 659<p>Returning a true value aborts selection grabbing. It will still be highlighted.</p>
660</dd> 660</dd>
661</li> 661</li>
662<dt><strong><a name="item_on_sel_extend__24term">on_sel_extend $term</a></strong> 662<dt><strong><a name="item_on_sel_extend__24term">on_sel_extend $term</a></strong>
663 663
664<dd> 664<dd>
665<p>Called whenever the user tries to extend the selection (e.g. with a double 665<p>Called whenever the user tries to extend the selection (e.g. with a double
666click) and is either supposed to return false (normal operation), or 666click) and is either supposed to return false (normal operation), or
667should extend the selection itelf and return true to suppress the built-in 667should extend the selection itself and return true to suppress the built-in
668processing. This can happen multiple times, as long as the callback 668processing. This can happen multiple times, as long as the callback
669returns true, it will be called on every further click by the user and is 669returns true, it will be called on every further click by the user and is
670supposed to enlarge the selection more and more, if possible.</p> 670supposed to enlarge the selection more and more, if possible.</p>
671</dd> 671</dd>
672<dd> 672<dd>
… …
674</dd> 674</dd>
675</li> 675</li>
676<dt><strong><a name="item_on_view_change__24term_2c__24offset">on_view_change $term, $offset</a></strong> 676<dt><strong><a name="item_on_view_change__24term_2c__24offset">on_view_change $term, $offset</a></strong>
677 677
678<dd> 678<dd>
679<p>Called whenever the view offset changes, i..e the user or program 679<p>Called whenever the view offset changes, i.e. the user or program
680scrolls. Offset <code>0</code> means display the normal terminal, positive values 680scrolls. Offset <code>0</code> means display the normal terminal, positive values
681show this many lines of scrollback.</p> 681show this many lines of scrollback.</p>
682</dd> 682</dd>
683</li> 683</li>
684<dt><strong><a name="item_on_scroll_back__24term_2c__24lines_2c__24saved">on_scroll_back $term, $lines, $saved</a></strong> 684<dt><strong><a name="item_on_scroll_back__24term_2c__24lines_2c__24saved">on_scroll_back $term, $lines, $saved</a></strong>
… …
717it from commands for other extensions, and this might be enforced in the 717it from commands for other extensions, and this might be enforced in the
718future.</p> 718future.</p>
719</dd> 719</dd>
720<dd> 720<dd>
721<p>Be careful not ever to trust (in a security sense) the data you receive, 721<p>Be careful not ever to trust (in a security sense) the data you receive,
722as its source can not easily be controleld (e-mail content, messages from 722as its source can not easily be controlled (e-mail content, messages from
723other users on the same system etc.).</p> 723other users on the same system etc.).</p>
724</dd> 724</dd>
725</li> 725</li>
726<dt><strong><a name="item_on_add_lines__24term_2c__24string">on_add_lines $term, $string</a></strong> 726<dt><strong><a name="item_on_add_lines__24term_2c__24string">on_add_lines $term, $string</a></strong>
727 727
… …
774</dd> 774</dd>
775</li> 775</li>
776<dt><strong><a name="item_on_user_command__24term_2c__24string">on_user_command $term, $string</a></strong> 776<dt><strong><a name="item_on_user_command__24term_2c__24string">on_user_command $term, $string</a></strong>
777 777
778<dd> 778<dd>
779<p>Called whenever the a user-configured event is being activated (e.g. via 779<p>Called whenever a user-configured event is being activated (e.g. via
780a <code>perl:string</code> action bound to a key, see description of the <strong>keysym</strong> 780a <code>perl:string</code> action bound to a key, see description of the <strong>keysym</strong>
781resource in the <code>rxvt(1)</code> manpage).</p> 781resource in the <code>rxvt(1)</code> manpage).</p>
782</dd> 782</dd>
783<dd> 783<dd>
784<p>The event is simply the action string. This interface is assumed to change 784<p>The event is simply the action string. This interface is assumed to change
… …
786</dd> 786</dd>
787</li> 787</li>
788<dt><strong><a name="item_on_resize_all_windows__24tern_2c__24new_width_2c__">on_resize_all_windows $tern, $new_width, $new_height</a></strong> 788<dt><strong><a name="item_on_resize_all_windows__24tern_2c__24new_width_2c__">on_resize_all_windows $tern, $new_width, $new_height</a></strong>
789 789
790<dd> 790<dd>
791<p>Called just after the new window size has been calculcated, but before 791<p>Called just after the new window size has been calculated, but before
792windows are actually being resized or hints are being set. If this hook 792windows are actually being resized or hints are being set. If this hook
793returns TRUE, setting of the window hints is being skipped.</p> 793returns TRUE, setting of the window hints is being skipped.</p>
794</dd> 794</dd>
795</li> 795</li>
796<dt><strong><a name="item_on_x_event__24term_2c__24event">on_x_event $term, $event</a></strong> 796<dt><strong><a name="item_on_x_event__24term_2c__24event">on_x_event $term, $event</a></strong>
… …
815</dd> 815</dd>
816</li> 816</li>
817<dt><strong><a name="item_on_focus_out__24term">on_focus_out $term</a></strong> 817<dt><strong><a name="item_on_focus_out__24term">on_focus_out $term</a></strong>
818 818
819<dd> 819<dd>
820<p>Called wheneever the window loses keyboard focus, before rxvt-unicode does 820<p>Called whenever the window loses keyboard focus, before rxvt-unicode does
821focus out processing.</p> 821focus out processing.</p>
822</dd> 822</dd>
823</li> 823</li>
824<dt><strong><a name="item_on_configure_notify__24term_2c__24event">on_configure_notify $term, $event</a></strong> 824<dt><strong><a name="item_on_configure_notify__24term_2c__24event">on_configure_notify $term, $event</a></strong>
825 825
… …
899</dd> 899</dd>
900</li> 900</li>
901<dt><strong><a name="item__urxvt__term_init">@urxvt::TERM_INIT</a></strong> 901<dt><strong><a name="item__urxvt__term_init">@urxvt::TERM_INIT</a></strong>
902 902
903<dd> 903<dd>
904<p>All coderefs in this array will be called as methods of the next newly 904<p>All code references in this array will be called as methods of the next newly
905created <code>urxvt::term</code> object (during the <code>on_init</code> phase). The array 905created <code>urxvt::term</code> object (during the <code>on_init</code> phase). The array
906gets cleared before the codereferences that were in it are being executed, 906gets cleared before the code references that were in it are being executed,
907so coderefs can push themselves onto it again if they so desire.</p> 907so references can push themselves onto it again if they so desire.</p>
908</dd>
909<dd> 908</dd>
909<dd>
910<p>This complements to the perl-eval commandline option, but gets executed 910<p>This complements to the perl-eval command line option, but gets executed
911first.</p> 911first.</p>
912</dd> 912</dd>
913</li> 913</li>
914<dt><strong><a name="item__urxvt__term_ext">@urxvt::TERM_EXT</a></strong> 914<dt><strong><a name="item__urxvt__term_ext">@urxvt::TERM_EXT</a></strong>
915 915
… …
949</li> 949</li>
950<dt><strong><a name="item__terms">@terms = urxvt::termlist</a></strong> 950<dt><strong><a name="item__terms">@terms = urxvt::termlist</a></strong>
951 951
952<dd> 952<dd>
953<p>Returns all urxvt::term objects that exist in this process, regardless of 953<p>Returns all urxvt::term objects that exist in this process, regardless of
954wether they are started, being destroyed etc., so be careful. Only term 954whether they are started, being destroyed etc., so be careful. Only term
955objects that have perl extensions attached will be returned (because there 955objects that have perl extensions attached will be returned (because there
956is no urxvt::term objet associated with others).</p> 956is no urxvt::term objet associated with others).</p>
957</dd> 957</dd>
958</li> 958</li>
959<dt><strong><a name="item__time">$time = urxvt::NOW</a></strong> 959<dt><strong><a name="item__time">$time = urxvt::NOW</a></strong>
… …
1108<p>Returns true if the option specified by <code>$optval</code> is enabled, and 1108<p>Returns true if the option specified by <code>$optval</code> is enabled, and
1109optionally change it. All option values are stored by name in the hash 1109optionally change it. All option values are stored by name in the hash
1110<code>%urxvt::OPTION</code>. Options not enabled in this binary are not in the hash.</p> 1110<code>%urxvt::OPTION</code>. Options not enabled in this binary are not in the hash.</p>
1111</dd> 1111</dd>
1112<dd> 1112<dd>
1113<p>Here is a a likely non-exhaustive list of option names, please see the 1113<p>Here is a likely non-exhaustive list of option names, please see the
1114source file <em>/src/optinc.h</em> to see the actual list:</p> 1114source file <em>/src/optinc.h</em> to see the actual list:</p>
1115</dd> 1115</dd>
1116<dd> 1116<dd>
1117<pre> 1117<pre>
1118 borderLess console cursorBlink cursorUnderline hold iconic insecure 1118 borderLess console cursorBlink cursorUnderline hold iconic insecure
… …
1143<dd> 1143<dd>
1144<p>Please note that resource strings will currently only be freed when the 1144<p>Please note that resource strings will currently only be freed when the
1145terminal is destroyed, so changing options frequently will eat memory.</p> 1145terminal is destroyed, so changing options frequently will eat memory.</p>
1146</dd> 1146</dd>
1147<dd> 1147<dd>
1148<p>Here is a a likely non-exhaustive list of resource names, not all of which 1148<p>Here is a likely non-exhaustive list of resource names, not all of which
1149are supported in every build, please see the source file <em>/src/rsinc.h</em> 1149are supported in every build, please see the source file <em>/src/rsinc.h</em>
1150to see the actual list:</p> 1150to see the actual list:</p>
1151</dd> 1151</dd>
1152<dd> 1152<dd>
1153<pre> 1153<pre>
… …
1500</dd> 1500</dd>
1501</li> 1501</li>
1502<dt><strong><a name="item_hidden_cursor">$cursor_is_hidden = $term-&gt;hidden_cursor</a></strong> 1502<dt><strong><a name="item_hidden_cursor">$cursor_is_hidden = $term-&gt;hidden_cursor</a></strong>
1503 1503
1504<dd> 1504<dd>
1505<p>Returns wether the cursor is currently hidden or not.</p> 1505<p>Returns whether the cursor is currently hidden or not.</p>
1506</dd> 1506</dd>
1507</li> 1507</li>
1508<dt><strong><a name="item_view_start">$view_start = $term-&gt;view_start ([$newvalue])</a></strong> 1508<dt><strong><a name="item_view_start">$view_start = $term-&gt;view_start ([$newvalue])</a></strong>
1509 1509
1510<dd> 1510<dd>
… …
1645</dd> 1645</dd>
1646</li> 1646</li>
1647<dt><strong><a name="item_special_decode">$string = $term-&gt;special_decode $text</a></strong> 1647<dt><strong><a name="item_special_decode">$string = $term-&gt;special_decode $text</a></strong>
1648 1648
1649<dd> 1649<dd>
1650<p>Converts rxvt-unicodes text reprsentation into a perl string. See 1650<p>Converts rxvt-unicodes text representation into a perl string. See
1651<a href="#item_row_t"><code>$term-&gt;ROW_t</code></a> for details.</p> 1651<a href="#item_row_t"><code>$term-&gt;ROW_t</code></a> for details.</p>
1652</dd> 1652</dd>
1653</li> 1653</li>
1654<dt><strong><a name="item_grab_button">$success = $term-&gt;grab_button ($button, $modifiermask[, $window = $term-&gt;vt])</a></strong> 1654<dt><strong><a name="item_grab_button">$success = $term-&gt;grab_button ($button, $modifiermask[, $window = $term-&gt;vt])</a></strong>
1655 1655
… …
1662</li> 1662</li>
1663<dt><strong><a name="item_grab">$success = $term-&gt;grab ($eventtime[, $sync])</a></strong> 1663<dt><strong><a name="item_grab">$success = $term-&gt;grab ($eventtime[, $sync])</a></strong>
1664 1664
1665<dd> 1665<dd>
1666<p>Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1666<p>Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1667synchronous (<code>$sync</code> is true). Also remembers the grab timestampe.</p> 1667synchronous (<code>$sync</code> is true). Also remembers the grab timestamp.</p>
1668</dd> 1668</dd>
1669</li> 1669</li>
1670<dt><strong><a name="item_allow_events_async">$term-&gt;allow_events_async</a></strong> 1670<dt><strong><a name="item_allow_events_async">$term-&gt;allow_events_async</a></strong>
1671 1671
1672<dd> 1672<dd>
… …
1870</dd> 1870</dd>
1871</li> 1871</li>
1872<dt><strong><a name="item_fd">$iow = $iow-&gt;fd ($fd)</a></strong> 1872<dt><strong><a name="item_fd">$iow = $iow-&gt;fd ($fd)</a></strong>
1873 1873
1874<dd> 1874<dd>
1875<p>Set the filedescriptor (not handle) to watch.</p> 1875<p>Set the file descriptor (not handle) to watch.</p>
1876</dd> 1876</dd>
1877</li> 1877</li>
1878<dt><strong><a name="item_events">$iow = $iow-&gt;events ($eventmask)</a></strong> 1878<dt><strong><a name="item_events">$iow = $iow-&gt;events ($eventmask)</a></strong>
1879 1879
1880<dd> 1880<dd>
… …
1890</dd> 1890</dd>
1891</li> 1891</li>
1892<dt><strong>$iow = $iow-&gt;stop</strong> 1892<dt><strong>$iow = $iow-&gt;stop</strong>
1893 1893
1894<dd> 1894<dd>
1895<p>Stop watching for events on the given filehandle.</p> 1895<p>Stop watching for events on the given file handle.</p>
1896</dd> 1896</dd>
1897</li> 1897</li>
1898</dl> 1898</dl>
1899<p> 1899<p>
1900</p> 1900</p>
… …
1957</dd> 1957</dd>
1958</li> 1958</li>
1959<dt><strong>$pw = $timer-&gt;start ($pid)</strong> 1959<dt><strong>$pw = $timer-&gt;start ($pid)</strong>
1960 1960
1961<dd> 1961<dd>
1962<p>Tells the wqtcher to start watching for process <code>$pid</code>.</p> 1962<p>Tells the watcher to start watching for process <code>$pid</code>.</p>
1963</dd> 1963</dd>
1964</li> 1964</li>
1965<dt><strong>$pw = $pw-&gt;stop</strong> 1965<dt><strong>$pw = $pw-&gt;stop</strong>
1966 1966
1967<dd> 1967<dd>
… …
1983 1983
1984<dt><strong><a name="item__3e_3d_3__2d_script_loading_and_management">&gt;= 3 - script loading and management</a></strong> 1984<dt><strong><a name="item__3e_3d_3__2d_script_loading_and_management">&gt;= 3 - script loading and management</a></strong>
1985 1985
1986<dt><strong><a name="item__3e_3d10__2d_all_called_hooks">&gt;=10 - all called hooks</a></strong> 1986<dt><strong><a name="item__3e_3d10__2d_all_called_hooks">&gt;=10 - all called hooks</a></strong>
1987 1987
1988<dt><strong><a name="item__3e_3d11__2d_hook_reutrn_values">&gt;=11 - hook reutrn values</a></strong> 1988<dt><strong><a name="item__3e_3d11__2d_hook_return_values">&gt;=11 - hook return values</a></strong>
1989 1989
1990</dl> 1990</dl>
1991<p> 1991<p>
1992</p> 1992</p>
1993<hr /> 1993<hr />

Diff Legend

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