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.113 by root, Fri Jan 20 10:27:08 2006 UTC vs.
Revision 1.180 by root, Sat Dec 26 09:42:16 2009 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: \\|([^|]+)\\|
74
75Another example: Programs I use often output "absolute path: " at the
76beginning of a line when they process multiple files. The following
77pattern matches the filename (note, there is a single space at the very
78end):
79
80 URxvt.selection.pattern-0: ^(/[^:]+):\
71 81
72You can look at the source of the selection extension to see more 82You can look at the source of the selection extension to see more
73interesting uses, such as parsing a line from beginning to end. 83interesting uses, such as parsing a line from beginning to end.
74 84
75This extension also offers following bindable keyboard commands: 85This extension also offers following bindable keyboard commands:
87=item option-popup (enabled by default) 97=item option-popup (enabled by default)
88 98
89Binds 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
90runtime. 100runtime.
91 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
92=item selection-popup (enabled by default) 119=item selection-popup (enabled by default)
93 120
94Binds 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
95text into various other formats/action (such as uri unescaping, perl 122text into various other formats/action (such as uri unescaping, perl
96evalution, web-browser starting etc.), depending on content. 123evaluation, web-browser starting etc.), depending on content.
97 124
98Other extensions can extend this popup menu by pushing a code reference 125Other extensions can extend this popup menu by pushing a code reference
99onto C<@{ $term->{selection_popup_hook} }>, that is called whenever the 126onto C<@{ $term->{selection_popup_hook} }>, which gets called whenever the
100popup is displayed. 127popup is being displayed.
101 128
102It'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
103is 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.
104It 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
105string 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
106when the button gets activated and should transform C<$_>. 133when the button gets activated and should transform C<$_>.
107 134
108The 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
109the 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
110C<a>s: 137C<a>s:
111 138
112 push @{ $self->{term}{selection_popup_hook} }, sub { 139 push @{ $self->{term}{selection_popup_hook} }, sub {
113 /a/ ? ("a to be" => sub { s/a/b/g } 140 /a/ ? ("a to b" => sub { s/a/b/g }
114 : () 141 : ()
115 }; 142 };
116 143
117=item searchable-scrollback<hotkey> (enabled by default) 144=item searchable-scrollback<hotkey> (enabled by default)
118 145
125search. 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>
126search upwards/downwards in the scrollback buffer, C<End> jumps to the 153search upwards/downwards in the scrollback buffer, C<End> jumps to the
127bottom. 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
128was 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
129additionally stores the first match in the current line into the primary 156additionally stores the first match in the current line into the primary
130selection. 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.
164
165=item readline (enabled by default)
166
167A support package that tries to make editing with readline easier. At
168the moment, it reacts to clicking shift-left mouse button by trying to
169move the text cursor to this position. It does so by generating as many
170cursor-left or cursor-right keypresses as required (this only works
171for programs that correctly support wide characters).
172
173To avoid too many false positives, this is only done when:
174
175=over 4
176
177=item - the tty is in ICANON state.
178
179=item - the text cursor is visible.
180
181=item - the primary screen is currently being displayed.
182
183=item - the mouse is on the same (multi-row-) line as the text cursor.
184
185=back
186
187The normal selection mechanism isn't disabled, so quick successive clicks
188might interfere with selection creation in harmless ways.
131 189
132=item selection-autotransform 190=item selection-autotransform
133 191
134This selection allows you to do automatic transforms on a selection 192This selection allows you to do automatic transforms on a selection
135whenever a selection is made. 193whenever a selection is made.
162 220
163The first line tells the selection code to treat the unchanging part of 221The first line tells the selection code to treat the unchanging part of
164every error message as a selection pattern, and the second line transforms 222every error message as a selection pattern, and the second line transforms
165the message into vi commands to load the file. 223the message into vi commands to load the file.
166 224
167=item mark-urls 225=item tabbed
168 226
227This transforms the terminal into a tabbar with additional terminals, that
228is, it implements what is commonly referred to as "tabbed terminal". The topmost line
229displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one
230button per tab.
231
232Clicking a button will activate that tab. Pressing B<Shift-Left> and
233B<Shift-Right> will switch to the tab left or right of the current one,
234while B<Shift-Down> creates a new tab.
235
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):
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
169Uses per-line display filtering (C<on_line_update>) to underline urls and 250Uses per-line display filtering (C<on_line_update>) to underline text
170make them clickable. When middle-clicked, the program specified in the 251matching a certain pattern and make it clickable. When clicked with the
171resource C<urlLauncher> (default C<x-www-browser>) will be started with 252mouse button specified in the C<matcher.button> resource (default 2, or
172the 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.
173 258
174=item automove-background 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.
175 263
176This is basically a one-line extension that dynamically changes the background pixmap offset 264It is possible to activate the most recently seen match from the keyboard.
177to the window position, in effect creating the same effect as pseudo transparency with 265Simply bind a keysym to "perl:matcher" as seen in the example below.
178a custom pixmap. No scaling is supported in this mode. Exmaple:
179 266
180 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background 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
276
277=item xim-onthespot
278
279This (experimental) perl extension implements OnTheSpot editing. It does
280not work perfectly, and some input methods don't seem to work well with
281OnTheSpot editing in general, but it seems to work at least for SCIM and
282kinput2.
283
284You enable it by specifying this extension and a preedit style of
285C<OnTheSpot>, i.e.:
286
287 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot
288
289=item kuake<hotkey>
290
291A very primitive quake-console-like extension. It was inspired by a
292description of how the programs C<kuake> and C<yakuake> work: Whenever the
293user presses a global accelerator key (by default C<F10>), the terminal
294will show or hide itself. Another press of the accelerator key will hide
295or show it again.
296
297Initially, the window will not be shown when using this extension.
298
299This is useful if you need a single terminal that is not using any desktop
300space most of the time but is quickly available at the press of a key.
301
302The accelerator key is grabbed regardless of any modifiers, so this
303extension will actually grab a physical key just for this function.
304
305If you want a quake-like animation, tell your window manager to do so
306(fvwm can do it).
307
308=item overlay-osc
309
310This extension implements some OSC commands to display timed popups on the
311screen - useful for status displays from within scripts. You have to read
312the sources for more info.
181 313
182=item block-graphics-to-ascii 314=item block-graphics-to-ascii
183 315
184A 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
185by replacing all line-drawing characters (U+2500 .. U+259F) by a 317by replacing all line-drawing characters (U+2500 .. U+259F) by a
186similar-looking ascii character. 318similar-looking ascii character.
187 319
188=item digital-clock 320=item digital-clock
189 321
190Displays a digital clock using the built-in overlay. 322Displays a digital clock using the built-in overlay.
191 323
192=item example-refresh-hooks 324=item remote-clipboard
193 325
194Displays a very simple digital clock in the upper right corner of the 326Somewhat of a misnomer, this extension adds two menu entries to the
195window. Illustrates overwriting the refresh callbacks to create your own 327selection popup that allows one to run external commands to store the
196overlays or changes. 328selection somewhere and fetch it again.
329
330We use it to implement a "distributed selection mechanism", which just
331means that one command uploads the file to a remote server, and another
332reads it.
333
334The commands can be set using the C<URxvt.remote-selection.store> and
335C<URxvt.remote-selection.fetch> resources. The first should read the
336selection to store from STDIN (always in UTF-8), the second should provide
337the selection data on STDOUT (also in UTF-8).
338
339The defaults (which are likely useless to you) use rsh and cat:
340
341 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
342 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
197 343
198=item selection-pastebin 344=item selection-pastebin
199 345
200This is a little rarely useful extension that Uploads the selection as 346This is a little rarely useful extension that Uploads the selection as
201textfile to a remote site (or does other things). (The implementation is 347textfile to a remote site (or does other things). (The implementation is
221After 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
222in the C<selection-pastebin-url> resource (again, the % is the placeholder 368in the C<selection-pastebin-url> resource (again, the % is the placeholder
223for the filename): 369for the filename):
224 370
225 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.
377
378=item macosx-pastebin and macosx-pastebin-native
379
380These two modules implement an extended clipboard for Mac OS X. They are
381used like this:
382
383 URxvt.perl-ext-common: default,macosx-clipboard
384 URxvt.keysym.M-c: perl:macosx-clipboard:copy
385 URxvt.keysym.M-v: perl:macosx-clipboard:paste
386
387The difference between them is that the native variant requires a
388perl from apple's devkit or so, and C<maxosx-pastebin> requires the
389C<Mac::Pasteboard> module, works with other perls, has fewer bugs, is
390simpler etc. etc.
391
392=item example-refresh-hooks
393
394Displays a very simple digital clock in the upper right corner of the
395window. Illustrates overwriting the refresh callbacks to create your own
396overlays or changes.
226 397
227=back 398=back
228 399
229=head1 API DOCUMENTATION 400=head1 API DOCUMENTATION
230 401
264 435
265=back 436=back
266 437
267=head2 Extension Objects 438=head2 Extension Objects
268 439
269Very perl extension is a perl class. A separate perl object is created 440Every perl extension is a perl class. A separate perl object is created
270for each terminal and each extension and passed as the first parameter to 441for each terminal, and each terminal has its own set of extenion objects,
271hooks. So extensions can use their C<$self> object without having to think 442which are passed as the first parameter to hooks. So extensions can use
272about other extensions, with the exception of methods and members that 443their C<$self> object without having to think about clashes with other
444extensions or other terminals, with the exception of methods and members
273begin with an underscore character C<_>: these are reserved for internal 445that begin with an underscore character C<_>: these are reserved for
274use. 446internal use.
275 447
276Although it isn't a C<urxvt::term> object, you can call all methods of the 448Although it isn't a C<urxvt::term> object, you can call all methods of the
277C<urxvt::term> class on this object. 449C<urxvt::term> class on this object.
278 450
279It has the following methods and data members: 451It has the following methods and data members:
300=head2 Hooks 472=head2 Hooks
301 473
302The following subroutines can be declared in extension files, and will be 474The following subroutines can be declared in extension files, and will be
303called whenever the relevant event happens. 475called whenever the relevant event happens.
304 476
305The first argument passed to them is an extension oject as described in 477The first argument passed to them is an extension object as described in
306the in the C<Extension Objects> section. 478the in the C<Extension Objects> section.
307 479
308B<All> of these hooks must return a boolean value. If any of the called 480B<All> of these hooks must return a boolean value. If any of the called
309hooks returns true, then the event counts as being I<consumed>, and the 481hooks returns true, then the event counts as being I<consumed>, and the
310relevant action might not be carried out by the C++ code. 482relevant action might not be carried out by the C++ code.
323place. 495place.
324 496
325=item on_start $term 497=item on_start $term
326 498
327Called at the very end of initialisation of a new terminal, just before 499Called at the very end of initialisation of a new terminal, just before
328trying to map (display) the toplevel and returning to the mainloop. 500trying to map (display) the toplevel and returning to the main loop.
329 501
330=item on_destroy $term 502=item on_destroy $term
331 503
332Called whenever something tries to destroy terminal, before doing anything 504Called whenever something tries to destroy terminal, when the terminal is
333yet. If this hook returns true, then destruction is skipped, but this is 505still fully functional (not for long, though).
334rarely a good idea.
335 506
336=item on_reset $term 507=item on_reset $term
337 508
338Called after the screen is "reset" for any reason, such as resizing or 509Called after the screen is "reset" for any reason, such as resizing or
339control sequences. Here is where you can react on changes to size-related 510control sequences. Here is where you can react on changes to size-related
361 532
362Called whenever a selection has been copied, but before the selection is 533Called whenever a selection has been copied, but before the selection is
363requested from the server. The selection text can be queried and changed 534requested from the server. The selection text can be queried and changed
364by calling C<< $term->selection >>. 535by calling C<< $term->selection >>.
365 536
366Returning a true value aborts selection grabbing. It will still be hilighted. 537Returning a true value aborts selection grabbing. It will still be highlighted.
367 538
368=item on_sel_extend $term 539=item on_sel_extend $term
369 540
370Called whenever the user tries to extend the selection (e.g. with a double 541Called whenever the user tries to extend the selection (e.g. with a double
371click) and is either supposed to return false (normal operation), or 542click) and is either supposed to return false (normal operation), or
372should extend the selection itelf and return true to suppress the built-in 543should extend the selection itself and return true to suppress the built-in
373processing. This can happen multiple times, as long as the callback 544processing. This can happen multiple times, as long as the callback
374returns true, it will be called on every further click by the user and is 545returns true, it will be called on every further click by the user and is
375supposed to enlarge the selection more and more, if possible. 546supposed to enlarge the selection more and more, if possible.
376 547
377See the F<selection> example extension. 548See the F<selection> example extension.
378 549
379=item on_view_change $term, $offset 550=item on_view_change $term, $offset
380 551
381Called whenever the view offset changes, i..e the user or program 552Called whenever the view offset changes, i.e. the user or program
382scrolls. Offset C<0> means display the normal terminal, positive values 553scrolls. Offset C<0> means display the normal terminal, positive values
383show this many lines of scrollback. 554show this many lines of scrollback.
384 555
385=item on_scroll_back $term, $lines, $saved 556=item on_scroll_back $term, $lines, $saved
386 557
390 561
391It is called before lines are scrolled out (so rows 0 .. min ($lines - 1, 562It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
392$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total 563$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
393number of lines that will be in the scrollback buffer. 564number of lines that will be in the scrollback buffer.
394 565
395=item on_osc_seq $term, $string 566=item on_osc_seq $term, $op, $args, $resp
567
568Called on every OSC sequence and can be used to suppress it or modify its
569behaviour. The default should be to return an empty list. A true value
570suppresses execution of the request completely. Make sure you don't get
571confused by recursive invocations when you output an OSC sequence within
572this callback.
573
574C<on_osc_seq_perl> should be used for new behaviour.
575
576=item on_osc_seq_perl $term, $args, $resp
396 577
397Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 578Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
398operating system command) is processed. Cursor position and other state 579operating system command) is processed. Cursor position and other state
399information is up-to-date when this happens. For interoperability, the 580information is up-to-date when this happens. For interoperability, the
400string should start with the extension name and a colon, to distinguish 581string should start with the extension name (sans -osc) and a semicolon,
401it from commands for other extensions, and this might be enforced in the 582to distinguish it from commands for other extensions, and this might be
402future. 583enforced in the future.
584
585For example, C<overlay-osc> uses this:
586
587 sub on_osc_seq_perl {
588 my ($self, $osc, $resp) = @_;
589
590 return unless $osc =~ s/^overlay;//;
591
592 ... process remaining $osc string
593 }
403 594
404Be careful not ever to trust (in a security sense) the data you receive, 595Be careful not ever to trust (in a security sense) the data you receive,
405as its source can not easily be controleld (e-mail content, messages from 596as its source can not easily be controlled (e-mail content, messages from
406other users on the same system etc.). 597other users on the same system etc.).
598
599For responses, C<$resp> contains the end-of-args separator used by the
600sender.
407 601
408=item on_add_lines $term, $string 602=item on_add_lines $term, $string
409 603
410Called whenever text is about to be output, with the text as argument. You 604Called whenever text is about to be output, with the text as argument. You
411can filter/change and output the text yourself by returning a true value 605can filter/change and output the text yourself by returning a true value
432later with the already-modified line (e.g. if unrelated parts change), so 626later with the already-modified line (e.g. if unrelated parts change), so
433you cannot just toggle rendition bits, but only set them. 627you cannot just toggle rendition bits, but only set them.
434 628
435=item on_refresh_begin $term 629=item on_refresh_begin $term
436 630
437Called just before the screen gets redrawn. Can be used for overlay 631Called just before the screen gets redrawn. Can be used for overlay or
438or similar effects by modify terminal contents in refresh_begin, and 632similar effects by modifying the terminal contents in refresh_begin, and
439restoring them in refresh_end. The built-in overlay and selection display 633restoring them in refresh_end. The built-in overlay and selection display
440code is run after this hook, and takes precedence. 634code is run after this hook, and takes precedence.
441 635
442=item on_refresh_end $term 636=item on_refresh_end $term
443 637
444Called just after the screen gets redrawn. See C<on_refresh_begin>. 638Called just after the screen gets redrawn. See C<on_refresh_begin>.
445 639
446=item on_keyboard_command $term, $string 640=item on_user_command $term, $string
447 641
448Called whenever the user presses a key combination that has a 642Called whenever a user-configured event is being activated (e.g. via
449C<perl:string> action bound to it (see description of the B<keysym> 643a C<perl:string> action bound to a key, see description of the B<keysym>
450resource in the @@RXVT_NAME@@(1) manpage). 644resource in the @@RXVT_NAME@@(1) manpage).
645
646The event is simply the action string. This interface is assumed to change
647slightly in the future.
648
649=item on_resize_all_windows $tern, $new_width, $new_height
650
651Called just after the new window size has been calculated, but before
652windows are actually being resized or hints are being set. If this hook
653returns TRUE, setting of the window hints is being skipped.
451 654
452=item on_x_event $term, $event 655=item on_x_event $term, $event
453 656
454Called on every X event received on the vt window (and possibly other 657Called on every X event received on the vt window (and possibly other
455windows). Should only be used as a last resort. Most event structure 658windows). Should only be used as a last resort. Most event structure
456members are not passed. 659members are not passed.
457 660
661=item on_root_event $term, $event
662
663Like C<on_x_event>, but is called for events on the root window.
664
458=item on_focus_in $term 665=item on_focus_in $term
459 666
460Called whenever the window gets the keyboard focus, before rxvt-unicode 667Called whenever the window gets the keyboard focus, before rxvt-unicode
461does focus in processing. 668does focus in processing.
462 669
463=item on_focus_out $term 670=item on_focus_out $term
464 671
465Called wheneever the window loses keyboard focus, before rxvt-unicode does 672Called whenever the window loses keyboard focus, before rxvt-unicode does
466focus out processing. 673focus out processing.
467 674
468=item on_configure_notify $term, $event 675=item on_configure_notify $term, $event
676
677=item on_property_notify $term, $event
469 678
470=item on_key_press $term, $event, $keysym, $octets 679=item on_key_press $term, $event, $keysym, $octets
471 680
472=item on_key_release $term, $event, $keysym 681=item on_key_release $term, $event, $keysym
473 682
483 692
484Called whenever the corresponding X event is received for the terminal If 693Called whenever the corresponding X event is received for the terminal If
485the hook returns true, then the even will be ignored by rxvt-unicode. 694the hook returns true, then the even will be ignored by rxvt-unicode.
486 695
487The event is a hash with most values as named by Xlib (see the XEvent 696The event is a hash with most values as named by Xlib (see the XEvent
488manpage), with the additional members C<row> and C<col>, which are the row 697manpage), with the additional members C<row> and C<col>, which are the
489and column under the mouse cursor. 698(real, not screen-based) row and column under the mouse cursor.
490 699
491C<on_key_press> additionally receives the string rxvt-unicode would 700C<on_key_press> additionally receives the string rxvt-unicode would
492output, if any, in locale-specific encoding. 701output, if any, in locale-specific encoding.
493 702
494subwindow. 703subwindow.
704
705=item on_client_message $term, $event
706
707=item on_wm_protocols $term, $event
708
709=item on_wm_delete_window $term, $event
710
711Called when various types of ClientMessage events are received (all with
712format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
495 713
496=back 714=back
497 715
498=cut 716=cut
499 717
516our $LIBDIR; 734our $LIBDIR;
517our $RESNAME; 735our $RESNAME;
518our $RESCLASS; 736our $RESCLASS;
519our $RXVTNAME; 737our $RXVTNAME;
520 738
739our $NOCHAR = chr 0xffff;
740
521=head2 Variables in the C<urxvt> Package 741=head2 Variables in the C<urxvt> Package
522 742
523=over 4 743=over 4
524 744
525=item $urxvt::LIBDIR 745=item $urxvt::LIBDIR
540The current terminal. This variable stores the current C<urxvt::term> 760The current terminal. This variable stores the current C<urxvt::term>
541object, whenever a callback/hook is executing. 761object, whenever a callback/hook is executing.
542 762
543=item @urxvt::TERM_INIT 763=item @urxvt::TERM_INIT
544 764
545All coderefs in this array will be called as methods of the next newly 765All code references in this array will be called as methods of the next newly
546created C<urxvt::term> object (during the C<on_init> phase). The array 766created C<urxvt::term> object (during the C<on_init> phase). The array
547gets cleared before the codereferences that were in it are being executed, 767gets cleared before the code references that were in it are being executed,
548so coderefs can push themselves onto it again if they so desire. 768so references can push themselves onto it again if they so desire.
549 769
550This complements to the perl-eval commandline option, but gets executed 770This complements to the perl-eval command line option, but gets executed
551first. 771first.
552 772
553=item @urxvt::TERM_EXT 773=item @urxvt::TERM_EXT
554 774
555Works similar to C<@TERM_INIT>, but contains perl package/class names, which 775Works similar to C<@TERM_INIT>, but contains perl package/class names, which
576 796
577Using this function has the advantage that its output ends up in the 797Using this function has the advantage that its output ends up in the
578correct place, e.g. on stderr of the connecting urxvtc client. 798correct place, e.g. on stderr of the connecting urxvtc client.
579 799
580Messages have a size limit of 1023 bytes currently. 800Messages have a size limit of 1023 bytes currently.
801
802=item @terms = urxvt::termlist
803
804Returns all urxvt::term objects that exist in this process, regardless of
805whether they are started, being destroyed etc., so be careful. Only term
806objects that have perl extensions attached will be returned (because there
807is no urxvt::term objet associated with others).
581 808
582=item $time = urxvt::NOW 809=item $time = urxvt::NOW
583 810
584Returns the "current time" (as per the event loop). 811Returns the "current time" (as per the event loop).
585 812
643Return the foreground/background colour index, respectively. 870Return the foreground/background colour index, respectively.
644 871
645=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour 872=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
646 873
647=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour 874=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
875
876=item $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
648 877
649Replace the foreground/background colour in the rendition mask with the 878Replace the foreground/background colour in the rendition mask with the
650specified one. 879specified one.
651 880
652=item $value = urxvt::GET_CUSTOM $rend 881=item $value = urxvt::GET_CUSTOM $rend
671 unless $msg =~ /\n$/; 900 unless $msg =~ /\n$/;
672 urxvt::warn ($msg); 901 urxvt::warn ($msg);
673 }; 902 };
674} 903}
675 904
905no warnings 'utf8';
906
676my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 907my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
677 908
678sub verbose { 909sub verbose {
679 my ($level, $msg) = @_; 910 my ($level, $msg) = @_;
680 warn "$msg\n" if $level <= $verbosity; 911 warn "$msg\n" if $level <= $verbosity;
696 927
697 open my $fh, "<:raw", $path 928 open my $fh, "<:raw", $path
698 or die "$path: $!"; 929 or die "$path: $!";
699 930
700 my $source = 931 my $source =
701 "package $pkg; use strict; use utf8;\n" 932 "package $pkg; use strict; use utf8; no warnings 'utf8';\n"
702 . "#line 1 \"$path\"\n{\n" 933 . "#line 1 \"$path\"\n{\n"
703 . (do { local $/; <$fh> }) 934 . (do { local $/; <$fh> })
704 . "\n};\n1"; 935 . "\n};\n1";
705 936
706 eval $source 937 eval $source
717 local $TERM = shift; 948 local $TERM = shift;
718 my $htype = shift; 949 my $htype = shift;
719 950
720 if ($htype == 0) { # INIT 951 if ($htype == 0) { # INIT
721 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 952 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
722 953
723 my %ext_arg; 954 my %ext_arg;
724 955
725 { 956 {
726 my @init = @TERM_INIT; 957 my @init = @TERM_INIT;
727 @TERM_INIT = (); 958 @TERM_INIT = ();
731 $TERM->register_package ($_) for @pkg; 962 $TERM->register_package ($_) for @pkg;
732 } 963 }
733 964
734 for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) { 965 for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
735 if ($_ eq "default") { 966 if ($_ eq "default") {
736 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback); 967 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback readline);
737 } elsif (/^-(.*)$/) { 968 } elsif (/^-(.*)$/) {
738 delete $ext_arg{$1}; 969 delete $ext_arg{$1};
739 } elsif (/^([^<]+)<(.*)>$/) { 970 } elsif (/^([^<]+)<(.*)>$/) {
740 push @{ $ext_arg{$1} }, $2; 971 push @{ $ext_arg{$1} }, $2;
741 } else { 972 } else {
742 $ext_arg{$_} ||= []; 973 $ext_arg{$_} ||= [];
743 } 974 }
744 } 975 }
745 976
746 while (my ($ext, $argv) = each %ext_arg) { 977 for my $ext (sort keys %ext_arg) {
747 my @files = grep -f $_, map "$_/$ext", @dirs; 978 my @files = grep -f $_, map "$_/$ext", @dirs;
748 979
749 if (@files) { 980 if (@files) {
750 $TERM->register_package (extension_package $files[0], $argv); 981 $TERM->register_package (extension_package $files[0], $ext_arg{$ext});
751 } else { 982 } else {
752 warn "perl extension '$ext' not found in perl library search path\n"; 983 warn "perl extension '$ext' not found in perl library search path\n";
753 } 984 }
754 } 985 }
755 986
761 992
762 if (my $cb = $TERM->{_hook}[$htype]) { 993 if (my $cb = $TERM->{_hook}[$htype]) {
763 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")" 994 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
764 if $verbosity >= 10; 995 if $verbosity >= 10;
765 996
766 keys %$cb; 997 for my $pkg (keys %$cb) {
767
768 while (my ($pkg, $cb) = each %$cb) {
769 my $retval_ = eval { $cb->($TERM->{_pkg}{$pkg}, @_) }; 998 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg}, @_) };
770 $retval ||= $retval_; 999 $retval ||= $retval_;
771 1000
772 if ($@) { 1001 if ($@) {
773 $TERM->ungrab; # better to lose the grab than the session 1002 $TERM->ungrab; # better to lose the grab than the session
774 warn $@; 1003 warn $@;
786 # clear package 1015 # clear package
787 %$TERM = (); 1016 %$TERM = ();
788 } 1017 }
789 1018
790 $retval 1019 $retval
1020}
1021
1022sub SET_COLOR($$$) {
1023 SET_BGCOLOR (SET_FGCOLOR ($_[0], $_[1]), $_[2])
1024}
1025
1026sub rend2mask {
1027 no strict 'refs';
1028 my ($str, $mask) = (@_, 0);
1029 my %color = ( fg => undef, bg => undef );
1030 my @failed;
1031 for my $spec ( split /\s+/, $str ) {
1032 if ( $spec =~ /^([fb]g)[_:-]?(\d+)/i ) {
1033 $color{lc($1)} = $2;
1034 } else {
1035 my $neg = $spec =~ s/^[-^]//;
1036 unless ( exists &{"RS_$spec"} ) {
1037 push @failed, $spec;
1038 next;
1039 }
1040 my $cur = &{"RS_$spec"};
1041 if ( $neg ) {
1042 $mask &= ~$cur;
1043 } else {
1044 $mask |= $cur;
1045 }
1046 }
1047 }
1048 ($mask, @color{qw(fg bg)}, \@failed)
791} 1049}
792 1050
793# urxvt::term::extension 1051# urxvt::term::extension
794 1052
795package urxvt::term::extension; 1053package urxvt::term::extension;
866is that you cannot use blocking APIs, but the non-blocking variant should 1124is that you cannot use blocking APIs, but the non-blocking variant should
867work. 1125work.
868 1126
869=cut 1127=cut
870 1128
871our $VERSION = 1; 1129our $VERSION = '5.23';
872 1130
873$INC{"urxvt/anyevent.pm"} = 1; # mark us as there 1131$INC{"urxvt/anyevent.pm"} = 1; # mark us as there
874push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::]; 1132push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
875 1133
876sub timer { 1134sub timer {
878 1136
879 my $cb = $arg{cb}; 1137 my $cb = $arg{cb};
880 1138
881 urxvt::timer 1139 urxvt::timer
882 ->new 1140 ->new
883 ->start (urxvt::NOW + $arg{after}) 1141 ->after ($arg{after}, $arg{interval})
884 ->cb (sub { 1142 ->cb ($arg{interval} ? $cb : sub {
885 $_[0]->stop; # need to cancel manually 1143 $_[0]->stop; # need to cancel manually
886 $cb->(); 1144 $cb->();
887 }) 1145 })
888} 1146}
889 1147
890sub io { 1148sub io {
891 my ($class, %arg) = @_; 1149 my ($class, %arg) = @_;
892 1150
893 my $cb = $arg{cb}; 1151 my $cb = $arg{cb};
1152 my $fd = fileno $arg{fh};
1153 defined $fd or $fd = $arg{fh};
894 1154
895 bless [$arg{fh}, urxvt::iow 1155 bless [$arg{fh}, urxvt::iow
896 ->new 1156 ->new
897 ->fd (fileno $arg{fh}) 1157 ->fd ($fd)
898 ->events (($arg{poll} =~ /r/ ? 1 : 0) 1158 ->events (($arg{poll} =~ /r/ ? 1 : 0)
899 | ($arg{poll} =~ /w/ ? 2 : 0)) 1159 | ($arg{poll} =~ /w/ ? 2 : 0))
900 ->start 1160 ->start
901 ->cb (sub { 1161 ->cb ($cb)
902 $cb->(($_[1] & 1 ? 'r' : '')
903 . ($_[1] & 2 ? 'w' : ''));
904 })],
905 urxvt::anyevent:: 1162 ], urxvt::anyevent::
1163}
1164
1165sub idle {
1166 my ($class, %arg) = @_;
1167
1168 my $cb = $arg{cb};
1169
1170 urxvt::iw
1171 ->new
1172 ->start
1173 ->cb ($cb)
1174}
1175
1176sub child {
1177 my ($class, %arg) = @_;
1178
1179 my $cb = $arg{cb};
1180
1181 urxvt::pw
1182 ->new
1183 ->start ($arg{pid})
1184 ->cb (sub {
1185 $_[0]->stop; # need to cancel manually
1186 $cb->($_[0]->rpid, $_[0]->rstatus);
1187 })
906} 1188}
907 1189
908sub DESTROY { 1190sub DESTROY {
909 $_[0][1]->stop; 1191 $_[0][1]->stop;
910} 1192}
911 1193
912sub condvar { 1194sub one_event {
913 bless \my $flag, urxvt::anyevent::condvar::
914}
915
916sub urxvt::anyevent::condvar::broadcast {
917 ${$_[0]}++;
918}
919
920sub urxvt::anyevent::condvar::wait {
921 unless (${$_[0]}) {
922 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API"; 1195 Carp::croak "AnyEvent->one_event blocking wait unsupported in urxvt, use a non-blocking API";
923 }
924} 1196}
925 1197
926package urxvt::term; 1198package urxvt::term;
927 1199
928=head2 The C<urxvt::term> Class 1200=head2 The C<urxvt::term> Class
964hash which defines the environment of the new terminal. 1236hash which defines the environment of the new terminal.
965 1237
966Croaks (and probably outputs an error message) if the new instance 1238Croaks (and probably outputs an error message) if the new instance
967couldn't be created. Returns C<undef> if the new instance didn't 1239couldn't be created. Returns C<undef> if the new instance didn't
968initialise perl, and the terminal object otherwise. The C<init> and 1240initialise perl, and the terminal object otherwise. The C<init> and
969C<start> hooks will be called during this call. 1241C<start> hooks will be called before this call returns, and are free to
1242refer to global data (which is race free).
970 1243
971=cut 1244=cut
972 1245
973sub new { 1246sub new {
974 my ($class, $env, @args) = @_; 1247 my ($class, $env, @args) = @_;
975 1248
1249 $env or Carp::croak "environment hash missing in call to urxvt::term->new";
1250 @args or Carp::croak "name argument missing in call to urxvt::term->new";
1251
976 _new ([ map "$_=$env->{$_}", keys %$env ], @args); 1252 _new ([ map "$_=$env->{$_}", keys %$env ], \@args);
977} 1253}
978 1254
979=item $term->destroy 1255=item $term->destroy
980 1256
981Destroy the terminal object (close the window, free resources 1257Destroy the terminal object (close the window, free resources
1011 1287
1012Returns true if the option specified by C<$optval> is enabled, and 1288Returns true if the option specified by C<$optval> is enabled, and
1013optionally change it. All option values are stored by name in the hash 1289optionally change it. All option values are stored by name in the hash
1014C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash. 1290C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
1015 1291
1016Here is a a likely non-exhaustive list of option names, please see the 1292Here is a likely non-exhaustive list of option names, please see the
1017source file F</src/optinc.h> to see the actual list: 1293source file F</src/optinc.h> to see the actual list:
1018 1294
1019 borderLess console cursorBlink cursorUnderline hold iconic insecure 1295 borderLess console cursorBlink cursorUnderline hold iconic insecure
1020 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 1296 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
1021 override-redirect pastableTabs pointerBlank reverseVideo scrollBar 1297 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
1038likely change). 1314likely change).
1039 1315
1040Please note that resource strings will currently only be freed when the 1316Please note that resource strings will currently only be freed when the
1041terminal is destroyed, so changing options frequently will eat memory. 1317terminal is destroyed, so changing options frequently will eat memory.
1042 1318
1043Here is a a likely non-exhaustive list of resource names, not all of which 1319Here is a likely non-exhaustive list of resource names, not all of which
1044are supported in every build, please see the source file F</src/rsinc.h> 1320are supported in every build, please see the source file F</src/rsinc.h>
1045to see the actual list: 1321to see the actual list:
1046 1322
1047 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1323 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
1048 borderLess color cursorBlink cursorUnderline cutchars delete_key 1324 borderLess chdir color cursorBlink cursorUnderline cutchars delete_key
1049 display_name embed ext_bwidth fade font geometry hold iconName 1325 display_name embed ext_bwidth fade font geometry hold iconName
1050 imFont imLocale inputMethod insecure int_bwidth intensityStyles 1326 imFont imLocale inputMethod insecure int_bwidth intensityStyles
1051 italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier 1327 italicFont jumpScroll lineSpace letterSpace loginShell mapAlert meta8
1052 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval 1328 modifier mouseWheelScrollPage name override_redirect pastableTabs path
1053 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay 1329 perl_eval perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
1054 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar 1330 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
1055 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness 1331 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
1056 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle 1332 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
1057 secondaryScreen secondaryScroll selectstyle shade term_name title 1333 secondaryScreen secondaryScroll shade term_name title
1058 transient_for transparent transparent_all tripleclickwords utmpInhibit 1334 transient_for transparent transparent_all tripleclickwords utmpInhibit
1059 visualBell 1335 visualBell
1060 1336
1061=cut 1337=cut
1062 1338
1063sub resource($$;$) { 1339sub resource($$;$) {
1064 my ($self, $name) = (shift, shift); 1340 my ($self, $name) = (shift, shift);
1065 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 1341 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
1066 &urxvt::term::_resource 1342 goto &urxvt::term::_resource
1067} 1343}
1068 1344
1069=item $value = $term->x_resource ($pattern) 1345=item $value = $term->x_resource ($pattern)
1070 1346
1071Returns the X-Resource for the given pattern, excluding the program or 1347Returns the X-Resource for the given pattern, excluding the program or
1096 1372
1097=item ($row, $col) = $term->selection_beg ([$row, $col]) 1373=item ($row, $col) = $term->selection_beg ([$row, $col])
1098 1374
1099=item ($row, $col) = $term->selection_end ([$row, $col]) 1375=item ($row, $col) = $term->selection_end ([$row, $col])
1100 1376
1101Return the current values of the selection mark, begin or end positions, 1377Return the current values of the selection mark, begin or end positions.
1102and optionally set them to new values. 1378
1379When arguments are given, then the selection coordinates are set to
1380C<$row> and C<$col>, and the selection screen is set to the current
1381screen.
1382
1383=item $screen = $term->selection_screen ([$screen])
1384
1385Returns the current selection screen, and then optionally sets it.
1103 1386
1104=item $term->selection_make ($eventtime[, $rectangular]) 1387=item $term->selection_make ($eventtime[, $rectangular])
1105 1388
1106Tries to make a selection as set by C<selection_beg> and 1389Tries to make a selection as set by C<selection_beg> and
1107C<selection_end>. If C<$rectangular> is true (default: false), a 1390C<selection_end>. If C<$rectangular> is true (default: false), a
1154 1437
1155The methods currently supported on C<urxvt::overlay> objects are: 1438The methods currently supported on C<urxvt::overlay> objects are:
1156 1439
1157=over 4 1440=over 4
1158 1441
1159=item $overlay->set ($x, $y, $text, $rend) 1442=item $overlay->set ($x, $y, $text[, $rend])
1160 1443
1161Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts 1444Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts
1162text in rxvt-unicode's special encoding and an array of rendition values 1445text in rxvt-unicode's special encoding and an array of rendition values
1163at a specific position inside the overlay. 1446at a specific position inside the overlay.
1447
1448If C<$rend> is missing, then the rendition will not be changed.
1164 1449
1165=item $overlay->hide 1450=item $overlay->hide
1166 1451
1167If visible, hide the overlay, but do not destroy it. 1452If visible, hide the overlay, but do not destroy it.
1168 1453
1238 1523
1239Normally its not a good idea to use this function, as programs might be 1524Normally its not a good idea to use this function, as programs might be
1240confused by changes in cursor position or scrolling. Its useful inside a 1525confused by changes in cursor position or scrolling. Its useful inside a
1241C<on_add_lines> hook, though. 1526C<on_add_lines> hook, though.
1242 1527
1528=item $term->scr_change_screen ($screen)
1529
1530Switch to given screen - 0 primary, 1 secondary.
1531
1243=item $term->cmd_parse ($octets) 1532=item $term->cmd_parse ($octets)
1244 1533
1245Similar to C<scr_add_lines>, but the argument must be in the 1534Similar to C<scr_add_lines>, but the argument must be in the
1246locale-specific encoding of the terminal and can contain command sequences 1535locale-specific encoding of the terminal and can contain command sequences
1247(escape codes) that will be interpreted. 1536(escape codes) that will be interpreted.
1257Replaces the event mask of the pty watcher by the given event mask. Can 1546Replaces the event mask of the pty watcher by the given event mask. Can
1258be used to suppress input and output handling to the pty/tty. See the 1547be used to suppress input and output handling to the pty/tty. See the
1259description of C<< urxvt::timer->events >>. Make sure to always restore 1548description of C<< urxvt::timer->events >>. Make sure to always restore
1260the previous value. 1549the previous value.
1261 1550
1551=item $fd = $term->pty_fd
1552
1553Returns the master file descriptor for the pty in use, or C<-1> if no pty
1554is used.
1555
1262=item $windowid = $term->parent 1556=item $windowid = $term->parent
1263 1557
1264Return the window id of the toplevel window. 1558Return the window id of the toplevel window.
1265 1559
1266=item $windowid = $term->vt 1560=item $windowid = $term->vt
1272Adds the specified events to the vt event mask. Useful e.g. when you want 1566Adds the specified events to the vt event mask. Useful e.g. when you want
1273to receive pointer events all the times: 1567to receive pointer events all the times:
1274 1568
1275 $term->vt_emask_add (urxvt::PointerMotionMask); 1569 $term->vt_emask_add (urxvt::PointerMotionMask);
1276 1570
1571=item $term->focus_in
1572
1573=item $term->focus_out
1574
1575=item $term->key_press ($state, $keycode[, $time])
1576
1577=item $term->key_release ($state, $keycode[, $time])
1578
1579Deliver various fake events to to terminal.
1580
1277=item $window_width = $term->width 1581=item $window_width = $term->width
1278 1582
1279=item $window_height = $term->height 1583=item $window_height = $term->height
1280 1584
1281=item $font_width = $term->fwidth 1585=item $font_width = $term->fwidth
1311=item $env = $term->env 1615=item $env = $term->env
1312 1616
1313Returns a copy of the environment in effect for the terminal as a hashref 1617Returns a copy of the environment in effect for the terminal as a hashref
1314similar to C<\%ENV>. 1618similar to C<\%ENV>.
1315 1619
1620=item @envv = $term->envv
1621
1622Returns the environment as array of strings of the form C<VAR=VALUE>.
1623
1624=item @argv = $term->argv
1625
1626Return the argument vector as this terminal, similar to @ARGV, but
1627includes the program name as first element.
1628
1316=cut 1629=cut
1317 1630
1318sub env { 1631sub env {
1319 if (my $env = $_[0]->_env) {
1320 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env } 1632 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), $_[0]->envv }
1321 } else {
1322 +{ %ENV }
1323 }
1324} 1633}
1325 1634
1326=item $modifiermask = $term->ModLevel3Mask 1635=item $modifiermask = $term->ModLevel3Mask
1327 1636
1328=item $modifiermask = $term->ModMetaMask 1637=item $modifiermask = $term->ModMetaMask
1329 1638
1330=item $modifiermask = $term->ModNumLockMask 1639=item $modifiermask = $term->ModNumLockMask
1331 1640
1332Return the modifier masks corresponding to the "ISO Level 3 Shift" (often 1641Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
1333AltGr), the meta key (often Alt) and the num lock key, if applicable. 1642AltGr), the meta key (often Alt) and the num lock key, if applicable.
1643
1644=item $screen = $term->current_screen
1645
1646Returns the currently displayed screen (0 primary, 1 secondary).
1647
1648=item $cursor_is_hidden = $term->hidden_cursor
1649
1650Returns whether the cursor is currently hidden or not.
1334 1651
1335=item $view_start = $term->view_start ([$newvalue]) 1652=item $view_start = $term->view_start ([$newvalue])
1336 1653
1337Returns the row number of the topmost displayed line. Maximum value is 1654Returns the row number of the topmost displayed line. Maximum value is
1338C<0>, which displays the normal terminal contents. Lower values scroll 1655C<0>, which displays the normal terminal contents. Lower values scroll
1346 1663
1347Used after changing terminal contents to display them. 1664Used after changing terminal contents to display them.
1348 1665
1349=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]]) 1666=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
1350 1667
1351Returns the text of the entire row with number C<$row_number>. Row C<0> 1668Returns the text of the entire row with number C<$row_number>. Row C<< $term->top_row >>
1352is the topmost terminal line, row C<< $term->$ncol-1 >> is the bottommost 1669is the topmost terminal line, row C<< $term->nrow-1 >> is the bottommost
1353terminal line. The scrollback buffer starts at line C<-1> and extends to
1354line C<< -$term->nsaved >>. Nothing will be returned if a nonexistent line 1670terminal line. Nothing will be returned if a nonexistent line
1355is requested. 1671is requested.
1356 1672
1357If C<$new_text> is specified, it will replace characters in the current 1673If C<$new_text> is specified, it will replace characters in the current
1358line, starting at column C<$start_col> (default C<0>), which is useful 1674line, starting at column C<$start_col> (default C<0>), which is useful
1359to replace only parts of a line. The font index in the rendition will 1675to replace only parts of a line. The font index in the rendition will
1360automatically be updated. 1676automatically be updated.
1361 1677
1362C<$text> is in a special encoding: tabs and wide characters that use more 1678C<$text> is in a special encoding: tabs and wide characters that use more
1363than one cell when displayed are padded with urxvt::NOCHAR characters 1679than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535)
1364(C<chr 65535>). Characters with combining characters and other characters 1680characters. Characters with combining characters and other characters that
1365that do not fit into the normal tetx encoding will be replaced with 1681do not fit into the normal text encoding will be replaced with characters
1366characters in the private use area. 1682in the private use area.
1367 1683
1368You have to obey this encoding when changing text. The advantage is 1684You have to obey this encoding when changing text. The advantage is
1369that C<substr> and similar functions work on screen cells and not on 1685that C<substr> and similar functions work on screen cells and not on
1370characters. 1686characters.
1371 1687
1515where one character corresponds to one screen cell. See 1831where one character corresponds to one screen cell. See
1516C<< $term->ROW_t >> for details. 1832C<< $term->ROW_t >> for details.
1517 1833
1518=item $string = $term->special_decode $text 1834=item $string = $term->special_decode $text
1519 1835
1520Converts rxvt-unicodes text reprsentation into a perl string. See 1836Converts rxvt-unicodes text representation into a perl string. See
1521C<< $term->ROW_t >> for details. 1837C<< $term->ROW_t >> for details.
1522 1838
1523=item $success = $term->grab_button ($button, $modifiermask) 1839=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1524 1840
1841=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1842
1525Registers a synchronous button grab. See the XGrabButton manpage. 1843Register/unregister a synchronous button grab. See the XGrabButton
1844manpage.
1526 1845
1527=item $success = $term->grab ($eventtime[, $sync]) 1846=item $success = $term->grab ($eventtime[, $sync])
1528 1847
1529Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1848Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1530synchronous (C<$sync> is true). Also remembers the grab timestampe. 1849synchronous (C<$sync> is true). Also remembers the grab timestamp.
1531 1850
1532=item $term->allow_events_async 1851=item $term->allow_events_async
1533 1852
1534Calls XAllowEvents with AsyncBoth for the most recent grab. 1853Calls XAllowEvents with AsyncBoth for the most recent grab.
1535 1854
1545=item $term->ungrab 1864=item $term->ungrab
1546 1865
1547Calls XUngrab for the most recent grab. Is called automatically on 1866Calls XUngrab for the most recent grab. Is called automatically on
1548evaluation errors, as it is better to lose the grab in the error case as 1867evaluation errors, as it is better to lose the grab in the error case as
1549the session. 1868the session.
1869
1870=item $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
1871
1872=item $atom_name = $term->XGetAtomName ($atom)
1873
1874=item @atoms = $term->XListProperties ($window)
1875
1876=item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
1877
1878=item $term->XChangeProperty ($window, $property, $type, $format, $octets)
1879
1880=item $term->XDeleteProperty ($window, $property)
1881
1882=item $window = $term->DefaultRootWindow
1883
1884=item $term->XReparentWindow ($window, $parent, [$x, $y])
1885
1886=item $term->XMapWindow ($window)
1887
1888=item $term->XUnmapWindow ($window)
1889
1890=item $term->XMoveResizeWindow ($window, $x, $y, $width, $height)
1891
1892=item ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x, $y)
1893
1894=item $term->XChangeInput ($window, $add_events[, $del_events])
1895
1896Various X or X-related functions. The C<$term> object only serves as
1897the source of the display, otherwise those functions map more-or-less
1898directory onto the X functions of the same name.
1550 1899
1551=back 1900=back
1552 1901
1553=cut 1902=cut
1554 1903
1618 my ($self, $text, $cb) = @_; 1967 my ($self, $text, $cb) = @_;
1619 1968
1620 $self->add_item ({ type => "button", text => $text, activate => $cb}); 1969 $self->add_item ({ type => "button", text => $text, activate => $cb});
1621} 1970}
1622 1971
1623=item $popup->add_toggle ($text, $cb, $initial_value) 1972=item $popup->add_toggle ($text, $initial_value, $cb)
1624 1973
1625Adds a toggle/checkbox item to the popup. Teh callback gets called 1974Adds a toggle/checkbox item to the popup. The callback gets called
1626whenever it gets toggled, with a boolean indicating its value as its first 1975whenever it gets toggled, with a boolean indicating its new value as its
1627argument. 1976first argument.
1628 1977
1629=cut 1978=cut
1630 1979
1631sub add_toggle { 1980sub add_toggle {
1632 my ($self, $text, $cb, $value) = @_; 1981 my ($self, $text, $value, $cb) = @_;
1633 1982
1634 my $item; $item = { 1983 my $item; $item = {
1635 type => "button", 1984 type => "button",
1636 text => " $text", 1985 text => " $text",
1637 value => $value, 1986 value => $value,
1656 my $env = $self->{term}->env; 2005 my $env = $self->{term}->env;
1657 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE. 2006 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
1658 delete $env->{LC_ALL}; 2007 delete $env->{LC_ALL};
1659 $env->{LC_CTYPE} = $self->{term}->locale; 2008 $env->{LC_CTYPE} = $self->{term}->locale;
1660 2009
1661 urxvt::term->new ($env, "popup", 2010 my $term = urxvt::term->new (
2011 $env, "popup",
1662 "--perl-lib" => "", "--perl-ext-common" => "", 2012 "--perl-lib" => "", "--perl-ext-common" => "",
1663 "-pty-fd" => -1, "-sl" => 0, 2013 "-pty-fd" => -1, "-sl" => 0,
1664 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect", 2014 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect",
1665 "--transient-for" => $self->{term}->parent, 2015 "--transient-for" => $self->{term}->parent,
1666 "-display" => $self->{term}->display_id, 2016 "-display" => $self->{term}->display_id,
1667 "-pe" => "urxvt-popup") 2017 "-pe" => "urxvt-popup",
1668 or die "unable to create popup window\n"; 2018 ) or die "unable to create popup window\n";
2019
2020 unless (delete $term->{urxvt_popup_init_done}) {
2021 $term->ungrab;
2022 $term->destroy;
2023 die "unable to initialise popup window\n";
2024 }
1669} 2025}
1670 2026
1671sub DESTROY { 2027sub DESTROY {
1672 my ($self) = @_; 2028 my ($self) = @_;
1673 2029
1678=back 2034=back
1679 2035
1680=cut 2036=cut
1681 2037
1682package urxvt::watcher; 2038package urxvt::watcher;
1683
1684@urxvt::timer::ISA = __PACKAGE__;
1685@urxvt::iow::ISA = __PACKAGE__;
1686@urxvt::pw::ISA = __PACKAGE__;
1687@urxvt::iw::ISA = __PACKAGE__;
1688 2039
1689=head2 The C<urxvt::timer> Class 2040=head2 The C<urxvt::timer> Class
1690 2041
1691This class implements timer watchers/events. Time is represented as a 2042This class implements timer watchers/events. Time is represented as a
1692fractional number of seconds since the epoch. Example: 2043fractional number of seconds since the epoch. Example:
1696 ->new 2047 ->new
1697 ->interval (1) 2048 ->interval (1)
1698 ->cb (sub { 2049 ->cb (sub {
1699 $term->{overlay}->set (0, 0, 2050 $term->{overlay}->set (0, 0,
1700 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]); 2051 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
1701 }); 2052 });
1702 2053
1703=over 4 2054=over 4
1704 2055
1705=item $timer = new urxvt::timer 2056=item $timer = new urxvt::timer
1706 2057
1709 2060
1710=item $timer = $timer->cb (sub { my ($timer) = @_; ... }) 2061=item $timer = $timer->cb (sub { my ($timer) = @_; ... })
1711 2062
1712Set the callback to be called when the timer triggers. 2063Set the callback to be called when the timer triggers.
1713 2064
1714=item $tstamp = $timer->at
1715
1716Return the time this watcher will fire next.
1717
1718=item $timer = $timer->set ($tstamp) 2065=item $timer = $timer->set ($tstamp[, $interval])
1719 2066
1720Set the time the event is generated to $tstamp. 2067Set the time the event is generated to $tstamp (and optionally specifies a
2068new $interval).
1721 2069
1722=item $timer = $timer->interval ($interval) 2070=item $timer = $timer->interval ($interval)
1723 2071
1724Normally (and when C<$interval> is C<0>), the timer will automatically 2072By default (and when C<$interval> is C<0>), the timer will automatically
1725stop after it has fired once. If C<$interval> is non-zero, then the timer 2073stop after it has fired once. If C<$interval> is non-zero, then the timer
1726is automatically rescheduled at the given intervals. 2074is automatically rescheduled at the given intervals.
1727 2075
1728=item $timer = $timer->start 2076=item $timer = $timer->start
1729 2077
1730Start the timer. 2078Start the timer.
1731 2079
1732=item $timer = $timer->start ($tstamp) 2080=item $timer = $timer->start ($tstamp[, $interval])
1733 2081
1734Set the event trigger time to C<$tstamp> and start the timer. 2082Set the event trigger time to C<$tstamp> and start the timer. Optionally
2083also replaces the interval.
1735 2084
1736=item $timer = $timer->after ($delay) 2085=item $timer = $timer->after ($delay[, $interval])
1737 2086
1738Like C<start>, but sets the expiry timer to c<urxvt::NOW + $delay>. 2087Like C<start>, but sets the expiry timer to c<urxvt::NOW + $delay>.
1739 2088
1740=item $timer = $timer->stop 2089=item $timer = $timer->stop
1741 2090
1749 2098
1750 $term->{socket} = ... 2099 $term->{socket} = ...
1751 $term->{iow} = urxvt::iow 2100 $term->{iow} = urxvt::iow
1752 ->new 2101 ->new
1753 ->fd (fileno $term->{socket}) 2102 ->fd (fileno $term->{socket})
1754 ->events (urxvt::EVENT_READ) 2103 ->events (urxvt::EV_READ)
1755 ->start 2104 ->start
1756 ->cb (sub { 2105 ->cb (sub {
1757 my ($iow, $revents) = @_; 2106 my ($iow, $revents) = @_;
1758 # $revents must be 1 here, no need to check 2107 # $revents must be 1 here, no need to check
1759 sysread $term->{socket}, my $buf, 8192 2108 sysread $term->{socket}, my $buf, 8192
1772Set the callback to be called when io events are triggered. C<$reventmask> 2121Set the callback to be called when io events are triggered. C<$reventmask>
1773is a bitset as described in the C<events> method. 2122is a bitset as described in the C<events> method.
1774 2123
1775=item $iow = $iow->fd ($fd) 2124=item $iow = $iow->fd ($fd)
1776 2125
1777Set the filedescriptor (not handle) to watch. 2126Set the file descriptor (not handle) to watch.
1778 2127
1779=item $iow = $iow->events ($eventmask) 2128=item $iow = $iow->events ($eventmask)
1780 2129
1781Set the event mask to watch. The only allowed values are 2130Set the event mask to watch. The only allowed values are
1782C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed 2131C<urxvt::EV_READ> and C<urxvt::EV_WRITE>, which might be ORed
1783together, or C<urxvt::EVENT_NONE>. 2132together, or C<urxvt::EV_NONE>.
1784 2133
1785=item $iow = $iow->start 2134=item $iow = $iow->start
1786 2135
1787Start watching for requested events on the given handle. 2136Start watching for requested events on the given handle.
1788 2137
1789=item $iow = $iow->stop 2138=item $iow = $iow->stop
1790 2139
1791Stop watching for events on the given filehandle. 2140Stop watching for events on the given file handle.
2141
2142=back
2143
2144=head2 The C<urxvt::iw> Class
2145
2146This class implements idle watchers, that get called automatically when
2147the process is idle. They should return as fast as possible, after doing
2148some useful work.
2149
2150=over 4
2151
2152=item $iw = new urxvt::iw
2153
2154Create a new idle watcher object in stopped state.
2155
2156=item $iw = $iw->cb (sub { my ($iw) = @_; ... })
2157
2158Set the callback to be called when the watcher triggers.
2159
2160=item $timer = $timer->start
2161
2162Start the watcher.
2163
2164=item $timer = $timer->stop
2165
2166Stop the watcher.
2167
2168=back
2169
2170=head2 The C<urxvt::pw> Class
2171
2172This class implements process watchers. They create an event whenever a
2173process exits, after which they stop automatically.
2174
2175 my $pid = fork;
2176 ...
2177 $term->{pw} = urxvt::pw
2178 ->new
2179 ->start ($pid)
2180 ->cb (sub {
2181 my ($pw, $exit_status) = @_;
2182 ...
2183 });
2184
2185=over 4
2186
2187=item $pw = new urxvt::pw
2188
2189Create a new process watcher in stopped state.
2190
2191=item $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
2192
2193Set the callback to be called when the timer triggers.
2194
2195=item $pw = $timer->start ($pid)
2196
2197Tells the watcher to start watching for process C<$pid>.
2198
2199=item $pw = $pw->stop
2200
2201Stop the watcher.
1792 2202
1793=back 2203=back
1794 2204
1795=head1 ENVIRONMENT 2205=head1 ENVIRONMENT
1796 2206
1805 2215
1806=item >= 3 - script loading and management 2216=item >= 3 - script loading and management
1807 2217
1808=item >=10 - all called hooks 2218=item >=10 - all called hooks
1809 2219
1810=item >=11 - hook reutrn values 2220=item >=11 - hook return values
1811 2221
1812=back 2222=back
1813 2223
1814=head1 AUTHOR 2224=head1 AUTHOR
1815 2225
1817 http://software.schmorp.de/pkg/rxvt-unicode 2227 http://software.schmorp.de/pkg/rxvt-unicode
1818 2228
1819=cut 2229=cut
1820 2230
18211 22311
2232
2233# vim: sw=3:

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines