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.131 by root, Sun Jan 29 20:51:28 2006 UTC vs.
Revision 1.198 by root, Tue Oct 4 22:25:14 2011 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
94=item option-popup (enabled by default) 97=item option-popup (enabled by default)
95 98
96Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at 99Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at
97runtime. 100runtime.
98 101
102Other extensions can extend this popup menu by pushing a code reference
103onto C<@{ $term->{option_popup_hook} }>, which gets called whenever the
104popup is being displayed.
105
106Its sole argument is the popup menu, which can be modified. It should
107either return nothing or a string, the initial boolean value and a code
108reference. The string will be used as button text and the code reference
109will be called when the toggle changes, with the new boolean value as
110first argument.
111
112The following will add an entry C<myoption> that changes
113C<< $self->{myoption} >>:
114
115 push @{ $self->{term}{option_popup_hook} }, sub {
116 ("my option" => $myoption, sub { $self->{myoption} = $_[0] })
117 };
118
99=item selection-popup (enabled by default) 119=item selection-popup (enabled by default)
100 120
101Binds a popup menu to Ctrl-Button3 that lets you convert the selection 121Binds a popup menu to Ctrl-Button3 that lets you convert the selection
102text into various other formats/action (such as uri unescaping, perl 122text into various other formats/action (such as uri unescaping, perl
103evaluation, web-browser starting etc.), depending on content. 123evaluation, web-browser starting etc.), depending on content.
104 124
105Other extensions can extend this popup menu by pushing a code reference 125Other extensions can extend this popup menu by pushing a code reference
106onto C<@{ $term->{selection_popup_hook} }>, that is called whenever the 126onto C<@{ $term->{selection_popup_hook} }>, which gets called whenever the
107popup is displayed. 127popup is being displayed.
108 128
109It'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
110is 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.
111It 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
112string 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
113when the button gets activated and should transform C<$_>. 133when the button gets activated and should transform C<$_>.
114 134
115The 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
116the 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
117C<a>s: 137C<a>s:
118 138
119 push @{ $self->{term}{selection_popup_hook} }, sub { 139 push @{ $self->{term}{selection_popup_hook} }, sub {
120 /a/ ? ("a to be" => sub { s/a/b/g } 140 /a/ ? ("a to b" => sub { s/a/b/g }
121 : () 141 : ()
122 }; 142 };
123 143
124=item searchable-scrollback<hotkey> (enabled by default) 144=item searchable-scrollback<hotkey> (enabled by default)
125 145
132search. 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>
133search upwards/downwards in the scrollback buffer, C<End> jumps to the 153search upwards/downwards in the scrollback buffer, C<End> jumps to the
134bottom. 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
135was 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
136additionally stores the first match in the current line into the primary 156additionally stores the first match in the current line into the primary
137selection. 157selection if the C<Shift> modifier is active.
158
159The regex defaults to "(?i)", resulting in a case-insensitive search. To
160get a case-sensitive search you can delete this prefix using C<BackSpace>
161or simply use an uppercase character which removes the "(?i)" prefix.
162
163See L<perlre> for more info about perl regular expression syntax.
138 164
139=item readline (enabled by default) 165=item readline (enabled by default)
140 166
141A support package that tries to make editing with readline easier. At the 167A support package that tries to make editing with readline easier. At
142moment, it reacts to clicking with the left mouse button by trying to 168the moment, it reacts to clicking shift-left mouse button by trying to
143move 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
144cursor-left or cursor-right keypresses as required (the this only works 170cursor-left or cursor-right keypresses as required (this only works
145for programs that correctly support wide characters). 171for programs that correctly support wide characters).
146 172
147To avoid too many false positives, this is only done when: 173To avoid too many false positives, this is only done when:
148 174
149=over 4 175=over 4
197the message into vi commands to load the file. 223the message into vi commands to load the file.
198 224
199=item tabbed 225=item tabbed
200 226
201This transforms the terminal into a tabbar with additional terminals, that 227This transforms the terminal into a tabbar with additional terminals, that
202is, 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
203displays 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
204button per tab. 230button per tab.
205 231
206Clicking a button will activate that tab. Pressing B<Shift-Left> and 232Clicking a button will activate that tab. Pressing B<Shift-Left> and
207B<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,
208while B<Shift-Down> creates a new tab. 234while B<Shift-Down> creates a new tab.
209 235
210=item mark-urls 236The tabbar itself can be configured similarly to a normal terminal, but
237with a resource class of C<URxvt.tabbed>. In addition, it supports the
238following four resources (shown with defaults):
211 239
240 URxvt.tabbed.tabbar-fg: <colour-index, default 3>
241 URxvt.tabbed.tabbar-bg: <colour-index, default 0>
242 URxvt.tabbed.tab-fg: <colour-index, default 0>
243 URxvt.tabbed.tab-bg: <colour-index, default 1>
244
245See I<COLOR AND GRAPHICS> in the @@RXVT_NAME@@(1) manpage for valid
246indices.
247
248=item matcher
249
212Uses per-line display filtering (C<on_line_update>) to underline urls and 250Uses per-line display filtering (C<on_line_update>) to underline text
213make them clickable. When middle-clicked, the program specified in the 251matching a certain pattern and make it clickable. When clicked with the
214resource C<urlLauncher> (default C<x-www-browser>) will be started with 252mouse button specified in the C<matcher.button> resource (default 2, or
215the 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 or a list of matches
265from the keyboard. Simply bind a keysym to "perl:matcher:last" or
266"perl:matcher:list" as seen in the example below.
267
268Example configuration:
269
270 URxvt.perl-ext: default,matcher
271 URxvt.urlLauncher: sensible-browser
272 URxvt.keysym.C-Delete: perl:matcher:last
273 URxvt.keysym.M-Delete: perl:matcher:list
274 URxvt.matcher.button: 1
275 URxvt.matcher.pattern.1: \\bwww\\.[\\w-]+\\.[\\w./?&@#-]*[\\w/-]
276 URxvt.matcher.pattern.2: \\B(/\\S+?):(\\d+)(?=:|$)
277 URxvt.matcher.launcher.2: gvim +$2 $1
216 278
217=item xim-onthespot 279=item xim-onthespot
218 280
219This (experimental) perl extension implements OnTheSpot editing. It does 281This (experimental) perl extension implements OnTheSpot editing. It does
220not work perfectly, and some input methods don't seem to work well with 282not work perfectly, and some input methods don't seem to work well with
221OnTheSpot editing in general, but it seems to work at leats for SCIM and 283OnTheSpot editing in general, but it seems to work at least for SCIM and
222kinput2. 284kinput2.
223 285
224You enable it by specifying this extension and a preedit style of 286You enable it by specifying this extension and a preedit style of
225C<OnTheSpot>, i.e.: 287C<OnTheSpot>, i.e.:
226 288
227 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot 289 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot
228 290
229=item automove-background 291=item kuake<hotkey>
230 292
231This is basically a one-line extension that dynamically changes the background pixmap offset 293A very primitive quake-console-like extension. It was inspired by a
232to the window position, in effect creating the same effect as pseudo transparency with 294description of how the programs C<kuake> and C<yakuake> work: Whenever the
233a custom pixmap. No scaling is supported in this mode. Exmaple: 295user presses a global accelerator key (by default C<F10>), the terminal
296will show or hide itself. Another press of the accelerator key will hide
297or show it again.
234 298
235 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background 299Initially, the window will not be shown when using this extension.
300
301This is useful if you need a single terminal that is not using any desktop
302space most of the time but is quickly available at the press of a key.
303
304The accelerator key is grabbed regardless of any modifiers, so this
305extension will actually grab a physical key just for this function.
306
307If you want a quake-like animation, tell your window manager to do so
308(fvwm can do it).
309
310=item overlay-osc
311
312This extension implements some OSC commands to display timed popups on the
313screen - useful for status displays from within scripts. You have to read
314the sources for more info.
236 315
237=item block-graphics-to-ascii 316=item block-graphics-to-ascii
238 317
239A not very useful example of filtering all text output to the terminal, 318A not very useful example of filtering all text output to the terminal
240by replacing all line-drawing characters (U+2500 .. U+259F) by a 319by replacing all line-drawing characters (U+2500 .. U+259F) by a
241similar-looking ascii character. 320similar-looking ascii character.
242 321
243=item digital-clock 322=item digital-clock
244 323
245Displays a digital clock using the built-in overlay. 324Displays a digital clock using the built-in overlay.
246 325
247=item remote-clipboard 326=item remote-clipboard
248 327
249Somewhat of a misnomer, this extension adds two menu entries to the 328Somewhat of a misnomer, this extension adds two menu entries to the
250selection popup that allows one ti run external commands to store the 329selection popup that allows one to run external commands to store the
251selection somewhere and fetch it again. 330selection somewhere and fetch it again.
252 331
253We use it to implement a "distributed selection mechanism", which just 332We use it to implement a "distributed selection mechanism", which just
254means that one command uploads the file to a remote server, and another 333means that one command uploads the file to a remote server, and another
255reads it. 334reads it.
264 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection' 343 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
265 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection' 344 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
266 345
267=item selection-pastebin 346=item selection-pastebin
268 347
269This is a little rarely useful extension that Uploads the selection as 348This is a little rarely useful extension that uploads the selection as
270textfile to a remote site (or does other things). (The implementation is 349textfile to a remote site (or does other things). (The implementation is
271not currently secure for use in a multiuser environment as it writes to 350not currently secure for use in a multiuser environment as it writes to
272F</tmp> directly.). 351F</tmp> directly.).
273 352
274It listens to the C<selection-pastebin:remote-pastebin> keyboard command, 353It listens to the C<selection-pastebin:remote-pastebin> keyboard command,
291in the C<selection-pastebin-url> resource (again, the % is the placeholder 370in the C<selection-pastebin-url> resource (again, the % is the placeholder
292for the filename): 371for the filename):
293 372
294 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/% 373 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
295 374
375I<Note to xrdb users:> xrdb uses the C preprocessor, which might interpret
376the double C</> characters as comment start. Use C<\057\057> instead,
377which works regardless of whether xrdb is used to parse the resource file
378or not.
379
380=item macosx-clipboard and macosx-clipboard-native
381
382These two modules implement an extended clipboard for Mac OS X. They are
383used like this:
384
385 URxvt.perl-ext-common: default,macosx-clipboard
386 URxvt.keysym.M-c: perl:macosx-clipboard:copy
387 URxvt.keysym.M-v: perl:macosx-clipboard:paste
388
389The difference between them is that the native variant requires a
390perl from apple's devkit or so, and C<macosx-clipboard> requires the
391C<Mac::Pasteboard> module, works with other perls, has fewer bugs, is
392simpler etc. etc.
393
296=item example-refresh-hooks 394=item example-refresh-hooks
297 395
298Displays a very simple digital clock in the upper right corner of the 396Displays a very simple digital clock in the upper right corner of the
299window. Illustrates overwriting the refresh callbacks to create your own 397window. Illustrates overwriting the refresh callbacks to create your own
300overlays or changes. 398overlays or changes.
399
400=item confirm-paste
401
402Displays a confirmation dialog when a paste containing at least a full
403line is detected.
301 404
302=back 405=back
303 406
304=head1 API DOCUMENTATION 407=head1 API DOCUMENTATION
305 408
321 424
322=over 4 425=over 4
323 426
324=item $text 427=item $text
325 428
326Rxvt-unicodes special way of encoding text, where one "unicode" character 429Rxvt-unicode's special way of encoding text, where one "unicode" character
327always represents one screen cell. See L<ROW_t> for a discussion of this format. 430always represents one screen cell. See L<ROW_t> for a discussion of this format.
328 431
329=item $string 432=item $string
330 433
331A perl text string, with an emphasis on I<text>. It can store all unicode 434A perl text string, with an emphasis on I<text>. It can store all unicode
339 442
340=back 443=back
341 444
342=head2 Extension Objects 445=head2 Extension Objects
343 446
344Very perl extension is a perl class. A separate perl object is created 447Every perl extension is a perl class. A separate perl object is created
345for each terminal and each extension and passed as the first parameter to 448for each terminal, and each terminal has its own set of extension objects,
346hooks. So extensions can use their C<$self> object without having to think 449which are passed as the first parameter to hooks. So extensions can use
347about other extensions, with the exception of methods and members that 450their C<$self> object without having to think about clashes with other
451extensions or other terminals, with the exception of methods and members
348begin with an underscore character C<_>: these are reserved for internal 452that begin with an underscore character C<_>: these are reserved for
349use. 453internal use.
350 454
351Although it isn't a C<urxvt::term> object, you can call all methods of the 455Although it isn't a C<urxvt::term> object, you can call all methods of the
352C<urxvt::term> class on this object. 456C<urxvt::term> class on this object.
353 457
354It has the following methods and data members: 458It has the following methods and data members:
375=head2 Hooks 479=head2 Hooks
376 480
377The following subroutines can be declared in extension files, and will be 481The following subroutines can be declared in extension files, and will be
378called whenever the relevant event happens. 482called whenever the relevant event happens.
379 483
380The first argument passed to them is an extension oject as described in 484The first argument passed to them is an extension object as described in
381the in the C<Extension Objects> section. 485the in the C<Extension Objects> section.
382 486
383B<All> of these hooks must return a boolean value. If any of the called 487B<All> of these hooks must return a boolean value. If any of the called
384hooks returns true, then the event counts as being I<consumed>, and the 488hooks returns true, then the event counts as being I<consumed>, and the
385relevant action might not be carried out by the C++ code. 489relevant action might not be carried out by the C++ code.
398place. 502place.
399 503
400=item on_start $term 504=item on_start $term
401 505
402Called at the very end of initialisation of a new terminal, just before 506Called at the very end of initialisation of a new terminal, just before
403trying to map (display) the toplevel and returning to the mainloop. 507trying to map (display) the toplevel and returning to the main loop.
404 508
405=item on_destroy $term 509=item on_destroy $term
406 510
407Called whenever something tries to destroy terminal, when the terminal is 511Called whenever something tries to destroy terminal, when the terminal is
408still fully functional (not for long, though). 512still fully functional (not for long, though).
435 539
436Called whenever a selection has been copied, but before the selection is 540Called whenever a selection has been copied, but before the selection is
437requested from the server. The selection text can be queried and changed 541requested from the server. The selection text can be queried and changed
438by calling C<< $term->selection >>. 542by calling C<< $term->selection >>.
439 543
440Returning a true value aborts selection grabbing. It will still be hilighted. 544Returning a true value aborts selection grabbing. It will still be highlighted.
441 545
442=item on_sel_extend $term 546=item on_sel_extend $term
443 547
444Called whenever the user tries to extend the selection (e.g. with a double 548Called whenever the user tries to extend the selection (e.g. with a double
445click) and is either supposed to return false (normal operation), or 549click) and is either supposed to return false (normal operation), or
446should extend the selection itelf and return true to suppress the built-in 550should extend the selection itself and return true to suppress the built-in
447processing. This can happen multiple times, as long as the callback 551processing. This can happen multiple times, as long as the callback
448returns true, it will be called on every further click by the user and is 552returns true, it will be called on every further click by the user and is
449supposed to enlarge the selection more and more, if possible. 553supposed to enlarge the selection more and more, if possible.
450 554
451See the F<selection> example extension. 555See the F<selection> example extension.
452 556
453=item on_view_change $term, $offset 557=item on_view_change $term, $offset
454 558
455Called whenever the view offset changes, i..e the user or program 559Called whenever the view offset changes, i.e. the user or program
456scrolls. Offset C<0> means display the normal terminal, positive values 560scrolls. Offset C<0> means display the normal terminal, positive values
457show this many lines of scrollback. 561show this many lines of scrollback.
458 562
459=item on_scroll_back $term, $lines, $saved 563=item on_scroll_back $term, $lines, $saved
460 564
464 568
465It is called before lines are scrolled out (so rows 0 .. min ($lines - 1, 569It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
466$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total 570$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
467number of lines that will be in the scrollback buffer. 571number of lines that will be in the scrollback buffer.
468 572
469=item on_osc_seq $term, $string 573=item on_osc_seq $term, $op, $args, $resp
574
575Called on every OSC sequence and can be used to suppress it or modify its
576behaviour. The default should be to return an empty list. A true value
577suppresses execution of the request completely. Make sure you don't get
578confused by recursive invocations when you output an OSC sequence within
579this callback.
580
581C<on_osc_seq_perl> should be used for new behaviour.
582
583=item on_osc_seq_perl $term, $args, $resp
470 584
471Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 585Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
472operating system command) is processed. Cursor position and other state 586operating system command) is processed. Cursor position and other state
473information is up-to-date when this happens. For interoperability, the 587information is up-to-date when this happens. For interoperability, the
474string should start with the extension name and a colon, to distinguish 588string should start with the extension name (sans -osc) and a semicolon,
475it from commands for other extensions, and this might be enforced in the 589to distinguish it from commands for other extensions, and this might be
476future. 590enforced in the future.
591
592For example, C<overlay-osc> uses this:
593
594 sub on_osc_seq_perl {
595 my ($self, $osc, $resp) = @_;
596
597 return unless $osc =~ s/^overlay;//;
598
599 ... process remaining $osc string
600 }
477 601
478Be careful not ever to trust (in a security sense) the data you receive, 602Be careful not ever to trust (in a security sense) the data you receive,
479as its source can not easily be controleld (e-mail content, messages from 603as its source can not easily be controlled (e-mail content, messages from
480other users on the same system etc.). 604other users on the same system etc.).
605
606For responses, C<$resp> contains the end-of-args separator used by the
607sender.
481 608
482=item on_add_lines $term, $string 609=item on_add_lines $term, $string
483 610
484Called whenever text is about to be output, with the text as argument. You 611Called whenever text is about to be output, with the text as argument. You
485can filter/change and output the text yourself by returning a true value 612can filter/change and output the text yourself by returning a true value
490=item on_tt_write $term, $octets 617=item on_tt_write $term, $octets
491 618
492Called whenever some data is written to the tty/pty and can be used to 619Called whenever some data is written to the tty/pty and can be used to
493suppress or filter tty input. 620suppress or filter tty input.
494 621
622=item on_tt_paste $term, $octets
623
624Called whenever text is about to be pasted, with the text as argument. You
625can filter/change and paste the text yourself by returning a true value
626and calling C<< $term->tt_paste >> yourself. C<$octets> is
627locale-encoded.
628
495=item on_line_update $term, $row 629=item on_line_update $term, $row
496 630
497Called whenever a line was updated or changed. Can be used to filter 631Called whenever a line was updated or changed. Can be used to filter
498screen output (e.g. underline urls or other useless stuff). Only lines 632screen output (e.g. underline urls or other useless stuff). Only lines
499that are being shown will be filtered, and, due to performance reasons, 633that are being shown will be filtered, and, due to performance reasons,
506later with the already-modified line (e.g. if unrelated parts change), so 640later with the already-modified line (e.g. if unrelated parts change), so
507you cannot just toggle rendition bits, but only set them. 641you cannot just toggle rendition bits, but only set them.
508 642
509=item on_refresh_begin $term 643=item on_refresh_begin $term
510 644
511Called just before the screen gets redrawn. Can be used for overlay 645Called just before the screen gets redrawn. Can be used for overlay or
512or similar effects by modify terminal contents in refresh_begin, and 646similar effects by modifying the terminal contents in refresh_begin, and
513restoring them in refresh_end. The built-in overlay and selection display 647restoring them in refresh_end. The built-in overlay and selection display
514code is run after this hook, and takes precedence. 648code is run after this hook, and takes precedence.
515 649
516=item on_refresh_end $term 650=item on_refresh_end $term
517 651
518Called just after the screen gets redrawn. See C<on_refresh_begin>. 652Called just after the screen gets redrawn. See C<on_refresh_begin>.
519 653
520=item on_user_command $term, $string 654=item on_user_command $term, $string
521 655
522Called whenever the a user-configured event is being activated (e.g. via 656Called whenever a user-configured event is being activated (e.g. via
523a C<perl:string> action bound to a key, see description of the B<keysym> 657a C<perl:string> action bound to a key, see description of the B<keysym>
524resource in the @@RXVT_NAME@@(1) manpage). 658resource in the @@RXVT_NAME@@(1) manpage).
525 659
526The event is simply the action string. This interface is assumed to change 660The event is simply the action string. This interface is assumed to change
527slightly in the future. 661slightly in the future.
662
663=item on_resize_all_windows $term, $new_width, $new_height
664
665Called just after the new window size has been calculated, but before
666windows are actually being resized or hints are being set. If this hook
667returns TRUE, setting of the window hints is being skipped.
528 668
529=item on_x_event $term, $event 669=item on_x_event $term, $event
530 670
531Called on every X event received on the vt window (and possibly other 671Called on every X event received on the vt window (and possibly other
532windows). Should only be used as a last resort. Most event structure 672windows). Should only be used as a last resort. Most event structure
533members are not passed. 673members are not passed.
534 674
675=item on_root_event $term, $event
676
677Like C<on_x_event>, but is called for events on the root window.
678
535=item on_focus_in $term 679=item on_focus_in $term
536 680
537Called whenever the window gets the keyboard focus, before rxvt-unicode 681Called whenever the window gets the keyboard focus, before rxvt-unicode
538does focus in processing. 682does focus in processing.
539 683
540=item on_focus_out $term 684=item on_focus_out $term
541 685
542Called wheneever the window loses keyboard focus, before rxvt-unicode does 686Called whenever the window loses keyboard focus, before rxvt-unicode does
543focus out processing. 687focus out processing.
544 688
545=item on_configure_notify $term, $event 689=item on_configure_notify $term, $event
546 690
547=item on_property_notify $term, $event 691=item on_property_notify $term, $event
558 702
559=item on_map_notify $term, $event 703=item on_map_notify $term, $event
560 704
561=item on_unmap_notify $term, $event 705=item on_unmap_notify $term, $event
562 706
563Called whenever the corresponding X event is received for the terminal If 707Called whenever the corresponding X event is received for the terminal. If
564the hook returns true, then the even will be ignored by rxvt-unicode. 708the hook returns true, then the event will be ignored by rxvt-unicode.
565 709
566The event is a hash with most values as named by Xlib (see the XEvent 710The event is a hash with most values as named by Xlib (see the XEvent
567manpage), with the additional members C<row> and C<col>, which are the 711manpage), with the additional members C<row> and C<col>, which are the
568(real, not screen-based) row and column under the mouse cursor. 712(real, not screen-based) row and column under the mouse cursor.
569 713
578 722
579=item on_wm_delete_window $term, $event 723=item on_wm_delete_window $term, $event
580 724
581Called when various types of ClientMessage events are received (all with 725Called when various types of ClientMessage events are received (all with
582format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW). 726format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
727
728=item on_bell $term
729
730Called on receipt of a bell character.
583 731
584=back 732=back
585 733
586=cut 734=cut
587 735
630The current terminal. This variable stores the current C<urxvt::term> 778The current terminal. This variable stores the current C<urxvt::term>
631object, whenever a callback/hook is executing. 779object, whenever a callback/hook is executing.
632 780
633=item @urxvt::TERM_INIT 781=item @urxvt::TERM_INIT
634 782
635All coderefs in this array will be called as methods of the next newly 783All code references in this array will be called as methods of the next newly
636created C<urxvt::term> object (during the C<on_init> phase). The array 784created C<urxvt::term> object (during the C<on_init> phase). The array
637gets cleared before the codereferences that were in it are being executed, 785gets cleared before the code references that were in it are being executed,
638so coderefs can push themselves onto it again if they so desire. 786so references can push themselves onto it again if they so desire.
639 787
640This complements to the perl-eval commandline option, but gets executed 788This complements to the perl-eval command line option, but gets executed
641first. 789first.
642 790
643=item @urxvt::TERM_EXT 791=item @urxvt::TERM_EXT
644 792
645Works similar to C<@TERM_INIT>, but contains perl package/class names, which 793Works similar to C<@TERM_INIT>, but contains perl package/class names, which
652 800
653=over 4 801=over 4
654 802
655=item urxvt::fatal $errormessage 803=item urxvt::fatal $errormessage
656 804
657Fatally aborts execution with the given error message. Avoid at all 805Fatally aborts execution with the given error message (which should
658costs! The only time this is acceptable is when the terminal process 806include a trailing newline). Avoid at all costs! The only time this
659starts up. 807is acceptable (and useful) is in the init hook, where it prevents the
808terminal from starting up.
660 809
661=item urxvt::warn $string 810=item urxvt::warn $string
662 811
663Calls C<rxvt_warn> with the given string which should not include a 812Calls C<rxvt_warn> with the given string which should include a trailing
664newline. The module also overwrites the C<warn> builtin with a function 813newline. The module also overwrites the C<warn> builtin with a function
665that calls this function. 814that calls this function.
666 815
667Using this function has the advantage that its output ends up in the 816Using this function has the advantage that its output ends up in the
668correct place, e.g. on stderr of the connecting urxvtc client. 817correct place, e.g. on stderr of the connecting urxvtc client.
670Messages have a size limit of 1023 bytes currently. 819Messages have a size limit of 1023 bytes currently.
671 820
672=item @terms = urxvt::termlist 821=item @terms = urxvt::termlist
673 822
674Returns all urxvt::term objects that exist in this process, regardless of 823Returns all urxvt::term objects that exist in this process, regardless of
675wether they are started, being destroyed etc., so be careful. Only term 824whether they are started, being destroyed etc., so be careful. Only term
676objects that have perl extensions attached will be returned (because there 825objects that have perl extensions attached will be returned (because there
677is no urxvt::term objet associated with others). 826is no urxvt::term object associated with others).
678 827
679=item $time = urxvt::NOW 828=item $time = urxvt::NOW
680 829
681Returns the "current time" (as per the event loop). 830Returns the "current time" (as per the event loop).
682 831
725 874
726=item $rend = urxvt::OVERLAY_RSTYLE 875=item $rend = urxvt::OVERLAY_RSTYLE
727 876
728Return the rendition mask used for overlays by default. 877Return the rendition mask used for overlays by default.
729 878
730=item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline 879=item $rendbit = urxvt::RS_Bold, urxvt::RS_Italic, urxvt::RS_Blink,
880urxvt::RS_RVid, urxvt::RS_Uline
731 881
732Return the bit that enabled bold, italic, blink, reverse-video and 882Return the bit that enabled bold, italic, blink, reverse-video and
733underline, respectively. To enable such a style, just logically OR it into 883underline, respectively. To enable such a style, just logically OR it into
734the bitset. 884the bitset.
735 885
740Return the foreground/background colour index, respectively. 890Return the foreground/background colour index, respectively.
741 891
742=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour 892=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
743 893
744=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour 894=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
895
896=item $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
745 897
746Replace the foreground/background colour in the rendition mask with the 898Replace the foreground/background colour in the rendition mask with the
747specified one. 899specified one.
748 900
749=item $value = urxvt::GET_CUSTOM $rend 901=item $value = urxvt::GET_CUSTOM $rend
816 local $TERM = shift; 968 local $TERM = shift;
817 my $htype = shift; 969 my $htype = shift;
818 970
819 if ($htype == 0) { # INIT 971 if ($htype == 0) { # INIT
820 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 972 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
821 973
822 my %ext_arg; 974 my %ext_arg;
823 975
824 { 976 {
825 my @init = @TERM_INIT; 977 my @init = @TERM_INIT;
826 @TERM_INIT = (); 978 @TERM_INIT = ();
840 } else { 992 } else {
841 $ext_arg{$_} ||= []; 993 $ext_arg{$_} ||= [];
842 } 994 }
843 } 995 }
844 996
845 while (my ($ext, $argv) = each %ext_arg) { 997 for my $ext (sort keys %ext_arg) {
846 my @files = grep -f $_, map "$_/$ext", @dirs; 998 my @files = grep -f $_, map "$_/$ext", @dirs;
847 999
848 if (@files) { 1000 if (@files) {
849 $TERM->register_package (extension_package $files[0], $argv); 1001 $TERM->register_package (extension_package $files[0], $ext_arg{$ext});
850 } else { 1002 } else {
851 warn "perl extension '$ext' not found in perl library search path\n"; 1003 warn "perl extension '$ext' not found in perl library search path\n";
852 } 1004 }
853 } 1005 }
854 1006
860 1012
861 if (my $cb = $TERM->{_hook}[$htype]) { 1013 if (my $cb = $TERM->{_hook}[$htype]) {
862 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")" 1014 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
863 if $verbosity >= 10; 1015 if $verbosity >= 10;
864 1016
865 keys %$cb; 1017 for my $pkg (keys %$cb) {
866
867 while (my ($pkg, $cb) = each %$cb) {
868 my $retval_ = eval { $cb->($TERM->{_pkg}{$pkg}, @_) }; 1018 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg}, @_) };
869 $retval ||= $retval_; 1019 $retval ||= $retval_;
870 1020
871 if ($@) { 1021 if ($@) {
872 $TERM->ungrab; # better to lose the grab than the session 1022 $TERM->ungrab; # better to lose the grab than the session
873 warn $@; 1023 warn $@;
885 # clear package 1035 # clear package
886 %$TERM = (); 1036 %$TERM = ();
887 } 1037 }
888 1038
889 $retval 1039 $retval
1040}
1041
1042sub SET_COLOR($$$) {
1043 SET_BGCOLOR (SET_FGCOLOR ($_[0], $_[1]), $_[2])
1044}
1045
1046sub rend2mask {
1047 no strict 'refs';
1048 my ($str, $mask) = (@_, 0);
1049 my %color = ( fg => undef, bg => undef );
1050 my @failed;
1051 for my $spec ( split /\s+/, $str ) {
1052 if ( $spec =~ /^([fb]g)[_:-]?(\d+)/i ) {
1053 $color{lc($1)} = $2;
1054 } else {
1055 my $neg = $spec =~ s/^[-^]//;
1056 unless ( exists &{"RS_$spec"} ) {
1057 push @failed, $spec;
1058 next;
1059 }
1060 my $cur = &{"RS_$spec"};
1061 if ( $neg ) {
1062 $mask &= ~$cur;
1063 } else {
1064 $mask |= $cur;
1065 }
1066 }
1067 }
1068 ($mask, @color{qw(fg bg)}, \@failed)
890} 1069}
891 1070
892# urxvt::term::extension 1071# urxvt::term::extension
893 1072
894package urxvt::term::extension; 1073package urxvt::term::extension;
965is that you cannot use blocking APIs, but the non-blocking variant should 1144is that you cannot use blocking APIs, but the non-blocking variant should
966work. 1145work.
967 1146
968=cut 1147=cut
969 1148
970our $VERSION = 1; 1149our $VERSION = '5.23';
971 1150
972$INC{"urxvt/anyevent.pm"} = 1; # mark us as there 1151$INC{"urxvt/anyevent.pm"} = 1; # mark us as there
973push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::]; 1152push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
974 1153
975sub timer { 1154sub timer {
977 1156
978 my $cb = $arg{cb}; 1157 my $cb = $arg{cb};
979 1158
980 urxvt::timer 1159 urxvt::timer
981 ->new 1160 ->new
982 ->start (urxvt::NOW + $arg{after}) 1161 ->after ($arg{after}, $arg{interval})
983 ->cb (sub { 1162 ->cb ($arg{interval} ? $cb : sub {
984 $_[0]->stop; # need to cancel manually 1163 $_[0]->stop; # need to cancel manually
985 $cb->(); 1164 $cb->();
986 }) 1165 })
987} 1166}
988 1167
989sub io { 1168sub io {
990 my ($class, %arg) = @_; 1169 my ($class, %arg) = @_;
991 1170
992 my $cb = $arg{cb}; 1171 my $cb = $arg{cb};
1172 my $fd = fileno $arg{fh};
1173 defined $fd or $fd = $arg{fh};
993 1174
994 bless [$arg{fh}, urxvt::iow 1175 bless [$arg{fh}, urxvt::iow
995 ->new 1176 ->new
996 ->fd (fileno $arg{fh}) 1177 ->fd ($fd)
997 ->events (($arg{poll} =~ /r/ ? 1 : 0) 1178 ->events (($arg{poll} =~ /r/ ? 1 : 0)
998 | ($arg{poll} =~ /w/ ? 2 : 0)) 1179 | ($arg{poll} =~ /w/ ? 2 : 0))
999 ->start 1180 ->start
1000 ->cb (sub { 1181 ->cb ($cb)
1001 $cb->(($_[1] & 1 ? 'r' : '')
1002 . ($_[1] & 2 ? 'w' : ''));
1003 })],
1004 urxvt::anyevent:: 1182 ], urxvt::anyevent::
1183}
1184
1185sub idle {
1186 my ($class, %arg) = @_;
1187
1188 my $cb = $arg{cb};
1189
1190 urxvt::iw
1191 ->new
1192 ->start
1193 ->cb ($cb)
1194}
1195
1196sub child {
1197 my ($class, %arg) = @_;
1198
1199 my $cb = $arg{cb};
1200
1201 urxvt::pw
1202 ->new
1203 ->start ($arg{pid})
1204 ->cb (sub {
1205 $_[0]->stop; # need to cancel manually
1206 $cb->($_[0]->rpid, $_[0]->rstatus);
1207 })
1005} 1208}
1006 1209
1007sub DESTROY { 1210sub DESTROY {
1008 $_[0][1]->stop; 1211 $_[0][1]->stop;
1009} 1212}
1010 1213
1011sub condvar { 1214# only needed for AnyEvent < 6 compatibility
1012 bless \my $flag, urxvt::anyevent::condvar:: 1215sub one_event {
1013}
1014
1015sub urxvt::anyevent::condvar::broadcast {
1016 ${$_[0]}++;
1017}
1018
1019sub urxvt::anyevent::condvar::wait {
1020 unless (${$_[0]}) {
1021 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API"; 1216 Carp::croak "AnyEvent->one_event blocking wait unsupported in urxvt, use a non-blocking API";
1022 }
1023} 1217}
1024 1218
1025package urxvt::term; 1219package urxvt::term;
1026 1220
1027=head2 The C<urxvt::term> Class 1221=head2 The C<urxvt::term> Class
1114 1308
1115Returns true if the option specified by C<$optval> is enabled, and 1309Returns true if the option specified by C<$optval> is enabled, and
1116optionally change it. All option values are stored by name in the hash 1310optionally change it. All option values are stored by name in the hash
1117C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash. 1311C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
1118 1312
1119Here is a a likely non-exhaustive list of option names, please see the 1313Here is a likely non-exhaustive list of option names, please see the
1120source file F</src/optinc.h> to see the actual list: 1314source file F</src/optinc.h> to see the actual list:
1121 1315
1122 borderLess console cursorBlink cursorUnderline hold iconic insecure 1316 borderLess buffered console cursorBlink cursorUnderline hold iconic
1123 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 1317 insecure intensityStyles iso14755 iso14755_52 jumpScroll loginShell
1124 override-redirect pastableTabs pointerBlank reverseVideo scrollBar 1318 mapAlert meta8 mouseWheelScrollPage override_redirect pastableTabs
1125 scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput 1319 pointerBlank reverseVideo scrollBar scrollBar_floating scrollBar_right
1126 scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs 1320 scrollTtyKeypress scrollTtyOutput scrollWithBuffer secondaryScreen
1127 transparent tripleclickwords utmpInhibit visualBell 1321 secondaryScroll skipBuiltinGlyphs skipScroll transparent tripleclickwords
1322 urgentOnBell utmpInhibit visualBell
1128 1323
1129=item $value = $term->resource ($name[, $newval]) 1324=item $value = $term->resource ($name[, $newval])
1130 1325
1131Returns the current resource value associated with a given name and 1326Returns the current resource value associated with a given name and
1132optionally sets a new value. Setting values is most useful in the C<init> 1327optionally sets a new value. Setting values is most useful in the C<init>
1141likely change). 1336likely change).
1142 1337
1143Please note that resource strings will currently only be freed when the 1338Please note that resource strings will currently only be freed when the
1144terminal is destroyed, so changing options frequently will eat memory. 1339terminal is destroyed, so changing options frequently will eat memory.
1145 1340
1146Here is a a likely non-exhaustive list of resource names, not all of which 1341Here is a likely non-exhaustive list of resource names, not all of which
1147are supported in every build, please see the source file F</src/rsinc.h> 1342are supported in every build, please see the source file F</src/rsinc.h>
1148to see the actual list: 1343to see the actual list:
1149 1344
1150 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1345 answerbackstring backgroundPixmap backspace_key blendtype blurradius
1151 borderLess color cursorBlink cursorUnderline cutchars delete_key 1346 boldFont boldItalicFont borderLess buffered chdir color cursorBlink
1152 display_name embed ext_bwidth fade font geometry hold iconName 1347 cursorUnderline cutchars delete_key depth display_name embed ext_bwidth
1153 imFont imLocale inputMethod insecure int_bwidth intensityStyles 1348 fade font geometry hold iconName iconfile imFont imLocale inputMethod
1349 insecure int_bwidth intensityStyles iso14755 iso14755_52 italicFont
1154 italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier 1350 jumpScroll letterSpace lineSpace loginShell mapAlert meta8 modifier
1155 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval 1351 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
1156 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay 1352 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
1157 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar 1353 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
1158 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness 1354 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
1159 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle 1355 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
1160 secondaryScreen secondaryScroll selectstyle shade term_name title 1356 secondaryScreen secondaryScroll shade skipBuiltinGlyphs skipScroll
1161 transient_for transparent transparent_all tripleclickwords utmpInhibit 1357 term_name title transient_for transparent tripleclickwords urgentOnBell
1162 visualBell 1358 utmpInhibit visualBell
1163 1359
1164=cut 1360=cut
1165 1361
1166sub resource($$;$) { 1362sub resource($$;$) {
1167 my ($self, $name) = (shift, shift); 1363 my ($self, $name) = (shift, shift);
1168 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 1364 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
1169 &urxvt::term::_resource 1365 goto &urxvt::term::_resource
1170} 1366}
1171 1367
1172=item $value = $term->x_resource ($pattern) 1368=item $value = $term->x_resource ($pattern)
1173 1369
1174Returns the X-Resource for the given pattern, excluding the program or 1370Returns the X-Resource for the given pattern, excluding the program or
1199 1395
1200=item ($row, $col) = $term->selection_beg ([$row, $col]) 1396=item ($row, $col) = $term->selection_beg ([$row, $col])
1201 1397
1202=item ($row, $col) = $term->selection_end ([$row, $col]) 1398=item ($row, $col) = $term->selection_end ([$row, $col])
1203 1399
1204Return the current values of the selection mark, begin or end positions, 1400Return the current values of the selection mark, begin or end positions.
1205and optionally set them to new values. 1401
1402When arguments are given, then the selection coordinates are set to
1403C<$row> and C<$col>, and the selection screen is set to the current
1404screen.
1405
1406=item $screen = $term->selection_screen ([$screen])
1407
1408Returns the current selection screen, and then optionally sets it.
1206 1409
1207=item $term->selection_make ($eventtime[, $rectangular]) 1410=item $term->selection_make ($eventtime[, $rectangular])
1208 1411
1209Tries to make a selection as set by C<selection_beg> and 1412Tries to make a selection as set by C<selection_beg> and
1210C<selection_end>. If C<$rectangular> is true (default: false), a 1413C<selection_end>. If C<$rectangular> is true (default: false), a
1211rectangular selection will be made. This is the prefered function to make 1414rectangular selection will be made. This is the preferred function to make
1212a selection. 1415a selection.
1213 1416
1214=item $success = $term->selection_grab ($eventtime) 1417=item $success = $term->selection_grab ($eventtime[, $clipboard])
1215 1418
1216Try to request the primary selection text from the server (for example, as 1419Try to acquire ownership of the primary (clipboard if C<$clipboard> is
1420true) selection from the server. The corresponding text can be set
1217set by the next method). No visual feedback will be given. This function 1421with the next method. No visual feedback will be given. This function
1218is mostly useful from within C<on_sel_grab> hooks. 1422is mostly useful from within C<on_sel_grab> hooks.
1219 1423
1220=item $oldtext = $term->selection ([$newtext]) 1424=item $oldtext = $term->selection ([$newtext, $clipboard])
1221 1425
1222Return the current selection text and optionally replace it by C<$newtext>. 1426Return the current selection (clipboard if C<$clipboard> is true) text
1427and optionally replace it by C<$newtext>.
1428
1429=item $term->selection_clear ([$clipboard])
1430
1431Revoke ownership of the primary (clipboard if C<$clipboard> is true) selection.
1223 1432
1224=item $term->overlay_simple ($x, $y, $text) 1433=item $term->overlay_simple ($x, $y, $text)
1225 1434
1226Create a simple multi-line overlay box. See the next method for details. 1435Create a simple multi-line overlay box. See the next method for details.
1227 1436
1257 1466
1258The methods currently supported on C<urxvt::overlay> objects are: 1467The methods currently supported on C<urxvt::overlay> objects are:
1259 1468
1260=over 4 1469=over 4
1261 1470
1262=item $overlay->set ($x, $y, $text, $rend) 1471=item $overlay->set ($x, $y, $text[, $rend])
1263 1472
1264Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts 1473Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts
1265text in rxvt-unicode's special encoding and an array of rendition values 1474text in rxvt-unicode's special encoding and an array of rendition values
1266at a specific position inside the overlay. 1475at a specific position inside the overlay.
1476
1477If C<$rend> is missing, then the rendition will not be changed.
1267 1478
1268=item $overlay->hide 1479=item $overlay->hide
1269 1480
1270If visible, hide the overlay, but do not destroy it. 1481If visible, hide the overlay, but do not destroy it.
1271 1482
1353locale-specific encoding of the terminal and can contain command sequences 1564locale-specific encoding of the terminal and can contain command sequences
1354(escape codes) that will be interpreted. 1565(escape codes) that will be interpreted.
1355 1566
1356=item $term->tt_write ($octets) 1567=item $term->tt_write ($octets)
1357 1568
1358Write the octets given in C<$data> to the tty (i.e. as program input). To 1569Write the octets given in C<$octets> to the tty (i.e. as program input). To
1359pass characters instead of octets, you should convert your strings first 1570pass characters instead of octets, you should convert your strings first
1360to the locale-specific encoding using C<< $term->locale_encode >>. 1571to the locale-specific encoding using C<< $term->locale_encode >>.
1572
1573=item $term->tt_paste ($octets)
1574
1575Write the octets given in C<$octets> to the tty as a paste, converting NL to
1576CR and bracketing the data with control sequences if bracketed paste mode
1577is set.
1361 1578
1362=item $old_events = $term->pty_ev_events ([$new_events]) 1579=item $old_events = $term->pty_ev_events ([$new_events])
1363 1580
1364Replaces the event mask of the pty watcher by the given event mask. Can 1581Replaces the event mask of the pty watcher by the given event mask. Can
1365be used to suppress input and output handling to the pty/tty. See the 1582be used to suppress input and output handling to the pty/tty. See the
1384Adds the specified events to the vt event mask. Useful e.g. when you want 1601Adds the specified events to the vt event mask. Useful e.g. when you want
1385to receive pointer events all the times: 1602to receive pointer events all the times:
1386 1603
1387 $term->vt_emask_add (urxvt::PointerMotionMask); 1604 $term->vt_emask_add (urxvt::PointerMotionMask);
1388 1605
1606=item $term->focus_in
1607
1608=item $term->focus_out
1609
1610=item $term->key_press ($state, $keycode[, $time])
1611
1612=item $term->key_release ($state, $keycode[, $time])
1613
1614Deliver various fake events to to terminal.
1615
1389=item $window_width = $term->width 1616=item $window_width = $term->width
1390 1617
1391=item $window_height = $term->height 1618=item $window_height = $term->height
1392 1619
1393=item $font_width = $term->fwidth 1620=item $font_width = $term->fwidth
1423=item $env = $term->env 1650=item $env = $term->env
1424 1651
1425Returns a copy of the environment in effect for the terminal as a hashref 1652Returns a copy of the environment in effect for the terminal as a hashref
1426similar to C<\%ENV>. 1653similar to C<\%ENV>.
1427 1654
1655=item @envv = $term->envv
1656
1657Returns the environment as array of strings of the form C<VAR=VALUE>.
1658
1659=item @argv = $term->argv
1660
1661Return the argument vector as this terminal, similar to @ARGV, but
1662includes the program name as first element.
1663
1428=cut 1664=cut
1429 1665
1430sub env { 1666sub env {
1431 if (my $env = $_[0]->_env) {
1432 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env } 1667 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), $_[0]->envv }
1433 } else {
1434 +{ %ENV }
1435 }
1436} 1668}
1437 1669
1438=item $modifiermask = $term->ModLevel3Mask 1670=item $modifiermask = $term->ModLevel3Mask
1439 1671
1440=item $modifiermask = $term->ModMetaMask 1672=item $modifiermask = $term->ModMetaMask
1448 1680
1449Returns the currently displayed screen (0 primary, 1 secondary). 1681Returns the currently displayed screen (0 primary, 1 secondary).
1450 1682
1451=item $cursor_is_hidden = $term->hidden_cursor 1683=item $cursor_is_hidden = $term->hidden_cursor
1452 1684
1453Returns wether the cursor is currently hidden or not. 1685Returns whether the cursor is currently hidden or not.
1454 1686
1455=item $view_start = $term->view_start ([$newvalue]) 1687=item $view_start = $term->view_start ([$newvalue])
1456 1688
1457Returns the row number of the topmost displayed line. Maximum value is 1689Returns the row number of the topmost displayed line. Maximum value is
1458C<0>, which displays the normal terminal contents. Lower values scroll 1690C<0>, which displays the normal terminal contents. Lower values scroll
1466 1698
1467Used after changing terminal contents to display them. 1699Used after changing terminal contents to display them.
1468 1700
1469=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]]) 1701=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
1470 1702
1471Returns the text of the entire row with number C<$row_number>. Row C<0> 1703Returns the text of the entire row with number C<$row_number>. Row C<< $term->top_row >>
1472is the topmost terminal line, row C<< $term->$ncol-1 >> is the bottommost 1704is the topmost terminal line, row C<< $term->nrow-1 >> is the bottommost
1473terminal line. The scrollback buffer starts at line C<-1> and extends to
1474line C<< -$term->nsaved >>. Nothing will be returned if a nonexistent line 1705terminal line. Nothing will be returned if a nonexistent line
1475is requested. 1706is requested.
1476 1707
1477If C<$new_text> is specified, it will replace characters in the current 1708If C<$new_text> is specified, it will replace characters in the current
1478line, starting at column C<$start_col> (default C<0>), which is useful 1709line, starting at column C<$start_col> (default C<0>), which is useful
1479to replace only parts of a line. The font index in the rendition will 1710to replace only parts of a line. The font index in the rendition will
1480automatically be updated. 1711automatically be updated.
1481 1712
1482C<$text> is in a special encoding: tabs and wide characters that use more 1713C<$text> is in a special encoding: tabs and wide characters that use more
1483than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535) 1714than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535)
1484characters. Characters with combining characters and other characters that 1715characters. Characters with combining characters and other characters that
1485do not fit into the normal tetx encoding will be replaced with characters 1716do not fit into the normal text encoding will be replaced with characters
1486in the private use area. 1717in the private use area.
1487 1718
1488You have to obey this encoding when changing text. The advantage is 1719You have to obey this encoding when changing text. The advantage is
1489that C<substr> and similar functions work on screen cells and not on 1720that C<substr> and similar functions work on screen cells and not on
1490characters. 1721characters.
1635where one character corresponds to one screen cell. See 1866where one character corresponds to one screen cell. See
1636C<< $term->ROW_t >> for details. 1867C<< $term->ROW_t >> for details.
1637 1868
1638=item $string = $term->special_decode $text 1869=item $string = $term->special_decode $text
1639 1870
1640Converts rxvt-unicodes text reprsentation into a perl string. See 1871Converts rxvt-unicodes text representation into a perl string. See
1641C<< $term->ROW_t >> for details. 1872C<< $term->ROW_t >> for details.
1642 1873
1643=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt]) 1874=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1644 1875
1645=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt]) 1876=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1648manpage. 1879manpage.
1649 1880
1650=item $success = $term->grab ($eventtime[, $sync]) 1881=item $success = $term->grab ($eventtime[, $sync])
1651 1882
1652Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1883Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1653synchronous (C<$sync> is true). Also remembers the grab timestampe. 1884synchronous (C<$sync> is true). Also remembers the grab timestamp.
1654 1885
1655=item $term->allow_events_async 1886=item $term->allow_events_async
1656 1887
1657Calls XAllowEvents with AsyncBoth for the most recent grab. 1888Calls XAllowEvents with AsyncBoth for the most recent grab.
1658 1889
1665Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most 1896Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most
1666recent grab. 1897recent grab.
1667 1898
1668=item $term->ungrab 1899=item $term->ungrab
1669 1900
1670Calls XUngrab for the most recent grab. Is called automatically on 1901Calls XUngrabPointer and XUngrabKeyboard for the most recent grab. Is called automatically on
1671evaluation errors, as it is better to lose the grab in the error case as 1902evaluation errors, as it is better to lose the grab in the error case as
1672the session. 1903the session.
1673 1904
1674=item $atom = $term->XInternAtom ($atom_name[, $only_if_exists]) 1905=item $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
1675 1906
1677 1908
1678=item @atoms = $term->XListProperties ($window) 1909=item @atoms = $term->XListProperties ($window)
1679 1910
1680=item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property) 1911=item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
1681 1912
1682=item $term->XChangeWindowProperty ($window, $property, $type, $format, $octets) 1913=item $term->XChangeProperty ($window, $property, $type, $format, $octets)
1683 1914
1684=item $term->XDeleteProperty ($window, $property) 1915=item $term->XDeleteProperty ($window, $property)
1685 1916
1686=item $window = $term->DefaultRootWindow 1917=item $window = $term->DefaultRootWindow
1687 1918
1697 1928
1698=item $term->XChangeInput ($window, $add_events[, $del_events]) 1929=item $term->XChangeInput ($window, $add_events[, $del_events])
1699 1930
1700Various X or X-related functions. The C<$term> object only serves as 1931Various X or X-related functions. The C<$term> object only serves as
1701the source of the display, otherwise those functions map more-or-less 1932the source of the display, otherwise those functions map more-or-less
1702directory onto the X functions of the same name. 1933directly onto the X functions of the same name.
1703 1934
1704=back 1935=back
1705 1936
1706=cut 1937=cut
1707 1938
1771 my ($self, $text, $cb) = @_; 2002 my ($self, $text, $cb) = @_;
1772 2003
1773 $self->add_item ({ type => "button", text => $text, activate => $cb}); 2004 $self->add_item ({ type => "button", text => $text, activate => $cb});
1774} 2005}
1775 2006
1776=item $popup->add_toggle ($text, $cb, $initial_value) 2007=item $popup->add_toggle ($text, $initial_value, $cb)
1777 2008
1778Adds a toggle/checkbox item to the popup. Teh callback gets called 2009Adds a toggle/checkbox item to the popup. The callback gets called
1779whenever it gets toggled, with a boolean indicating its value as its first 2010whenever it gets toggled, with a boolean indicating its new value as its
1780argument. 2011first argument.
1781 2012
1782=cut 2013=cut
1783 2014
1784sub add_toggle { 2015sub add_toggle {
1785 my ($self, $text, $cb, $value) = @_; 2016 my ($self, $text, $value, $cb) = @_;
1786 2017
1787 my $item; $item = { 2018 my $item; $item = {
1788 type => "button", 2019 type => "button",
1789 text => " $text", 2020 text => " $text",
1790 value => $value, 2021 value => $value,
1809 my $env = $self->{term}->env; 2040 my $env = $self->{term}->env;
1810 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE. 2041 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
1811 delete $env->{LC_ALL}; 2042 delete $env->{LC_ALL};
1812 $env->{LC_CTYPE} = $self->{term}->locale; 2043 $env->{LC_CTYPE} = $self->{term}->locale;
1813 2044
1814 urxvt::term->new ($env, "popup", 2045 my $term = urxvt::term->new (
2046 $env, "popup",
1815 "--perl-lib" => "", "--perl-ext-common" => "", 2047 "--perl-lib" => "", "--perl-ext-common" => "",
1816 "-pty-fd" => -1, "-sl" => 0, 2048 "-pty-fd" => -1, "-sl" => 0,
1817 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect", 2049 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect",
1818 "--transient-for" => $self->{term}->parent, 2050 "--transient-for" => $self->{term}->parent,
1819 "-display" => $self->{term}->display_id, 2051 "-display" => $self->{term}->display_id,
1820 "-pe" => "urxvt-popup") 2052 "-pe" => "urxvt-popup",
1821 or die "unable to create popup window\n"; 2053 ) or die "unable to create popup window\n";
2054
2055 unless (delete $term->{urxvt_popup_init_done}) {
2056 $term->ungrab;
2057 $term->destroy;
2058 die "unable to initialise popup window\n";
2059 }
1822} 2060}
1823 2061
1824sub DESTROY { 2062sub DESTROY {
1825 my ($self) = @_; 2063 my ($self) = @_;
1826 2064
1831=back 2069=back
1832 2070
1833=cut 2071=cut
1834 2072
1835package urxvt::watcher; 2073package urxvt::watcher;
1836
1837@urxvt::timer::ISA = __PACKAGE__;
1838@urxvt::iow::ISA = __PACKAGE__;
1839@urxvt::pw::ISA = __PACKAGE__;
1840@urxvt::iw::ISA = __PACKAGE__;
1841 2074
1842=head2 The C<urxvt::timer> Class 2075=head2 The C<urxvt::timer> Class
1843 2076
1844This class implements timer watchers/events. Time is represented as a 2077This class implements timer watchers/events. Time is represented as a
1845fractional number of seconds since the epoch. Example: 2078fractional number of seconds since the epoch. Example:
1849 ->new 2082 ->new
1850 ->interval (1) 2083 ->interval (1)
1851 ->cb (sub { 2084 ->cb (sub {
1852 $term->{overlay}->set (0, 0, 2085 $term->{overlay}->set (0, 0,
1853 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]); 2086 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
1854 }); 2087 });
1855 2088
1856=over 4 2089=over 4
1857 2090
1858=item $timer = new urxvt::timer 2091=item $timer = new urxvt::timer
1859 2092
1862 2095
1863=item $timer = $timer->cb (sub { my ($timer) = @_; ... }) 2096=item $timer = $timer->cb (sub { my ($timer) = @_; ... })
1864 2097
1865Set the callback to be called when the timer triggers. 2098Set the callback to be called when the timer triggers.
1866 2099
1867=item $tstamp = $timer->at
1868
1869Return the time this watcher will fire next.
1870
1871=item $timer = $timer->set ($tstamp) 2100=item $timer = $timer->set ($tstamp[, $interval])
1872 2101
1873Set the time the event is generated to $tstamp. 2102Set the time the event is generated to $tstamp (and optionally specifies a
2103new $interval).
1874 2104
1875=item $timer = $timer->interval ($interval) 2105=item $timer = $timer->interval ($interval)
1876 2106
1877Normally (and when C<$interval> is C<0>), the timer will automatically 2107By default (and when C<$interval> is C<0>), the timer will automatically
1878stop after it has fired once. If C<$interval> is non-zero, then the timer 2108stop after it has fired once. If C<$interval> is non-zero, then the timer
1879is automatically rescheduled at the given intervals. 2109is automatically rescheduled at the given intervals.
1880 2110
1881=item $timer = $timer->start 2111=item $timer = $timer->start
1882 2112
1883Start the timer. 2113Start the timer.
1884 2114
1885=item $timer = $timer->start ($tstamp) 2115=item $timer = $timer->start ($tstamp[, $interval])
1886 2116
1887Set the event trigger time to C<$tstamp> and start the timer. 2117Set the event trigger time to C<$tstamp> and start the timer. Optionally
2118also replaces the interval.
1888 2119
1889=item $timer = $timer->after ($delay) 2120=item $timer = $timer->after ($delay[, $interval])
1890 2121
1891Like C<start>, but sets the expiry timer to c<urxvt::NOW + $delay>. 2122Like C<start>, but sets the expiry timer to c<urxvt::NOW + $delay>.
1892 2123
1893=item $timer = $timer->stop 2124=item $timer = $timer->stop
1894 2125
1902 2133
1903 $term->{socket} = ... 2134 $term->{socket} = ...
1904 $term->{iow} = urxvt::iow 2135 $term->{iow} = urxvt::iow
1905 ->new 2136 ->new
1906 ->fd (fileno $term->{socket}) 2137 ->fd (fileno $term->{socket})
1907 ->events (urxvt::EVENT_READ) 2138 ->events (urxvt::EV_READ)
1908 ->start 2139 ->start
1909 ->cb (sub { 2140 ->cb (sub {
1910 my ($iow, $revents) = @_; 2141 my ($iow, $revents) = @_;
1911 # $revents must be 1 here, no need to check 2142 # $revents must be 1 here, no need to check
1912 sysread $term->{socket}, my $buf, 8192 2143 sysread $term->{socket}, my $buf, 8192
1925Set the callback to be called when io events are triggered. C<$reventmask> 2156Set the callback to be called when io events are triggered. C<$reventmask>
1926is a bitset as described in the C<events> method. 2157is a bitset as described in the C<events> method.
1927 2158
1928=item $iow = $iow->fd ($fd) 2159=item $iow = $iow->fd ($fd)
1929 2160
1930Set the filedescriptor (not handle) to watch. 2161Set the file descriptor (not handle) to watch.
1931 2162
1932=item $iow = $iow->events ($eventmask) 2163=item $iow = $iow->events ($eventmask)
1933 2164
1934Set the event mask to watch. The only allowed values are 2165Set the event mask to watch. The only allowed values are
1935C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed 2166C<urxvt::EV_READ> and C<urxvt::EV_WRITE>, which might be ORed
1936together, or C<urxvt::EVENT_NONE>. 2167together, or C<urxvt::EV_NONE>.
1937 2168
1938=item $iow = $iow->start 2169=item $iow = $iow->start
1939 2170
1940Start watching for requested events on the given handle. 2171Start watching for requested events on the given handle.
1941 2172
1942=item $iow = $iow->stop 2173=item $iow = $iow->stop
1943 2174
1944Stop watching for events on the given filehandle. 2175Stop watching for events on the given file handle.
1945 2176
1946=back 2177=back
1947 2178
1948=head2 The C<urxvt::iw> Class 2179=head2 The C<urxvt::iw> Class
1949 2180
1982 ->new 2213 ->new
1983 ->start ($pid) 2214 ->start ($pid)
1984 ->cb (sub { 2215 ->cb (sub {
1985 my ($pw, $exit_status) = @_; 2216 my ($pw, $exit_status) = @_;
1986 ... 2217 ...
1987 }); 2218 });
1988 2219
1989=over 4 2220=over 4
1990 2221
1991=item $pw = new urxvt::pw 2222=item $pw = new urxvt::pw
1992 2223
1996 2227
1997Set the callback to be called when the timer triggers. 2228Set the callback to be called when the timer triggers.
1998 2229
1999=item $pw = $timer->start ($pid) 2230=item $pw = $timer->start ($pid)
2000 2231
2001Tells the wqtcher to start watching for process C<$pid>. 2232Tells the watcher to start watching for process C<$pid>.
2002 2233
2003=item $pw = $pw->stop 2234=item $pw = $pw->stop
2004 2235
2005Stop the watcher. 2236Stop the watcher.
2006 2237
2019 2250
2020=item >= 3 - script loading and management 2251=item >= 3 - script loading and management
2021 2252
2022=item >=10 - all called hooks 2253=item >=10 - all called hooks
2023 2254
2024=item >=11 - hook reutrn values 2255=item >=11 - hook return values
2025 2256
2026=back 2257=back
2027 2258
2028=head1 AUTHOR 2259=head1 AUTHOR
2029 2260
2030 Marc Lehmann <pcg@goof.com> 2261 Marc Lehmann <schmorp@schmorp.de>
2031 http://software.schmorp.de/pkg/rxvt-unicode 2262 http://software.schmorp.de/pkg/rxvt-unicode
2032 2263
2033=cut 2264=cut
2034 2265
20351 22661
2267
2268# vim: sw=3:

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines