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.142 by root, Thu Jul 6 18:56:10 2006 UTC vs.
Revision 1.147 by root, Tue Oct 3 11:32: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
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,
240 URxvt.tabbed.tab-bg: <colour-index, default 1> 240 URxvt.tabbed.tab-bg: <colour-index, default 1>
241 241
242See I<COLOR AND GRAPHICS> in the @@RXVT_NAME@@(1) manpage for valid 242See I<COLOR AND GRAPHICS> in the @@RXVT_NAME@@(1) manpage for valid
243indices. 243indices.
244 244
245=item mark-urls 245=item matcher
246 246
247Uses per-line display filtering (C<on_line_update>) to underline urls and 247Uses per-line display filtering (C<on_line_update>) to underline text
248make them clickable. When middle-clicked, the program specified in the 248matching a certain pattern and make it clickable. When clicked with the
249resource C<urlLauncher> (default C<x-www-browser>) will be started with 249mouse button specified in the C<matcher.button> resource (default 2, or
250the URL as first argument. 250middle), the program specified in the C<matcher.launcher> resource
251(default, the C<urlLauncher> resource, C<sensible-browser>) will be started
252with the matched text as first argument. The default configuration is
253suitable for matching URLs and launching a web browser, like the
254former "mark-urls" extension.
255
256The default pattern to match URLs can be overridden with the
257C<matcher.pattern.0> resource, and additional patterns can be specified
258with numbered patterns, in a manner similar to the "selection" extension.
259The launcher can also be overridden on a per-pattern basis.
260
261Example configuration:
262
263 URxvt.perl-ext: default,matcher
264 URxvt.urlLauncher: sensible-browser
265 URxvt.matcher.button: 1
266 URxvt.matcher.pattern.1: \\bwww\\.[\\w-]\\.[\\w./?&@#-]*[\\w/-]
267 URxvt.matcher.pattern.2: \\B(/\\S+?):(\\d+)(?=:|$)
268 URxvt.matcher.launcher.2: gvim +$2 $1
251 269
252=item xim-onthespot 270=item xim-onthespot
253 271
254This (experimental) perl extension implements OnTheSpot editing. It does 272This (experimental) perl extension implements OnTheSpot editing. It does
255not work perfectly, and some input methods don't seem to work well with 273not work perfectly, and some input methods don't seem to work well with
259You enable it by specifying this extension and a preedit style of 277You enable it by specifying this extension and a preedit style of
260C<OnTheSpot>, i.e.: 278C<OnTheSpot>, i.e.:
261 279
262 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot 280 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot
263 281
282=item kuake<hotkey>
283
284A very primitive quake-console-like extension. It was inspired by a
285description of how the programs C<kuake> and C<yakuake> work: Whenever the
286user presses a global accelerator key (by default C<F10>), the terminal
287will show or hide itself. Another press of the accelerator key will hide
288or show it again.
289
290Initially, the window will not be shown when using this extension.
291
292This is useful if you need a single terminal thats not using any desktop
293space most of the time but is quickly available at the press of a key.
294
295The accelerator key is grabbed regardless of any modifiers, so this
296extension will actually grab a physical key just for this function.
297
298If you want a quake-like animation, tell your window manager to do so
299(fvwm can do it).
300
264=item automove-background 301=item automove-background
265 302
266This is basically a very small extension that dynamically changes the 303This is basically a very small extension that dynamically changes the
267background pixmap offset to the window position, in effect creating the 304background pixmap offset to the window position, in effect creating the
268same effect as pseudo transparency with a custom pixmap. No scaling is 305same effect as pseudo transparency with a custom pixmap. No scaling is
269supported in this mode. Exmaple: 306supported in this mode. Example:
270 307
271 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background 308 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background
272 309
273=item block-graphics-to-ascii 310=item block-graphics-to-ascii
274 311
326After a successful upload the selection will be replaced by the text given 363After a successful upload the selection will be replaced by the text given
327in the C<selection-pastebin-url> resource (again, the % is the placeholder 364in the C<selection-pastebin-url> resource (again, the % is the placeholder
328for the filename): 365for the filename):
329 366
330 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/% 367 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
368
369I<Note to xrdb users:> xrdb uses the C preprocessor, which might interpret
370the double C</> characters as comment start. Use C<\057\057> instead,
371which works regardless of wether xrdb is used to parse the resource file
372or not.
331 373
332=item example-refresh-hooks 374=item example-refresh-hooks
333 375
334Displays a very simple digital clock in the upper right corner of the 376Displays a very simple digital clock in the upper right corner of the
335window. Illustrates overwriting the refresh callbacks to create your own 377window. Illustrates overwriting the refresh callbacks to create your own
376=back 418=back
377 419
378=head2 Extension Objects 420=head2 Extension Objects
379 421
380Every perl extension is a perl class. A separate perl object is created 422Every perl extension is a perl class. A separate perl object is created
381for each terminal and each extension and passed as the first parameter to 423for each terminal, and each terminal has its own set of extenion objects,
382hooks. So extensions can use their C<$self> object without having to think 424which are passed as the first parameter to hooks. So extensions can use
383about other extensions, with the exception of methods and members that 425their C<$self> object without having to think about clashes with other
426extensions or other terminals, with the exception of methods and members
384begin with an underscore character C<_>: these are reserved for internal 427that begin with an underscore character C<_>: these are reserved for
385use. 428internal use.
386 429
387Although it isn't a C<urxvt::term> object, you can call all methods of the 430Although it isn't a C<urxvt::term> object, you can call all methods of the
388C<urxvt::term> class on this object. 431C<urxvt::term> class on this object.
389 432
390It has the following methods and data members: 433It has the following methods and data members:
411=head2 Hooks 454=head2 Hooks
412 455
413The following subroutines can be declared in extension files, and will be 456The following subroutines can be declared in extension files, and will be
414called whenever the relevant event happens. 457called whenever the relevant event happens.
415 458
416The first argument passed to them is an extension oject as described in 459The first argument passed to them is an extension object as described in
417the in the C<Extension Objects> section. 460the in the C<Extension Objects> section.
418 461
419B<All> of these hooks must return a boolean value. If any of the called 462B<All> of these hooks must return a boolean value. If any of the called
420hooks returns true, then the event counts as being I<consumed>, and the 463hooks returns true, then the event counts as being I<consumed>, and the
421relevant action might not be carried out by the C++ code. 464relevant action might not be carried out by the C++ code.
434place. 477place.
435 478
436=item on_start $term 479=item on_start $term
437 480
438Called at the very end of initialisation of a new terminal, just before 481Called at the very end of initialisation of a new terminal, just before
439trying to map (display) the toplevel and returning to the mainloop. 482trying to map (display) the toplevel and returning to the main loop.
440 483
441=item on_destroy $term 484=item on_destroy $term
442 485
443Called whenever something tries to destroy terminal, when the terminal is 486Called whenever something tries to destroy terminal, when the terminal is
444still fully functional (not for long, though). 487still fully functional (not for long, though).
471 514
472Called whenever a selection has been copied, but before the selection is 515Called whenever a selection has been copied, but before the selection is
473requested from the server. The selection text can be queried and changed 516requested from the server. The selection text can be queried and changed
474by calling C<< $term->selection >>. 517by calling C<< $term->selection >>.
475 518
476Returning a true value aborts selection grabbing. It will still be hilighted. 519Returning a true value aborts selection grabbing. It will still be highlighted.
477 520
478=item on_sel_extend $term 521=item on_sel_extend $term
479 522
480Called whenever the user tries to extend the selection (e.g. with a double 523Called whenever the user tries to extend the selection (e.g. with a double
481click) and is either supposed to return false (normal operation), or 524click) and is either supposed to return false (normal operation), or
482should extend the selection itelf and return true to suppress the built-in 525should extend the selection itself and return true to suppress the built-in
483processing. This can happen multiple times, as long as the callback 526processing. This can happen multiple times, as long as the callback
484returns true, it will be called on every further click by the user and is 527returns true, it will be called on every further click by the user and is
485supposed to enlarge the selection more and more, if possible. 528supposed to enlarge the selection more and more, if possible.
486 529
487See the F<selection> example extension. 530See the F<selection> example extension.
488 531
489=item on_view_change $term, $offset 532=item on_view_change $term, $offset
490 533
491Called whenever the view offset changes, i..e the user or program 534Called whenever the view offset changes, i.e. the user or program
492scrolls. Offset C<0> means display the normal terminal, positive values 535scrolls. Offset C<0> means display the normal terminal, positive values
493show this many lines of scrollback. 536show this many lines of scrollback.
494 537
495=item on_scroll_back $term, $lines, $saved 538=item on_scroll_back $term, $lines, $saved
496 539
520string should start with the extension name and a colon, to distinguish 563string should start with the extension name and a colon, to distinguish
521it from commands for other extensions, and this might be enforced in the 564it from commands for other extensions, and this might be enforced in the
522future. 565future.
523 566
524Be careful not ever to trust (in a security sense) the data you receive, 567Be careful not ever to trust (in a security sense) the data you receive,
525as its source can not easily be controleld (e-mail content, messages from 568as its source can not easily be controlled (e-mail content, messages from
526other users on the same system etc.). 569other users on the same system etc.).
527 570
528=item on_add_lines $term, $string 571=item on_add_lines $term, $string
529 572
530Called whenever text is about to be output, with the text as argument. You 573Called whenever text is about to be output, with the text as argument. You
563 606
564Called just after the screen gets redrawn. See C<on_refresh_begin>. 607Called just after the screen gets redrawn. See C<on_refresh_begin>.
565 608
566=item on_user_command $term, $string 609=item on_user_command $term, $string
567 610
568Called whenever the a user-configured event is being activated (e.g. via 611Called whenever a user-configured event is being activated (e.g. via
569a C<perl:string> action bound to a key, see description of the B<keysym> 612a C<perl:string> action bound to a key, see description of the B<keysym>
570resource in the @@RXVT_NAME@@(1) manpage). 613resource in the @@RXVT_NAME@@(1) manpage).
571 614
572The event is simply the action string. This interface is assumed to change 615The event is simply the action string. This interface is assumed to change
573slightly in the future. 616slightly in the future.
574 617
575=item on_resize_all_windows $tern, $new_width, $new_height 618=item on_resize_all_windows $tern, $new_width, $new_height
576 619
577Called just after the new window size has been calculcated, but before 620Called just after the new window size has been calculated, but before
578windows are actually being resized or hints are being set. If this hook 621windows are actually being resized or hints are being set. If this hook
579returns TRUE, setting of the window hints is being skipped. 622returns TRUE, setting of the window hints is being skipped.
580 623
581=item on_x_event $term, $event 624=item on_x_event $term, $event
582 625
583Called on every X event received on the vt window (and possibly other 626Called on every X event received on the vt window (and possibly other
584windows). Should only be used as a last resort. Most event structure 627windows). Should only be used as a last resort. Most event structure
585members are not passed. 628members are not passed.
586 629
630=item on_root_event $term, $event
631
632Like C<on_x_event>, but is called for events on the root window.
633
587=item on_focus_in $term 634=item on_focus_in $term
588 635
589Called whenever the window gets the keyboard focus, before rxvt-unicode 636Called whenever the window gets the keyboard focus, before rxvt-unicode
590does focus in processing. 637does focus in processing.
591 638
592=item on_focus_out $term 639=item on_focus_out $term
593 640
594Called wheneever the window loses keyboard focus, before rxvt-unicode does 641Called whenever the window loses keyboard focus, before rxvt-unicode does
595focus out processing. 642focus out processing.
596 643
597=item on_configure_notify $term, $event 644=item on_configure_notify $term, $event
598 645
599=item on_property_notify $term, $event 646=item on_property_notify $term, $event
682The current terminal. This variable stores the current C<urxvt::term> 729The current terminal. This variable stores the current C<urxvt::term>
683object, whenever a callback/hook is executing. 730object, whenever a callback/hook is executing.
684 731
685=item @urxvt::TERM_INIT 732=item @urxvt::TERM_INIT
686 733
687All coderefs in this array will be called as methods of the next newly 734All code references in this array will be called as methods of the next newly
688created C<urxvt::term> object (during the C<on_init> phase). The array 735created C<urxvt::term> object (during the C<on_init> phase). The array
689gets cleared before the codereferences that were in it are being executed, 736gets cleared before the code references that were in it are being executed,
690so coderefs can push themselves onto it again if they so desire. 737so references can push themselves onto it again if they so desire.
691 738
692This complements to the perl-eval commandline option, but gets executed 739This complements to the perl-eval command line option, but gets executed
693first. 740first.
694 741
695=item @urxvt::TERM_EXT 742=item @urxvt::TERM_EXT
696 743
697Works similar to C<@TERM_INIT>, but contains perl package/class names, which 744Works similar to C<@TERM_INIT>, but contains perl package/class names, which
722Messages have a size limit of 1023 bytes currently. 769Messages have a size limit of 1023 bytes currently.
723 770
724=item @terms = urxvt::termlist 771=item @terms = urxvt::termlist
725 772
726Returns all urxvt::term objects that exist in this process, regardless of 773Returns all urxvt::term objects that exist in this process, regardless of
727wether they are started, being destroyed etc., so be careful. Only term 774whether they are started, being destroyed etc., so be careful. Only term
728objects that have perl extensions attached will be returned (because there 775objects that have perl extensions attached will be returned (because there
729is no urxvt::term objet associated with others). 776is no urxvt::term objet associated with others).
730 777
731=item $time = urxvt::NOW 778=item $time = urxvt::NOW
732 779
1170 1217
1171Returns true if the option specified by C<$optval> is enabled, and 1218Returns true if the option specified by C<$optval> is enabled, and
1172optionally change it. All option values are stored by name in the hash 1219optionally change it. All option values are stored by name in the hash
1173C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash. 1220C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
1174 1221
1175Here is a a likely non-exhaustive list of option names, please see the 1222Here is a likely non-exhaustive list of option names, please see the
1176source file F</src/optinc.h> to see the actual list: 1223source file F</src/optinc.h> to see the actual list:
1177 1224
1178 borderLess console cursorBlink cursorUnderline hold iconic insecure 1225 borderLess console cursorBlink cursorUnderline hold iconic insecure
1179 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 1226 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
1180 override-redirect pastableTabs pointerBlank reverseVideo scrollBar 1227 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
1197likely change). 1244likely change).
1198 1245
1199Please note that resource strings will currently only be freed when the 1246Please note that resource strings will currently only be freed when the
1200terminal is destroyed, so changing options frequently will eat memory. 1247terminal is destroyed, so changing options frequently will eat memory.
1201 1248
1202Here is a a likely non-exhaustive list of resource names, not all of which 1249Here is a likely non-exhaustive list of resource names, not all of which
1203are supported in every build, please see the source file F</src/rsinc.h> 1250are supported in every build, please see the source file F</src/rsinc.h>
1204to see the actual list: 1251to see the actual list:
1205 1252
1206 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1253 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
1207 borderLess color cursorBlink cursorUnderline cutchars delete_key 1254 borderLess color cursorBlink cursorUnderline cutchars delete_key
1519 1566
1520Returns the currently displayed screen (0 primary, 1 secondary). 1567Returns the currently displayed screen (0 primary, 1 secondary).
1521 1568
1522=item $cursor_is_hidden = $term->hidden_cursor 1569=item $cursor_is_hidden = $term->hidden_cursor
1523 1570
1524Returns wether the cursor is currently hidden or not. 1571Returns whether the cursor is currently hidden or not.
1525 1572
1526=item $view_start = $term->view_start ([$newvalue]) 1573=item $view_start = $term->view_start ([$newvalue])
1527 1574
1528Returns the row number of the topmost displayed line. Maximum value is 1575Returns the row number of the topmost displayed line. Maximum value is
1529C<0>, which displays the normal terminal contents. Lower values scroll 1576C<0>, which displays the normal terminal contents. Lower values scroll
1706where one character corresponds to one screen cell. See 1753where one character corresponds to one screen cell. See
1707C<< $term->ROW_t >> for details. 1754C<< $term->ROW_t >> for details.
1708 1755
1709=item $string = $term->special_decode $text 1756=item $string = $term->special_decode $text
1710 1757
1711Converts rxvt-unicodes text reprsentation into a perl string. See 1758Converts rxvt-unicodes text representation into a perl string. See
1712C<< $term->ROW_t >> for details. 1759C<< $term->ROW_t >> for details.
1713 1760
1714=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt]) 1761=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1715 1762
1716=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt]) 1763=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1719manpage. 1766manpage.
1720 1767
1721=item $success = $term->grab ($eventtime[, $sync]) 1768=item $success = $term->grab ($eventtime[, $sync])
1722 1769
1723Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1770Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1724synchronous (C<$sync> is true). Also remembers the grab timestampe. 1771synchronous (C<$sync> is true). Also remembers the grab timestamp.
1725 1772
1726=item $term->allow_events_async 1773=item $term->allow_events_async
1727 1774
1728Calls XAllowEvents with AsyncBoth for the most recent grab. 1775Calls XAllowEvents with AsyncBoth for the most recent grab.
1729 1776
1996Set the callback to be called when io events are triggered. C<$reventmask> 2043Set the callback to be called when io events are triggered. C<$reventmask>
1997is a bitset as described in the C<events> method. 2044is a bitset as described in the C<events> method.
1998 2045
1999=item $iow = $iow->fd ($fd) 2046=item $iow = $iow->fd ($fd)
2000 2047
2001Set the filedescriptor (not handle) to watch. 2048Set the file descriptor (not handle) to watch.
2002 2049
2003=item $iow = $iow->events ($eventmask) 2050=item $iow = $iow->events ($eventmask)
2004 2051
2005Set the event mask to watch. The only allowed values are 2052Set the event mask to watch. The only allowed values are
2006C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed 2053C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed
2010 2057
2011Start watching for requested events on the given handle. 2058Start watching for requested events on the given handle.
2012 2059
2013=item $iow = $iow->stop 2060=item $iow = $iow->stop
2014 2061
2015Stop watching for events on the given filehandle. 2062Stop watching for events on the given file handle.
2016 2063
2017=back 2064=back
2018 2065
2019=head2 The C<urxvt::iw> Class 2066=head2 The C<urxvt::iw> Class
2020 2067
2067 2114
2068Set the callback to be called when the timer triggers. 2115Set the callback to be called when the timer triggers.
2069 2116
2070=item $pw = $timer->start ($pid) 2117=item $pw = $timer->start ($pid)
2071 2118
2072Tells the wqtcher to start watching for process C<$pid>. 2119Tells the watcher to start watching for process C<$pid>.
2073 2120
2074=item $pw = $pw->stop 2121=item $pw = $pw->stop
2075 2122
2076Stop the watcher. 2123Stop the watcher.
2077 2124
2090 2137
2091=item >= 3 - script loading and management 2138=item >= 3 - script loading and management
2092 2139
2093=item >=10 - all called hooks 2140=item >=10 - all called hooks
2094 2141
2095=item >=11 - hook reutrn values 2142=item >=11 - hook return values
2096 2143
2097=back 2144=back
2098 2145
2099=head1 AUTHOR 2146=head1 AUTHOR
2100 2147

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines