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.173 by root, Wed Nov 5 12:45:36 2008 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
28Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where 28Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where
29scripts will be shared (but not enabled) for all terminals. 29scripts will be shared (but not enabled) for all terminals.
30 30
31You can disable the embedded perl interpreter by setting both "perl-ext"
32and "perl-ext-common" resources to the empty string.
33
31=head1 PREPACKAGED EXTENSIONS 34=head1 PREPACKAGED EXTENSIONS
32 35
33This section describes the extensions delivered with this release. You can 36This section describes the extensions delivered with this release. You can
34find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>. 37find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>.
35 38
37 40
38 @@RXVT_NAME@@ -pe <extensionname> 41 @@RXVT_NAME@@ -pe <extensionname>
39 42
40Or by adding them to the resource for extensions loaded by default: 43Or by adding them to the resource for extensions loaded by default:
41 44
42 URxvt.perl-ext-common: default,automove-background,selection-autotransform 45 URxvt.perl-ext-common: default,selection-autotransform
43 46
44=over 4 47=over 4
45 48
46=item selection (enabled by default) 49=item selection (enabled by default)
47 50
62 URxvt.selection.pattern-1: perl-regex 65 URxvt.selection.pattern-1: perl-regex
63 ... 66 ...
64 67
65The index number (0, 1...) must not have any holes, and each regex must 68The 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 69contain at least one pair of capturing parentheses, which will be used for
67the match. For example, the followign adds a regex that matches everything 70the match. For example, the following adds a regex that matches everything
68between two vertical bars: 71between two vertical bars:
69 72
70 URxvt.selection.pattern-0: \\|([^|]+)\\| 73 URxvt.selection.pattern-0: \\|([^|]+)\\|
71 74
72Another example: Programs I use often output "absolute path: " at the 75Another example: Programs I use often output "absolute path: " at the
98 101
99Other extensions can extend this popup menu by pushing a code reference 102Other extensions can extend this popup menu by pushing a code reference
100onto C<@{ $term->{option_popup_hook} }>, which gets called whenever the 103onto C<@{ $term->{option_popup_hook} }>, which gets called whenever the
101popup is being displayed. 104popup is being displayed.
102 105
103It's sole argument is the popup menu, which can be modified. It should 106Its sole argument is the popup menu, which can be modified. It should
104either return nothing or a string, the initial boolean value and a code 107either return nothing or a string, the initial boolean value and a code
105reference. The string will be used as button text and the code reference 108reference. The string will be used as button text and the code reference
106will be called when the toggle changes, with the new boolean value as 109will be called when the toggle changes, with the new boolean value as
107first argument. 110first argument.
108 111
109The following will add an entry C<myoption> that changes 112The following will add an entry C<myoption> that changes
110C<$self->{myoption}>: 113C<< $self->{myoption} >>:
111 114
112 push @{ $self->{term}{option_popup_hook} }, sub { 115 push @{ $self->{term}{option_popup_hook} }, sub {
113 ("my option" => $myoption, sub { $self->{myoption} = $_[0] }) 116 ("my option" => $myoption, sub { $self->{myoption} = $_[0] })
114 }; 117 };
115 118
121 124
122Other extensions can extend this popup menu by pushing a code reference 125Other extensions can extend this popup menu by pushing a code reference
123onto C<@{ $term->{selection_popup_hook} }>, which gets called whenever the 126onto C<@{ $term->{selection_popup_hook} }>, which gets called whenever the
124popup is being displayed. 127popup is being displayed.
125 128
126It's sole argument is the popup menu, which can be modified. The selection 129Its 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. 130is 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 131It 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 132string will be used as button text and the code reference will be called
130when the button gets activated and should transform C<$_>. 133when the button gets activated and should transform C<$_>.
131 134
132The following will add an entry C<a to b> that transforms all C<a>s in 135The following will add an entry C<a to b> that transforms all C<a>s in
133the selection to C<b>s, but only if the selection currently contains any 136the selection to C<b>s, but only if the selection currently contains any
134C<a>s: 137C<a>s:
135 138
136 push @{ $self->{term}{selection_popup_hook} }, sub { 139 push @{ $self->{term}{selection_popup_hook} }, sub {
137 /a/ ? ("a to be" => sub { s/a/b/g } 140 /a/ ? ("a to b" => sub { s/a/b/g }
138 : () 141 : ()
139 }; 142 };
140 143
141=item searchable-scrollback<hotkey> (enabled by default) 144=item searchable-scrollback<hotkey> (enabled by default)
142 145
149search. C<BackSpace> removes a character from the regex, C<Up> and C<Down> 152search. C<BackSpace> removes a character from the regex, C<Up> and C<Down>
150search upwards/downwards in the scrollback buffer, C<End> jumps to the 153search upwards/downwards in the scrollback buffer, C<End> jumps to the
151bottom. C<Escape> leaves search mode and returns to the point where search 154bottom. 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 155was 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 156additionally stores the first match in the current line into the primary
154selection. 157selection if the C<Shift> modifier is active.
155 158
156The regex defaults to "(?i)", resulting in a case-insensitive search. To 159The regex defaults to "(?i)", resulting in a case-insensitive search. To
157get a case-sensitive search you can delete this prefix using C<BackSpace> 160get a case-sensitive search you can delete this prefix using C<BackSpace>
158or simply use an uppercase character which removes the "(?i)" prefix. 161or simply use an uppercase character which removes the "(?i)" prefix.
159 162
162=item readline (enabled by default) 165=item readline (enabled by default)
163 166
164A support package that tries to make editing with readline easier. At 167A support package that tries to make editing with readline easier. At
165the moment, it reacts to clicking shift-left mouse button by trying to 168the moment, it reacts to clicking shift-left mouse button by trying to
166move the text cursor to this position. It does so by generating as many 169move the text cursor to this position. It does so by generating as many
167cursor-left or cursor-right keypresses as required (the this only works 170cursor-left or cursor-right keypresses as required (this only works
168for programs that correctly support wide characters). 171for programs that correctly support wide characters).
169 172
170To avoid too many false positives, this is only done when: 173To avoid too many false positives, this is only done when:
171 174
172=over 4 175=over 4
220the message into vi commands to load the file. 223the message into vi commands to load the file.
221 224
222=item tabbed 225=item tabbed
223 226
224This transforms the terminal into a tabbar with additional terminals, that 227This transforms the terminal into a tabbar with additional terminals, that
225is, it implements what is commonly refered to as "tabbed terminal". The topmost line 228is, 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 229displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one
227button per tab. 230button per tab.
228 231
229Clicking a button will activate that tab. Pressing B<Shift-Left> and 232Clicking 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, 233B<Shift-Right> will switch to the tab left or right of the current one,
240 URxvt.tabbed.tab-bg: <colour-index, default 1> 243 URxvt.tabbed.tab-bg: <colour-index, default 1>
241 244
242See I<COLOR AND GRAPHICS> in the @@RXVT_NAME@@(1) manpage for valid 245See I<COLOR AND GRAPHICS> in the @@RXVT_NAME@@(1) manpage for valid
243indices. 246indices.
244 247
245=item mark-urls 248=item matcher
246 249
247Uses per-line display filtering (C<on_line_update>) to underline urls and 250Uses per-line display filtering (C<on_line_update>) to underline text
248make them clickable. When middle-clicked, the program specified in the 251matching a certain pattern and make it clickable. When clicked with the
249resource C<urlLauncher> (default C<x-www-browser>) will be started with 252mouse button specified in the C<matcher.button> resource (default 2, or
250the URL as first argument. 253middle), the program specified in the C<matcher.launcher> resource
254(default, the C<urlLauncher> resource, C<sensible-browser>) will be started
255with the matched text as first argument. The default configuration is
256suitable for matching URLs and launching a web browser, like the
257former "mark-urls" extension.
258
259The default pattern to match URLs can be overridden with the
260C<matcher.pattern.0> resource, and additional patterns can be specified
261with numbered patterns, in a manner similar to the "selection" extension.
262The launcher can also be overridden on a per-pattern basis.
263
264It is possible to activate the most recently seen match from the keyboard.
265Simply bind a keysym to "perl:matcher" as seen in the example below.
266
267Example configuration:
268
269 URxvt.perl-ext: default,matcher
270 URxvt.urlLauncher: sensible-browser
271 URxvt.keysym.C-Delete: perl:matcher
272 URxvt.matcher.button: 1
273 URxvt.matcher.pattern.1: \\bwww\\.[\\w-]+\\.[\\w./?&@#-]*[\\w/-]
274 URxvt.matcher.pattern.2: \\B(/\\S+?):(\\d+)(?=:|$)
275 URxvt.matcher.launcher.2: gvim +$2 $1
251 276
252=item xim-onthespot 277=item xim-onthespot
253 278
254This (experimental) perl extension implements OnTheSpot editing. It does 279This (experimental) perl extension implements OnTheSpot editing. It does
255not work perfectly, and some input methods don't seem to work well with 280not work perfectly, and some input methods don't seem to work well with
256OnTheSpot editing in general, but it seems to work at leats for SCIM and 281OnTheSpot editing in general, but it seems to work at least for SCIM and
257kinput2. 282kinput2.
258 283
259You enable it by specifying this extension and a preedit style of 284You enable it by specifying this extension and a preedit style of
260C<OnTheSpot>, i.e.: 285C<OnTheSpot>, i.e.:
261 286
269will show or hide itself. Another press of the accelerator key will hide 294will show or hide itself. Another press of the accelerator key will hide
270or show it again. 295or show it again.
271 296
272Initially, the window will not be shown when using this extension. 297Initially, the window will not be shown when using this extension.
273 298
274This is useful if you need a single terminal thats not using any desktop 299This is useful if you need a single terminal that is not using any desktop
275space most of the time but is quickly available at the press of a key. 300space most of the time but is quickly available at the press of a key.
276 301
277The accelerator key is grabbed regardless of any modifers, so this 302The accelerator key is grabbed regardless of any modifiers, so this
278extension will actually grab a physical key just for this function. 303extension will actually grab a physical key just for this function.
279 304
280If you want a quake-like animation, tell your window manager to do so 305If you want a quake-like animation, tell your window manager to do so
281(fvwm can do it). 306(fvwm can do it).
282 307
283=item automove-background 308=item overlay-osc
284 309
285This is basically a very small extension that dynamically changes the 310This extension implements some OSC commands to display timed popups on the
286background pixmap offset to the window position, in effect creating the 311screen - useful for status displays from within scripts. You have to read
287same effect as pseudo transparency with a custom pixmap. No scaling is 312the sources for more info.
288supported in this mode. Exmaple:
289
290 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background
291 313
292=item block-graphics-to-ascii 314=item block-graphics-to-ascii
293 315
294A not very useful example of filtering all text output to the terminal 316A not very useful example of filtering all text output to the terminal
295by replacing all line-drawing characters (U+2500 .. U+259F) by a 317by replacing all line-drawing characters (U+2500 .. U+259F) by a
300Displays a digital clock using the built-in overlay. 322Displays a digital clock using the built-in overlay.
301 323
302=item remote-clipboard 324=item remote-clipboard
303 325
304Somewhat of a misnomer, this extension adds two menu entries to the 326Somewhat of a misnomer, this extension adds two menu entries to the
305selection popup that allows one ti run external commands to store the 327selection popup that allows one to run external commands to store the
306selection somewhere and fetch it again. 328selection somewhere and fetch it again.
307 329
308We use it to implement a "distributed selection mechanism", which just 330We use it to implement a "distributed selection mechanism", which just
309means that one command uploads the file to a remote server, and another 331means that one command uploads the file to a remote server, and another
310reads it. 332reads it.
345After a successful upload the selection will be replaced by the text given 367After a successful upload the selection will be replaced by the text given
346in the C<selection-pastebin-url> resource (again, the % is the placeholder 368in the C<selection-pastebin-url> resource (again, the % is the placeholder
347for the filename): 369for the filename):
348 370
349 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/% 371 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
372
373I<Note to xrdb users:> xrdb uses the C preprocessor, which might interpret
374the double C</> characters as comment start. Use C<\057\057> instead,
375which works regardless of wether xrdb is used to parse the resource file
376or not.
350 377
351=item example-refresh-hooks 378=item example-refresh-hooks
352 379
353Displays a very simple digital clock in the upper right corner of the 380Displays a very simple digital clock in the upper right corner of the
354window. Illustrates overwriting the refresh callbacks to create your own 381window. Illustrates overwriting the refresh callbacks to create your own
395=back 422=back
396 423
397=head2 Extension Objects 424=head2 Extension Objects
398 425
399Every perl extension is a perl class. A separate perl object is created 426Every perl extension is a perl class. A separate perl object is created
400for each terminal and each extension and passed as the first parameter to 427for each terminal, and each terminal has its own set of extenion objects,
401hooks. So extensions can use their C<$self> object without having to think 428which are passed as the first parameter to hooks. So extensions can use
402about other extensions, with the exception of methods and members that 429their C<$self> object without having to think about clashes with other
430extensions or other terminals, with the exception of methods and members
403begin with an underscore character C<_>: these are reserved for internal 431that begin with an underscore character C<_>: these are reserved for
404use. 432internal use.
405 433
406Although it isn't a C<urxvt::term> object, you can call all methods of the 434Although it isn't a C<urxvt::term> object, you can call all methods of the
407C<urxvt::term> class on this object. 435C<urxvt::term> class on this object.
408 436
409It has the following methods and data members: 437It has the following methods and data members:
430=head2 Hooks 458=head2 Hooks
431 459
432The following subroutines can be declared in extension files, and will be 460The following subroutines can be declared in extension files, and will be
433called whenever the relevant event happens. 461called whenever the relevant event happens.
434 462
435The first argument passed to them is an extension oject as described in 463The first argument passed to them is an extension object as described in
436the in the C<Extension Objects> section. 464the in the C<Extension Objects> section.
437 465
438B<All> of these hooks must return a boolean value. If any of the called 466B<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 467hooks returns true, then the event counts as being I<consumed>, and the
440relevant action might not be carried out by the C++ code. 468relevant action might not be carried out by the C++ code.
453place. 481place.
454 482
455=item on_start $term 483=item on_start $term
456 484
457Called at the very end of initialisation of a new terminal, just before 485Called at the very end of initialisation of a new terminal, just before
458trying to map (display) the toplevel and returning to the mainloop. 486trying to map (display) the toplevel and returning to the main loop.
459 487
460=item on_destroy $term 488=item on_destroy $term
461 489
462Called whenever something tries to destroy terminal, when the terminal is 490Called whenever something tries to destroy terminal, when the terminal is
463still fully functional (not for long, though). 491still fully functional (not for long, though).
490 518
491Called whenever a selection has been copied, but before the selection is 519Called whenever a selection has been copied, but before the selection is
492requested from the server. The selection text can be queried and changed 520requested from the server. The selection text can be queried and changed
493by calling C<< $term->selection >>. 521by calling C<< $term->selection >>.
494 522
495Returning a true value aborts selection grabbing. It will still be hilighted. 523Returning a true value aborts selection grabbing. It will still be highlighted.
496 524
497=item on_sel_extend $term 525=item on_sel_extend $term
498 526
499Called whenever the user tries to extend the selection (e.g. with a double 527Called whenever the user tries to extend the selection (e.g. with a double
500click) and is either supposed to return false (normal operation), or 528click) and is either supposed to return false (normal operation), or
501should extend the selection itelf and return true to suppress the built-in 529should extend the selection itself and return true to suppress the built-in
502processing. This can happen multiple times, as long as the callback 530processing. 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 531returns true, it will be called on every further click by the user and is
504supposed to enlarge the selection more and more, if possible. 532supposed to enlarge the selection more and more, if possible.
505 533
506See the F<selection> example extension. 534See the F<selection> example extension.
507 535
508=item on_view_change $term, $offset 536=item on_view_change $term, $offset
509 537
510Called whenever the view offset changes, i..e the user or program 538Called whenever the view offset changes, i.e. the user or program
511scrolls. Offset C<0> means display the normal terminal, positive values 539scrolls. Offset C<0> means display the normal terminal, positive values
512show this many lines of scrollback. 540show this many lines of scrollback.
513 541
514=item on_scroll_back $term, $lines, $saved 542=item on_scroll_back $term, $lines, $saved
515 543
519 547
520It is called before lines are scrolled out (so rows 0 .. min ($lines - 1, 548It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
521$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total 549$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
522number of lines that will be in the scrollback buffer. 550number of lines that will be in the scrollback buffer.
523 551
524=item on_osc_seq $term, $op, $args 552=item on_osc_seq $term, $op, $args, $resp
525 553
526Called on every OSC sequence and can be used to suppress it or modify its 554Called on every OSC sequence and can be used to suppress it or modify its
527behaviour. The default should be to return an empty list. A true value 555behaviour. The default should be to return an empty list. A true value
528suppresses execution of the request completely. Make sure you don't get 556suppresses execution of the request completely. Make sure you don't get
529confused by recursive invocations when you output an osc sequence within 557confused by recursive invocations when you output an OSC sequence within
530this callback. 558this callback.
531 559
532C<on_osc_seq_perl> should be used for new behaviour. 560C<on_osc_seq_perl> should be used for new behaviour.
533 561
534=item on_osc_seq_perl $term, $string 562=item on_osc_seq_perl $term, $args, $resp
535 563
536Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 564Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
537operating system command) is processed. Cursor position and other state 565operating system command) is processed. Cursor position and other state
538information is up-to-date when this happens. For interoperability, the 566information is up-to-date when this happens. For interoperability, the
539string should start with the extension name and a colon, to distinguish 567string should start with the extension name (sans -osc) and a semicolon,
540it from commands for other extensions, and this might be enforced in the 568to distinguish it from commands for other extensions, and this might be
541future. 569enforced in the future.
570
571For example, C<overlay-osc> uses this:
572
573 sub on_osc_seq_perl {
574 my ($self, $osc, $resp) = @_;
575
576 return unless $osc =~ s/^overlay;//;
577
578 ... process remaining $osc string
579 }
542 580
543Be careful not ever to trust (in a security sense) the data you receive, 581Be 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 582as its source can not easily be controlled (e-mail content, messages from
545other users on the same system etc.). 583other users on the same system etc.).
584
585For responses, C<$resp> contains the end-of-args separator used by the
586sender.
546 587
547=item on_add_lines $term, $string 588=item on_add_lines $term, $string
548 589
549Called whenever text is about to be output, with the text as argument. You 590Called whenever text is about to be output, with the text as argument. You
550can filter/change and output the text yourself by returning a true value 591can filter/change and output the text yourself by returning a true value
571later with the already-modified line (e.g. if unrelated parts change), so 612later with the already-modified line (e.g. if unrelated parts change), so
572you cannot just toggle rendition bits, but only set them. 613you cannot just toggle rendition bits, but only set them.
573 614
574=item on_refresh_begin $term 615=item on_refresh_begin $term
575 616
576Called just before the screen gets redrawn. Can be used for overlay 617Called just before the screen gets redrawn. Can be used for overlay or
577or similar effects by modify terminal contents in refresh_begin, and 618similar effects by modifying the terminal contents in refresh_begin, and
578restoring them in refresh_end. The built-in overlay and selection display 619restoring them in refresh_end. The built-in overlay and selection display
579code is run after this hook, and takes precedence. 620code is run after this hook, and takes precedence.
580 621
581=item on_refresh_end $term 622=item on_refresh_end $term
582 623
583Called just after the screen gets redrawn. See C<on_refresh_begin>. 624Called just after the screen gets redrawn. See C<on_refresh_begin>.
584 625
585=item on_user_command $term, $string 626=item on_user_command $term, $string
586 627
587Called whenever the a user-configured event is being activated (e.g. via 628Called 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> 629a C<perl:string> action bound to a key, see description of the B<keysym>
589resource in the @@RXVT_NAME@@(1) manpage). 630resource in the @@RXVT_NAME@@(1) manpage).
590 631
591The event is simply the action string. This interface is assumed to change 632The event is simply the action string. This interface is assumed to change
592slightly in the future. 633slightly in the future.
593 634
594=item on_resize_all_windows $tern, $new_width, $new_height 635=item on_resize_all_windows $tern, $new_width, $new_height
595 636
596Called just after the new window size has been calculcated, but before 637Called just after the new window size has been calculated, but before
597windows are actually being resized or hints are being set. If this hook 638windows are actually being resized or hints are being set. If this hook
598returns TRUE, setting of the window hints is being skipped. 639returns TRUE, setting of the window hints is being skipped.
599 640
600=item on_x_event $term, $event 641=item on_x_event $term, $event
601 642
612Called whenever the window gets the keyboard focus, before rxvt-unicode 653Called whenever the window gets the keyboard focus, before rxvt-unicode
613does focus in processing. 654does focus in processing.
614 655
615=item on_focus_out $term 656=item on_focus_out $term
616 657
617Called wheneever the window loses keyboard focus, before rxvt-unicode does 658Called whenever the window loses keyboard focus, before rxvt-unicode does
618focus out processing. 659focus out processing.
619 660
620=item on_configure_notify $term, $event 661=item on_configure_notify $term, $event
621 662
622=item on_property_notify $term, $event 663=item on_property_notify $term, $event
705The current terminal. This variable stores the current C<urxvt::term> 746The current terminal. This variable stores the current C<urxvt::term>
706object, whenever a callback/hook is executing. 747object, whenever a callback/hook is executing.
707 748
708=item @urxvt::TERM_INIT 749=item @urxvt::TERM_INIT
709 750
710All coderefs in this array will be called as methods of the next newly 751All 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 752created C<urxvt::term> object (during the C<on_init> phase). The array
712gets cleared before the codereferences that were in it are being executed, 753gets cleared before the code references that were in it are being executed,
713so coderefs can push themselves onto it again if they so desire. 754so references can push themselves onto it again if they so desire.
714 755
715This complements to the perl-eval commandline option, but gets executed 756This complements to the perl-eval command line option, but gets executed
716first. 757first.
717 758
718=item @urxvt::TERM_EXT 759=item @urxvt::TERM_EXT
719 760
720Works similar to C<@TERM_INIT>, but contains perl package/class names, which 761Works similar to C<@TERM_INIT>, but contains perl package/class names, which
745Messages have a size limit of 1023 bytes currently. 786Messages have a size limit of 1023 bytes currently.
746 787
747=item @terms = urxvt::termlist 788=item @terms = urxvt::termlist
748 789
749Returns all urxvt::term objects that exist in this process, regardless of 790Returns all urxvt::term objects that exist in this process, regardless of
750wether they are started, being destroyed etc., so be careful. Only term 791whether they are started, being destroyed etc., so be careful. Only term
751objects that have perl extensions attached will be returned (because there 792objects that have perl extensions attached will be returned (because there
752is no urxvt::term objet associated with others). 793is no urxvt::term objet associated with others).
753 794
754=item $time = urxvt::NOW 795=item $time = urxvt::NOW
755 796
893 local $TERM = shift; 934 local $TERM = shift;
894 my $htype = shift; 935 my $htype = shift;
895 936
896 if ($htype == 0) { # INIT 937 if ($htype == 0) { # INIT
897 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 938 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
898 939
899 my %ext_arg; 940 my %ext_arg;
900 941
901 { 942 {
902 my @init = @TERM_INIT; 943 my @init = @TERM_INIT;
903 @TERM_INIT = (); 944 @TERM_INIT = ();
966 1007
967sub SET_COLOR($$$) { 1008sub SET_COLOR($$$) {
968 SET_BGCOLOR (SET_FGCOLOR ($_[0], $_[1]), $_[2]) 1009 SET_BGCOLOR (SET_FGCOLOR ($_[0], $_[1]), $_[2])
969} 1010}
970 1011
1012sub rend2mask {
1013 no strict 'refs';
1014 my ($str, $mask) = (@_, 0);
1015 my %color = ( fg => undef, bg => undef );
1016 my @failed;
1017 for my $spec ( split /\s+/, $str ) {
1018 if ( $spec =~ /^([fb]g)[_:-]?(\d+)/i ) {
1019 $color{lc($1)} = $2;
1020 } else {
1021 my $neg = $spec =~ s/^[-^]//;
1022 unless ( exists &{"RS_$spec"} ) {
1023 push @failed, $spec;
1024 next;
1025 }
1026 my $cur = &{"RS_$spec"};
1027 if ( $neg ) {
1028 $mask &= ~$cur;
1029 } else {
1030 $mask |= $cur;
1031 }
1032 }
1033 }
1034 ($mask, @color{qw(fg bg)}, \@failed)
1035}
1036
971# urxvt::term::extension 1037# urxvt::term::extension
972 1038
973package urxvt::term::extension; 1039package urxvt::term::extension;
974 1040
975sub enable { 1041sub enable {
1044is that you cannot use blocking APIs, but the non-blocking variant should 1110is that you cannot use blocking APIs, but the non-blocking variant should
1045work. 1111work.
1046 1112
1047=cut 1113=cut
1048 1114
1049our $VERSION = 1; 1115our $VERSION = '3.4';
1050 1116
1051$INC{"urxvt/anyevent.pm"} = 1; # mark us as there 1117$INC{"urxvt/anyevent.pm"} = 1; # mark us as there
1052push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::]; 1118push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
1053 1119
1054sub timer { 1120sub timer {
1085 1151
1086sub DESTROY { 1152sub DESTROY {
1087 $_[0][1]->stop; 1153 $_[0][1]->stop;
1088} 1154}
1089 1155
1090sub condvar { 1156sub one_event {
1091 bless \my $flag, urxvt::anyevent::condvar::
1092}
1093
1094sub urxvt::anyevent::condvar::broadcast {
1095 ${$_[0]}++;
1096}
1097
1098sub urxvt::anyevent::condvar::wait {
1099 unless (${$_[0]}) {
1100 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API"; 1157 Carp::croak "AnyEvent->one_event blocking wait unsupported in urxvt, use a non-blocking API";
1101 }
1102} 1158}
1103 1159
1104package urxvt::term; 1160package urxvt::term;
1105 1161
1106=head2 The C<urxvt::term> Class 1162=head2 The C<urxvt::term> Class
1193 1249
1194Returns true if the option specified by C<$optval> is enabled, and 1250Returns true if the option specified by C<$optval> is enabled, and
1195optionally change it. All option values are stored by name in the hash 1251optionally 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. 1252C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
1197 1253
1198Here is a a likely non-exhaustive list of option names, please see the 1254Here is a likely non-exhaustive list of option names, please see the
1199source file F</src/optinc.h> to see the actual list: 1255source file F</src/optinc.h> to see the actual list:
1200 1256
1201 borderLess console cursorBlink cursorUnderline hold iconic insecure 1257 borderLess console cursorBlink cursorUnderline hold iconic insecure
1202 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 1258 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
1203 override-redirect pastableTabs pointerBlank reverseVideo scrollBar 1259 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
1220likely change). 1276likely change).
1221 1277
1222Please note that resource strings will currently only be freed when the 1278Please note that resource strings will currently only be freed when the
1223terminal is destroyed, so changing options frequently will eat memory. 1279terminal is destroyed, so changing options frequently will eat memory.
1224 1280
1225Here is a a likely non-exhaustive list of resource names, not all of which 1281Here 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> 1282are supported in every build, please see the source file F</src/rsinc.h>
1227to see the actual list: 1283to see the actual list:
1228 1284
1229 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1285 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
1230 borderLess color cursorBlink cursorUnderline cutchars delete_key 1286 borderLess chdir color cursorBlink cursorUnderline cutchars delete_key
1231 display_name embed ext_bwidth fade font geometry hold iconName 1287 display_name embed ext_bwidth fade font geometry hold iconName
1232 imFont imLocale inputMethod insecure int_bwidth intensityStyles 1288 imFont imLocale inputMethod insecure int_bwidth intensityStyles
1233 italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier 1289 italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier
1234 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval 1290 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
1235 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay 1291 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
1236 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar 1292 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
1237 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness 1293 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
1238 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle 1294 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
1239 secondaryScreen secondaryScroll selectstyle shade term_name title 1295 secondaryScreen secondaryScroll shade term_name title
1240 transient_for transparent transparent_all tripleclickwords utmpInhibit 1296 transient_for transparent transparent_all tripleclickwords utmpInhibit
1241 visualBell 1297 visualBell
1242 1298
1243=cut 1299=cut
1244 1300
1245sub resource($$;$) { 1301sub resource($$;$) {
1246 my ($self, $name) = (shift, shift); 1302 my ($self, $name) = (shift, shift);
1247 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 1303 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
1248 &urxvt::term::_resource 1304 goto &urxvt::term::_resource
1249} 1305}
1250 1306
1251=item $value = $term->x_resource ($pattern) 1307=item $value = $term->x_resource ($pattern)
1252 1308
1253Returns the X-Resource for the given pattern, excluding the program or 1309Returns the X-Resource for the given pattern, excluding the program or
1336 1392
1337The methods currently supported on C<urxvt::overlay> objects are: 1393The methods currently supported on C<urxvt::overlay> objects are:
1338 1394
1339=over 4 1395=over 4
1340 1396
1341=item $overlay->set ($x, $y, $text, $rend) 1397=item $overlay->set ($x, $y, $text[, $rend])
1342 1398
1343Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts 1399Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts
1344text in rxvt-unicode's special encoding and an array of rendition values 1400text in rxvt-unicode's special encoding and an array of rendition values
1345at a specific position inside the overlay. 1401at a specific position inside the overlay.
1402
1403If C<$rend> is missing, then the rendition will not be changed.
1346 1404
1347=item $overlay->hide 1405=item $overlay->hide
1348 1406
1349If visible, hide the overlay, but do not destroy it. 1407If visible, hide the overlay, but do not destroy it.
1350 1408
1542 1600
1543Returns the currently displayed screen (0 primary, 1 secondary). 1601Returns the currently displayed screen (0 primary, 1 secondary).
1544 1602
1545=item $cursor_is_hidden = $term->hidden_cursor 1603=item $cursor_is_hidden = $term->hidden_cursor
1546 1604
1547Returns wether the cursor is currently hidden or not. 1605Returns whether the cursor is currently hidden or not.
1548 1606
1549=item $view_start = $term->view_start ([$newvalue]) 1607=item $view_start = $term->view_start ([$newvalue])
1550 1608
1551Returns the row number of the topmost displayed line. Maximum value is 1609Returns the row number of the topmost displayed line. Maximum value is
1552C<0>, which displays the normal terminal contents. Lower values scroll 1610C<0>, which displays the normal terminal contents. Lower values scroll
1560 1618
1561Used after changing terminal contents to display them. 1619Used after changing terminal contents to display them.
1562 1620
1563=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]]) 1621=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
1564 1622
1565Returns the text of the entire row with number C<$row_number>. Row C<0> 1623Returns the text of the entire row with number C<$row_number>. Row C<< $term->top_row >>
1566is the topmost terminal line, row C<< $term->$ncol-1 >> is the bottommost 1624is the topmost terminal line, row C<< $term->nrow-1 >> is the bottommost
1567terminal line. The scrollback buffer starts at line C<-1> and extends to
1568line C<< -$term->nsaved >>. Nothing will be returned if a nonexistent line 1625terminal line. Nothing will be returned if a nonexistent line
1569is requested. 1626is requested.
1570 1627
1571If C<$new_text> is specified, it will replace characters in the current 1628If C<$new_text> is specified, it will replace characters in the current
1572line, starting at column C<$start_col> (default C<0>), which is useful 1629line, starting at column C<$start_col> (default C<0>), which is useful
1573to replace only parts of a line. The font index in the rendition will 1630to replace only parts of a line. The font index in the rendition will
1574automatically be updated. 1631automatically be updated.
1575 1632
1576C<$text> is in a special encoding: tabs and wide characters that use more 1633C<$text> is in a special encoding: tabs and wide characters that use more
1577than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535) 1634than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535)
1578characters. Characters with combining characters and other characters that 1635characters. Characters with combining characters and other characters that
1579do not fit into the normal tetx encoding will be replaced with characters 1636do not fit into the normal text encoding will be replaced with characters
1580in the private use area. 1637in the private use area.
1581 1638
1582You have to obey this encoding when changing text. The advantage is 1639You have to obey this encoding when changing text. The advantage is
1583that C<substr> and similar functions work on screen cells and not on 1640that C<substr> and similar functions work on screen cells and not on
1584characters. 1641characters.
1729where one character corresponds to one screen cell. See 1786where one character corresponds to one screen cell. See
1730C<< $term->ROW_t >> for details. 1787C<< $term->ROW_t >> for details.
1731 1788
1732=item $string = $term->special_decode $text 1789=item $string = $term->special_decode $text
1733 1790
1734Converts rxvt-unicodes text reprsentation into a perl string. See 1791Converts rxvt-unicodes text representation into a perl string. See
1735C<< $term->ROW_t >> for details. 1792C<< $term->ROW_t >> for details.
1736 1793
1737=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt]) 1794=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1738 1795
1739=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt]) 1796=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1742manpage. 1799manpage.
1743 1800
1744=item $success = $term->grab ($eventtime[, $sync]) 1801=item $success = $term->grab ($eventtime[, $sync])
1745 1802
1746Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1803Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1747synchronous (C<$sync> is true). Also remembers the grab timestampe. 1804synchronous (C<$sync> is true). Also remembers the grab timestamp.
1748 1805
1749=item $term->allow_events_async 1806=item $term->allow_events_async
1750 1807
1751Calls XAllowEvents with AsyncBoth for the most recent grab. 1808Calls XAllowEvents with AsyncBoth for the most recent grab.
1752 1809
1771 1828
1772=item @atoms = $term->XListProperties ($window) 1829=item @atoms = $term->XListProperties ($window)
1773 1830
1774=item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property) 1831=item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
1775 1832
1776=item $term->XChangeWindowProperty ($window, $property, $type, $format, $octets) 1833=item $term->XChangeProperty ($window, $property, $type, $format, $octets)
1777 1834
1778=item $term->XDeleteProperty ($window, $property) 1835=item $term->XDeleteProperty ($window, $property)
1779 1836
1780=item $window = $term->DefaultRootWindow 1837=item $window = $term->DefaultRootWindow
1781 1838
1903 my $env = $self->{term}->env; 1960 my $env = $self->{term}->env;
1904 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE. 1961 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
1905 delete $env->{LC_ALL}; 1962 delete $env->{LC_ALL};
1906 $env->{LC_CTYPE} = $self->{term}->locale; 1963 $env->{LC_CTYPE} = $self->{term}->locale;
1907 1964
1908 urxvt::term->new ($env, "popup", 1965 my $term = urxvt::term->new (
1966 $env, "popup",
1909 "--perl-lib" => "", "--perl-ext-common" => "", 1967 "--perl-lib" => "", "--perl-ext-common" => "",
1910 "-pty-fd" => -1, "-sl" => 0, 1968 "-pty-fd" => -1, "-sl" => 0,
1911 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect", 1969 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect",
1912 "--transient-for" => $self->{term}->parent, 1970 "--transient-for" => $self->{term}->parent,
1913 "-display" => $self->{term}->display_id, 1971 "-display" => $self->{term}->display_id,
1914 "-pe" => "urxvt-popup") 1972 "-pe" => "urxvt-popup",
1915 or die "unable to create popup window\n"; 1973 ) or die "unable to create popup window\n";
1974
1975 unless (delete $term->{urxvt_popup_init_done}) {
1976 $term->ungrab;
1977 $term->destroy;
1978 die "unable to initialise popup window\n";
1979 }
1916} 1980}
1917 1981
1918sub DESTROY { 1982sub DESTROY {
1919 my ($self) = @_; 1983 my ($self) = @_;
1920 1984
1925=back 1989=back
1926 1990
1927=cut 1991=cut
1928 1992
1929package urxvt::watcher; 1993package urxvt::watcher;
1930
1931@urxvt::timer::ISA = __PACKAGE__;
1932@urxvt::iow::ISA = __PACKAGE__;
1933@urxvt::pw::ISA = __PACKAGE__;
1934@urxvt::iw::ISA = __PACKAGE__;
1935 1994
1936=head2 The C<urxvt::timer> Class 1995=head2 The C<urxvt::timer> Class
1937 1996
1938This class implements timer watchers/events. Time is represented as a 1997This class implements timer watchers/events. Time is represented as a
1939fractional number of seconds since the epoch. Example: 1998fractional number of seconds since the epoch. Example:
1943 ->new 2002 ->new
1944 ->interval (1) 2003 ->interval (1)
1945 ->cb (sub { 2004 ->cb (sub {
1946 $term->{overlay}->set (0, 0, 2005 $term->{overlay}->set (0, 0,
1947 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]); 2006 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
1948 }); 2007 });
1949 2008
1950=over 4 2009=over 4
1951 2010
1952=item $timer = new urxvt::timer 2011=item $timer = new urxvt::timer
1953 2012
1996 2055
1997 $term->{socket} = ... 2056 $term->{socket} = ...
1998 $term->{iow} = urxvt::iow 2057 $term->{iow} = urxvt::iow
1999 ->new 2058 ->new
2000 ->fd (fileno $term->{socket}) 2059 ->fd (fileno $term->{socket})
2001 ->events (urxvt::EVENT_READ) 2060 ->events (urxvt::EV_READ)
2002 ->start 2061 ->start
2003 ->cb (sub { 2062 ->cb (sub {
2004 my ($iow, $revents) = @_; 2063 my ($iow, $revents) = @_;
2005 # $revents must be 1 here, no need to check 2064 # $revents must be 1 here, no need to check
2006 sysread $term->{socket}, my $buf, 8192 2065 sysread $term->{socket}, my $buf, 8192
2019Set the callback to be called when io events are triggered. C<$reventmask> 2078Set the callback to be called when io events are triggered. C<$reventmask>
2020is a bitset as described in the C<events> method. 2079is a bitset as described in the C<events> method.
2021 2080
2022=item $iow = $iow->fd ($fd) 2081=item $iow = $iow->fd ($fd)
2023 2082
2024Set the filedescriptor (not handle) to watch. 2083Set the file descriptor (not handle) to watch.
2025 2084
2026=item $iow = $iow->events ($eventmask) 2085=item $iow = $iow->events ($eventmask)
2027 2086
2028Set the event mask to watch. The only allowed values are 2087Set the event mask to watch. The only allowed values are
2029C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed 2088C<urxvt::EV_READ> and C<urxvt::EV_WRITE>, which might be ORed
2030together, or C<urxvt::EVENT_NONE>. 2089together, or C<urxvt::EV_NONE>.
2031 2090
2032=item $iow = $iow->start 2091=item $iow = $iow->start
2033 2092
2034Start watching for requested events on the given handle. 2093Start watching for requested events on the given handle.
2035 2094
2036=item $iow = $iow->stop 2095=item $iow = $iow->stop
2037 2096
2038Stop watching for events on the given filehandle. 2097Stop watching for events on the given file handle.
2039 2098
2040=back 2099=back
2041 2100
2042=head2 The C<urxvt::iw> Class 2101=head2 The C<urxvt::iw> Class
2043 2102
2076 ->new 2135 ->new
2077 ->start ($pid) 2136 ->start ($pid)
2078 ->cb (sub { 2137 ->cb (sub {
2079 my ($pw, $exit_status) = @_; 2138 my ($pw, $exit_status) = @_;
2080 ... 2139 ...
2081 }); 2140 });
2082 2141
2083=over 4 2142=over 4
2084 2143
2085=item $pw = new urxvt::pw 2144=item $pw = new urxvt::pw
2086 2145
2090 2149
2091Set the callback to be called when the timer triggers. 2150Set the callback to be called when the timer triggers.
2092 2151
2093=item $pw = $timer->start ($pid) 2152=item $pw = $timer->start ($pid)
2094 2153
2095Tells the wqtcher to start watching for process C<$pid>. 2154Tells the watcher to start watching for process C<$pid>.
2096 2155
2097=item $pw = $pw->stop 2156=item $pw = $pw->stop
2098 2157
2099Stop the watcher. 2158Stop the watcher.
2100 2159
2113 2172
2114=item >= 3 - script loading and management 2173=item >= 3 - script loading and management
2115 2174
2116=item >=10 - all called hooks 2175=item >=10 - all called hooks
2117 2176
2118=item >=11 - hook reutrn values 2177=item >=11 - hook return values
2119 2178
2120=back 2179=back
2121 2180
2122=head1 AUTHOR 2181=head1 AUTHOR
2123 2182
2125 http://software.schmorp.de/pkg/rxvt-unicode 2184 http://software.schmorp.de/pkg/rxvt-unicode
2126 2185
2127=cut 2186=cut
2128 2187
21291 21881
2189
2190# vim: sw=3:

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines