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.109 by root, Thu Jan 19 16:07:09 2006 UTC vs.
Revision 1.174 by root, Sat May 30 08:47:07 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
36You can activate them like this: 39You can activate them like this:
37 40
38 @@RXVT_NAME@@ -pe <extensionname> 41 @@RXVT_NAME@@ -pe <extensionname>
42
43Or by adding them to the resource for extensions loaded by default:
44
45 URxvt.perl-ext-common: default,selection-autotransform
39 46
40=over 4 47=over 4
41 48
42=item selection (enabled by default) 49=item selection (enabled by default)
43 50
… …
58 URxvt.selection.pattern-1: perl-regex 65 URxvt.selection.pattern-1: perl-regex
59 ... 66 ...
60 67
61The 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
62contain 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
63the match. For example, the followign adds a regex that matches everything 70the match. For example, the following adds a regex that matches everything
64between two vertical bars: 71between two vertical bars:
65 72
66 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: ^(/[^:]+):\
67 81
68You 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
69interesting uses, such as parsing a line from beginning to end. 83interesting uses, such as parsing a line from beginning to end.
70 84
71This extension also offers following bindable keyboard commands: 85This extension also offers following bindable keyboard commands:
… …
83=item option-popup (enabled by default) 97=item option-popup (enabled by default)
84 98
85Binds 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
86runtime. 100runtime.
87 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
88=item selection-popup (enabled by default) 119=item selection-popup (enabled by default)
89 120
90Binds 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
91text into various other formats/action (such as uri unescaping, perl 122text into various other formats/action (such as uri unescaping, perl
92evalution, web-browser starting etc.), depending on content. 123evaluation, web-browser starting etc.), depending on content.
93 124
94Other extensions can extend this popup menu by pushing a code reference onto 125Other extensions can extend this popup menu by pushing a code reference
95C<@urxvt::ext::selection_popup::hook>, that is called whenever the popup is displayed. 126onto C<@{ $term->{selection_popup_hook} }>, which gets called whenever the
127popup is being displayed.
96 128
97It'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
98is 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.
99It 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
100string 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
101when the button gets activated and should transform C<$_>. 133when the button gets activated and should transform C<$_>.
102 134
103The 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
104the 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
105C<a>s: 137C<a>s:
106 138
107 push urxvt::ext::selection_popup::hook, sub { 139 push @{ $self->{term}{selection_popup_hook} }, sub {
108 /a/ ? ("a to be" => sub { s/a/b/g } 140 /a/ ? ("a to b" => sub { s/a/b/g }
109 : () 141 : ()
110 }; 142 };
111
112Don't run it in a hook, otherwise the menu will grow and grow. Instead put
113it at the toplevel of your extension.
114 143
115=item searchable-scrollback<hotkey> (enabled by default) 144=item searchable-scrollback<hotkey> (enabled by default)
116 145
117Adds regex search functionality to the scrollback buffer, triggered 146Adds regex search functionality to the scrollback buffer, triggered
118by a hotkey (default: C<M-s>). While in search mode, normal terminal 147by a hotkey (default: C<M-s>). While in search mode, normal terminal
… …
123search. 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>
124search upwards/downwards in the scrollback buffer, C<End> jumps to the 153search upwards/downwards in the scrollback buffer, C<End> jumps to the
125bottom. 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
126was 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
127additionally stores the first match in the current line into the primary 156additionally stores the first match in the current line into the primary
128selection. 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.
129 189
130=item selection-autotransform 190=item selection-autotransform
131 191
132This selection allows you to do automatic transforms on a selection 192This selection allows you to do automatic transforms on a selection
133whenever a selection is made. 193whenever a selection is made.
… …
160 220
161The 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
162every error message as a selection pattern, and the second line transforms 222every error message as a selection pattern, and the second line transforms
163the message into vi commands to load the file. 223the message into vi commands to load the file.
164 224
165=item mark-urls 225=item tabbed
166 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
167Uses per-line display filtering (C<on_line_update>) to underline urls and 250Uses per-line display filtering (C<on_line_update>) to underline text
168make them clickable. When middle-clicked, the program specified in the 251matching a certain pattern and make it clickable. When clicked with the
169resource C<urlLauncher> (default C<x-www-browser>) will be started with 252mouse button specified in the C<matcher.button> resource (default 2, or
170the 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.
171 258
172=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.
173 263
174This 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.
175to 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.
176a custom pixmap. No scaling is supported in this mode. Exmaple:
177 266
178 @@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.
179 313
180=item block-graphics-to-ascii 314=item block-graphics-to-ascii
181 315
182A 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
183by replacing all line-drawing characters (U+2500 .. U+259F) by a 317by replacing all line-drawing characters (U+2500 .. U+259F) by a
184similar-looking ascii character. 318similar-looking ascii character.
185 319
186=item digital-clock 320=item digital-clock
187 321
188Displays a digital clock using the built-in overlay. 322Displays a digital clock using the built-in overlay.
189 323
190=item example-refresh-hooks 324=item remote-clipboard
191 325
192Displays a very simple digital clock in the upper right corner of the 326Somewhat of a misnomer, this extension adds two menu entries to the
193window. Illustrates overwriting the refresh callbacks to create your own 327selection popup that allows one to run external commands to store the
194overlays 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'
195 343
196=item selection-pastebin 344=item selection-pastebin
197 345
198This is a little rarely useful extension that Uploads the selection as 346This is a little rarely useful extension that Uploads the selection as
199textfile to a remote site (or does other things). (The implementation is 347textfile to a remote site (or does other things). (The implementation is
… …
219After 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
220in the C<selection-pastebin-url> resource (again, the % is the placeholder 368in the C<selection-pastebin-url> resource (again, the % is the placeholder
221for the filename): 369for the filename):
222 370
223 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.
224 397
225=back 398=back
226 399
227=head1 API DOCUMENTATION 400=head1 API DOCUMENTATION
228 401
… …
262 435
263=back 436=back
264 437
265=head2 Extension Objects 438=head2 Extension Objects
266 439
267Very 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
268for 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,
269hooks. 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
270about 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
271begin with an underscore character C<_>: these are reserved for internal 445that begin with an underscore character C<_>: these are reserved for
272use. 446internal use.
273 447
274Although 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
275C<urxvt::term> class on this object. 449C<urxvt::term> class on this object.
276 450
277It has the following methods and data members: 451It has the following methods and data members:
… …
298=head2 Hooks 472=head2 Hooks
299 473
300The following subroutines can be declared in extension files, and will be 474The following subroutines can be declared in extension files, and will be
301called whenever the relevant event happens. 475called whenever the relevant event happens.
302 476
303The 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
304the in the C<Extension Objects> section. 478the in the C<Extension Objects> section.
305 479
306B<All> of these hooks must return a boolean value. If it is true, then the 480B<All> of these hooks must return a boolean value. If any of the called
307event counts as being I<consumed>, and the invocation of other hooks is 481hooks returns true, then the event counts as being I<consumed>, and the
308skipped, and the relevant action might not be carried out by the C++ code. 482relevant action might not be carried out by the C++ code.
309 483
310I<< When in doubt, return a false value (preferably C<()>). >> 484I<< When in doubt, return a false value (preferably C<()>). >>
311 485
312=over 4 486=over 4
313 487
314=item on_init $term 488=item on_init $term
315 489
316Called after a new terminal object has been initialized, but before 490Called after a new terminal object has been initialized, but before
317windows are created or the command gets run. Most methods are unsafe to 491windows are created or the command gets run. Most methods are unsafe to
318call or deliver senseless data, as terminal size and other characteristics 492call or deliver senseless data, as terminal size and other characteristics
319have not yet been determined. You can safely query and change resources, 493have not yet been determined. You can safely query and change resources
320though. 494and options, though. For many purposes the C<on_start> hook is a better
495place.
496
497=item on_start $term
498
499Called at the very end of initialisation of a new terminal, just before
500trying to map (display) the toplevel and returning to the main loop.
501
502=item on_destroy $term
503
504Called whenever something tries to destroy terminal, when the terminal is
505still fully functional (not for long, though).
321 506
322=item on_reset $term 507=item on_reset $term
323 508
324Called 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
325control 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
326variables. 511variables.
327 512
328=item on_start $term
329
330Called at the very end of initialisation of a new terminal, just before
331returning to the mainloop.
332
333=item on_child_start $term, $pid 513=item on_child_start $term, $pid
334 514
335Called just after the child process has been C<fork>ed. 515Called just after the child process has been C<fork>ed.
336 516
337=item on_child_exit $term, $status 517=item on_child_exit $term, $status
… …
352 532
353Called whenever a selection has been copied, but before the selection is 533Called whenever a selection has been copied, but before the selection is
354requested from the server. The selection text can be queried and changed 534requested from the server. The selection text can be queried and changed
355by calling C<< $term->selection >>. 535by calling C<< $term->selection >>.
356 536
357Returning a true value aborts selection grabbing. It will still be hilighted. 537Returning a true value aborts selection grabbing. It will still be highlighted.
358 538
359=item on_sel_extend $term 539=item on_sel_extend $term
360 540
361Called 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
362click) and is either supposed to return false (normal operation), or 542click) and is either supposed to return false (normal operation), or
363should 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
364processing. This can happen multiple times, as long as the callback 544processing. This can happen multiple times, as long as the callback
365returns 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
366supposed to enlarge the selection more and more, if possible. 546supposed to enlarge the selection more and more, if possible.
367 547
368See the F<selection> example extension. 548See the F<selection> example extension.
369 549
370=item on_view_change $term, $offset 550=item on_view_change $term, $offset
371 551
372Called whenever the view offset changes, i..e the user or program 552Called whenever the view offset changes, i.e. the user or program
373scrolls. Offset C<0> means display the normal terminal, positive values 553scrolls. Offset C<0> means display the normal terminal, positive values
374show this many lines of scrollback. 554show this many lines of scrollback.
375 555
376=item on_scroll_back $term, $lines, $saved 556=item on_scroll_back $term, $lines, $saved
377 557
… …
381 561
382It 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,
383$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
384number of lines that will be in the scrollback buffer. 564number of lines that will be in the scrollback buffer.
385 565
386=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
387 577
388Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 578Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
389operating system command) is processed. Cursor position and other state 579operating system command) is processed. Cursor position and other state
390information is up-to-date when this happens. For interoperability, the 580information is up-to-date when this happens. For interoperability, the
391string should start with the extension name and a colon, to distinguish 581string should start with the extension name (sans -osc) and a semicolon,
392it from commands for other extensions, and this might be enforced in the 582to distinguish it from commands for other extensions, and this might be
393future. 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 }
394 594
395Be 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,
396as 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
397other 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.
398 601
399=item on_add_lines $term, $string 602=item on_add_lines $term, $string
400 603
401Called 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
402can 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
… …
423later 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
424you cannot just toggle rendition bits, but only set them. 627you cannot just toggle rendition bits, but only set them.
425 628
426=item on_refresh_begin $term 629=item on_refresh_begin $term
427 630
428Called just before the screen gets redrawn. Can be used for overlay 631Called just before the screen gets redrawn. Can be used for overlay or
429or similar effects by modify terminal contents in refresh_begin, and 632similar effects by modifying the terminal contents in refresh_begin, and
430restoring them in refresh_end. The built-in overlay and selection display 633restoring them in refresh_end. The built-in overlay and selection display
431code is run after this hook, and takes precedence. 634code is run after this hook, and takes precedence.
432 635
433=item on_refresh_end $term 636=item on_refresh_end $term
434 637
435Called just after the screen gets redrawn. See C<on_refresh_begin>. 638Called just after the screen gets redrawn. See C<on_refresh_begin>.
436 639
437=item on_keyboard_command $term, $string 640=item on_user_command $term, $string
438 641
439Called whenever the user presses a key combination that has a 642Called whenever a user-configured event is being activated (e.g. via
440C<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>
441resource 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.
442 654
443=item on_x_event $term, $event 655=item on_x_event $term, $event
444 656
445Called 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
446windows). Should only be used as a last resort. Most event structure 658windows). Should only be used as a last resort. Most event structure
447members are not passed. 659members are not passed.
448 660
661=item on_root_event $term, $event
662
663Like C<on_x_event>, but is called for events on the root window.
664
449=item on_focus_in $term 665=item on_focus_in $term
450 666
451Called whenever the window gets the keyboard focus, before rxvt-unicode 667Called whenever the window gets the keyboard focus, before rxvt-unicode
452does focus in processing. 668does focus in processing.
453 669
454=item on_focus_out $term 670=item on_focus_out $term
455 671
456Called wheneever the window loses keyboard focus, before rxvt-unicode does 672Called whenever the window loses keyboard focus, before rxvt-unicode does
457focus out processing. 673focus out processing.
458 674
459=item on_configure_notify $term, $event 675=item on_configure_notify $term, $event
676
677=item on_property_notify $term, $event
460 678
461=item on_key_press $term, $event, $keysym, $octets 679=item on_key_press $term, $event, $keysym, $octets
462 680
463=item on_key_release $term, $event, $keysym 681=item on_key_release $term, $event, $keysym
464 682
… …
474 692
475Called whenever the corresponding X event is received for the terminal If 693Called whenever the corresponding X event is received for the terminal If
476the 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.
477 695
478The 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
479manpage), 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
480and column under the mouse cursor. 698(real, not screen-based) row and column under the mouse cursor.
481 699
482C<on_key_press> additionally receives the string rxvt-unicode would 700C<on_key_press> additionally receives the string rxvt-unicode would
483output, if any, in locale-specific encoding. 701output, if any, in locale-specific encoding.
484 702
485subwindow. 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).
486 713
487=back 714=back
488 715
489=cut 716=cut
490 717
… …
496use Scalar::Util (); 723use Scalar::Util ();
497use List::Util (); 724use List::Util ();
498 725
499our $VERSION = 1; 726our $VERSION = 1;
500our $TERM; 727our $TERM;
728our @TERM_INIT;
729our @TERM_EXT;
501our @HOOKNAME; 730our @HOOKNAME;
502our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME; 731our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
503our %OPTION; 732our %OPTION;
504 733
505our $LIBDIR; 734our $LIBDIR;
506our $RESNAME; 735our $RESNAME;
507our $RESCLASS; 736our $RESCLASS;
508our $RXVTNAME; 737our $RXVTNAME;
509 738
739our $NOCHAR = chr 0xffff;
740
510=head2 Variables in the C<urxvt> Package 741=head2 Variables in the C<urxvt> Package
511 742
512=over 4 743=over 4
513 744
514=item $urxvt::LIBDIR 745=item $urxvt::LIBDIR
… …
526 757
527=item $urxvt::TERM 758=item $urxvt::TERM
528 759
529The current terminal. This variable stores the current C<urxvt::term> 760The current terminal. This variable stores the current C<urxvt::term>
530object, whenever a callback/hook is executing. 761object, whenever a callback/hook is executing.
762
763=item @urxvt::TERM_INIT
764
765All code references in this array will be called as methods of the next newly
766created C<urxvt::term> object (during the C<on_init> phase). The array
767gets cleared before the code references that were in it are being executed,
768so references can push themselves onto it again if they so desire.
769
770This complements to the perl-eval command line option, but gets executed
771first.
772
773=item @urxvt::TERM_EXT
774
775Works similar to C<@TERM_INIT>, but contains perl package/class names, which
776get registered as normal extensions after calling the hooks in C<@TERM_INIT>
777but before other extensions. Gets cleared just like C<@TERM_INIT>.
531 778
532=back 779=back
533 780
534=head2 Functions in the C<urxvt> Package 781=head2 Functions in the C<urxvt> Package
535 782
… …
549 796
550Using 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
551correct place, e.g. on stderr of the connecting urxvtc client. 798correct place, e.g. on stderr of the connecting urxvtc client.
552 799
553Messages 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).
554 808
555=item $time = urxvt::NOW 809=item $time = urxvt::NOW
556 810
557Returns the "current time" (as per the event loop). 811Returns the "current time" (as per the event loop).
558 812
… …
616Return the foreground/background colour index, respectively. 870Return the foreground/background colour index, respectively.
617 871
618=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour 872=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
619 873
620=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
621 877
622Replace the foreground/background colour in the rendition mask with the 878Replace the foreground/background colour in the rendition mask with the
623specified one. 879specified one.
624 880
625=item $value = urxvt::GET_CUSTOM $rend 881=item $value = urxvt::GET_CUSTOM $rend
… …
644 unless $msg =~ /\n$/; 900 unless $msg =~ /\n$/;
645 urxvt::warn ($msg); 901 urxvt::warn ($msg);
646 }; 902 };
647} 903}
648 904
905no warnings 'utf8';
906
649my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 907my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
650 908
651sub verbose { 909sub verbose {
652 my ($level, $msg) = @_; 910 my ($level, $msg) = @_;
653 warn "$msg\n" if $level <= $verbosity; 911 warn "$msg\n" if $level <= $verbosity;
… …
656my %extension_pkg; 914my %extension_pkg;
657 915
658# load a single script into its own package, once only 916# load a single script into its own package, once only
659sub extension_package($) { 917sub extension_package($) {
660 my ($path) = @_; 918 my ($path) = @_;
661
662 no strict 'refs';
663 919
664 $extension_pkg{$path} ||= do { 920 $extension_pkg{$path} ||= do {
665 $path =~ /([^\/\\]+)$/; 921 $path =~ /([^\/\\]+)$/;
666 my $pkg = $1; 922 my $pkg = $1;
667 $pkg =~ s/[^[:word:]]/_/g; 923 $pkg =~ s/[^[:word:]]/_/g;
… …
670 verbose 3, "loading extension '$path' into package '$pkg'"; 926 verbose 3, "loading extension '$path' into package '$pkg'";
671 927
672 open my $fh, "<:raw", $path 928 open my $fh, "<:raw", $path
673 or die "$path: $!"; 929 or die "$path: $!";
674 930
675 @{"$pkg\::ISA"} = urxvt::term::extension::;
676
677 my $source = 931 my $source =
678 "package $pkg; use strict; use utf8;\n" 932 "package $pkg; use strict; use utf8; no warnings 'utf8';\n"
679 . "#line 1 \"$path\"\n{\n" 933 . "#line 1 \"$path\"\n{\n"
680 . (do { local $/; <$fh> }) 934 . (do { local $/; <$fh> })
681 . "\n};\n1"; 935 . "\n};\n1";
682 936
683 eval $source 937 eval $source
… …
694 local $TERM = shift; 948 local $TERM = shift;
695 my $htype = shift; 949 my $htype = shift;
696 950
697 if ($htype == 0) { # INIT 951 if ($htype == 0) { # INIT
698 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 952 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
699 953
700 my %ext_arg; 954 my %ext_arg;
701 955
956 {
957 my @init = @TERM_INIT;
958 @TERM_INIT = ();
959 $_->($TERM) for @init;
960 my @pkg = @TERM_EXT;
961 @TERM_EXT = ();
962 $TERM->register_package ($_) for @pkg;
963 }
964
702 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) { 965 for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
703 if ($_ eq "default") { 966 if ($_ eq "default") {
704 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback); 967 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback readline);
705 } elsif (/^-(.*)$/) { 968 } elsif (/^-(.*)$/) {
706 delete $ext_arg{$1}; 969 delete $ext_arg{$1};
707 } elsif (/^([^<]+)<(.*)>$/) { 970 } elsif (/^([^<]+)<(.*)>$/) {
708 push @{ $ext_arg{$1} }, $2; 971 push @{ $ext_arg{$1} }, $2;
709 } else { 972 } else {
710 $ext_arg{$_} ||= []; 973 $ext_arg{$_} ||= [];
711 } 974 }
712 } 975 }
713 976
714 while (my ($ext, $argv) = each %ext_arg) { 977 for my $ext (sort keys %ext_arg) {
715 my @files = grep -f $_, map "$_/$ext", @dirs; 978 my @files = grep -f $_, map "$_/$ext", @dirs;
716 979
717 if (@files) { 980 if (@files) {
718 $TERM->register_package (extension_package $files[0], $argv); 981 $TERM->register_package (extension_package $files[0], $ext_arg{$ext});
719 } else { 982 } else {
720 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";
721 } 984 }
722 } 985 }
723 986
… …
729 992
730 if (my $cb = $TERM->{_hook}[$htype]) { 993 if (my $cb = $TERM->{_hook}[$htype]) {
731 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")" 994 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
732 if $verbosity >= 10; 995 if $verbosity >= 10;
733 996
734 keys %$cb; 997 for my $pkg (keys %$cb) {
735
736 while (my ($pkg, $cb) = each %$cb) {
737 $retval = eval { $cb->($TERM->{_pkg}{$pkg}, @_) } 998 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg}, @_) };
738 and last; 999 $retval ||= $retval_;
739 1000
740 if ($@) { 1001 if ($@) {
741 $TERM->ungrab; # better to lose the grab than the session 1002 $TERM->ungrab; # better to lose the grab than the session
742 warn $@; 1003 warn $@;
743 } 1004 }
… …
754 # clear package 1015 # clear package
755 %$TERM = (); 1016 %$TERM = ();
756 } 1017 }
757 1018
758 $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)
759} 1049}
760 1050
761# urxvt::term::extension 1051# urxvt::term::extension
762 1052
763package urxvt::term::extension; 1053package urxvt::term::extension;
… …
834is 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
835work. 1125work.
836 1126
837=cut 1127=cut
838 1128
839our $VERSION = 1; 1129our $VERSION = '3.4';
840 1130
841$INC{"urxvt/anyevent.pm"} = 1; # mark us as there 1131$INC{"urxvt/anyevent.pm"} = 1; # mark us as there
842push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::]; 1132push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
843 1133
844sub timer { 1134sub timer {
… …
875 1165
876sub DESTROY { 1166sub DESTROY {
877 $_[0][1]->stop; 1167 $_[0][1]->stop;
878} 1168}
879 1169
880sub condvar { 1170sub one_event {
881 bless \my $flag, urxvt::anyevent::condvar::
882}
883
884sub urxvt::anyevent::condvar::broadcast {
885 ${$_[0]}++;
886}
887
888sub urxvt::anyevent::condvar::wait {
889 unless (${$_[0]}) {
890 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API"; 1171 Carp::croak "AnyEvent->one_event blocking wait unsupported in urxvt, use a non-blocking API";
891 }
892} 1172}
893 1173
894package urxvt::term; 1174package urxvt::term;
895 1175
896=head2 The C<urxvt::term> Class 1176=head2 The C<urxvt::term> Class
… …
901 1181
902# find on_xxx subs in the package and register them 1182# find on_xxx subs in the package and register them
903# as hooks 1183# as hooks
904sub register_package { 1184sub register_package {
905 my ($self, $pkg, $argv) = @_; 1185 my ($self, $pkg, $argv) = @_;
1186
1187 no strict 'refs';
1188
1189 urxvt::verbose 6, "register package $pkg to $self";
1190
1191 @{"$pkg\::ISA"} = urxvt::term::extension::;
906 1192
907 my $proxy = bless { 1193 my $proxy = bless {
908 _pkg => $pkg, 1194 _pkg => $pkg,
909 argv => $argv, 1195 argv => $argv,
910 }, $pkg; 1196 }, $pkg;
… …
926hash which defines the environment of the new terminal. 1212hash which defines the environment of the new terminal.
927 1213
928Croaks (and probably outputs an error message) if the new instance 1214Croaks (and probably outputs an error message) if the new instance
929couldn't be created. Returns C<undef> if the new instance didn't 1215couldn't be created. Returns C<undef> if the new instance didn't
930initialise perl, and the terminal object otherwise. The C<init> and 1216initialise perl, and the terminal object otherwise. The C<init> and
931C<start> hooks will be called during this call. 1217C<start> hooks will be called before this call returns, and are free to
1218refer to global data (which is race free).
932 1219
933=cut 1220=cut
934 1221
935sub new { 1222sub new {
936 my ($class, $env, @args) = @_; 1223 my ($class, $env, @args) = @_;
937 1224
1225 $env or Carp::croak "environment hash missing in call to urxvt::term->new";
1226 @args or Carp::croak "name argument missing in call to urxvt::term->new";
1227
938 _new ([ map "$_=$env->{$_}", keys %$env ], @args); 1228 _new ([ map "$_=$env->{$_}", keys %$env ], \@args);
939} 1229}
940 1230
941=item $term->destroy 1231=item $term->destroy
942 1232
943Destroy the terminal object (close the window, free resources 1233Destroy the terminal object (close the window, free resources
… …
973 1263
974Returns true if the option specified by C<$optval> is enabled, and 1264Returns true if the option specified by C<$optval> is enabled, and
975optionally change it. All option values are stored by name in the hash 1265optionally change it. All option values are stored by name in the hash
976C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash. 1266C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
977 1267
978Here is a a likely non-exhaustive list of option names, please see the 1268Here is a likely non-exhaustive list of option names, please see the
979source file F</src/optinc.h> to see the actual list: 1269source file F</src/optinc.h> to see the actual list:
980 1270
981 borderLess console cursorBlink cursorUnderline hold iconic insecure 1271 borderLess console cursorBlink cursorUnderline hold iconic insecure
982 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 1272 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
983 override-redirect pastableTabs pointerBlank reverseVideo scrollBar 1273 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
… …
1000likely change). 1290likely change).
1001 1291
1002Please note that resource strings will currently only be freed when the 1292Please note that resource strings will currently only be freed when the
1003terminal is destroyed, so changing options frequently will eat memory. 1293terminal is destroyed, so changing options frequently will eat memory.
1004 1294
1005Here is a a likely non-exhaustive list of resource names, not all of which 1295Here is a likely non-exhaustive list of resource names, not all of which
1006are supported in every build, please see the source file F</src/rsinc.h> 1296are supported in every build, please see the source file F</src/rsinc.h>
1007to see the actual list: 1297to see the actual list:
1008 1298
1009 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1299 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
1010 borderLess color cursorBlink cursorUnderline cutchars delete_key 1300 borderLess chdir color cursorBlink cursorUnderline cutchars delete_key
1011 display_name embed ext_bwidth fade font geometry hold iconName 1301 display_name embed ext_bwidth fade font geometry hold iconName
1012 imFont imLocale inputMethod insecure int_bwidth intensityStyles 1302 imFont imLocale inputMethod insecure int_bwidth intensityStyles
1013 italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier 1303 italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier
1014 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval 1304 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
1015 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay 1305 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
1016 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar 1306 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
1017 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness 1307 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
1018 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle 1308 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
1019 secondaryScreen secondaryScroll selectstyle shade term_name title 1309 secondaryScreen secondaryScroll shade term_name title
1020 transient_for transparent transparent_all tripleclickwords utmpInhibit 1310 transient_for transparent transparent_all tripleclickwords utmpInhibit
1021 visualBell 1311 visualBell
1022 1312
1023=cut 1313=cut
1024 1314
1025sub resource($$;$) { 1315sub resource($$;$) {
1026 my ($self, $name) = (shift, shift); 1316 my ($self, $name) = (shift, shift);
1027 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 1317 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
1028 &urxvt::term::_resource 1318 goto &urxvt::term::_resource
1029} 1319}
1030 1320
1031=item $value = $term->x_resource ($pattern) 1321=item $value = $term->x_resource ($pattern)
1032 1322
1033Returns the X-Resource for the given pattern, excluding the program or 1323Returns the X-Resource for the given pattern, excluding the program or
… …
1116 1406
1117The methods currently supported on C<urxvt::overlay> objects are: 1407The methods currently supported on C<urxvt::overlay> objects are:
1118 1408
1119=over 4 1409=over 4
1120 1410
1121=item $overlay->set ($x, $y, $text, $rend) 1411=item $overlay->set ($x, $y, $text[, $rend])
1122 1412
1123Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts 1413Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts
1124text in rxvt-unicode's special encoding and an array of rendition values 1414text in rxvt-unicode's special encoding and an array of rendition values
1125at a specific position inside the overlay. 1415at a specific position inside the overlay.
1416
1417If C<$rend> is missing, then the rendition will not be changed.
1126 1418
1127=item $overlay->hide 1419=item $overlay->hide
1128 1420
1129If visible, hide the overlay, but do not destroy it. 1421If visible, hide the overlay, but do not destroy it.
1130 1422
… …
1200 1492
1201Normally its not a good idea to use this function, as programs might be 1493Normally its not a good idea to use this function, as programs might be
1202confused by changes in cursor position or scrolling. Its useful inside a 1494confused by changes in cursor position or scrolling. Its useful inside a
1203C<on_add_lines> hook, though. 1495C<on_add_lines> hook, though.
1204 1496
1497=item $term->scr_change_screen ($screen)
1498
1499Switch to given screen - 0 primary, 1 secondary.
1500
1205=item $term->cmd_parse ($octets) 1501=item $term->cmd_parse ($octets)
1206 1502
1207Similar to C<scr_add_lines>, but the argument must be in the 1503Similar to C<scr_add_lines>, but the argument must be in the
1208locale-specific encoding of the terminal and can contain command sequences 1504locale-specific encoding of the terminal and can contain command sequences
1209(escape codes) that will be interpreted. 1505(escape codes) that will be interpreted.
… …
1219Replaces the event mask of the pty watcher by the given event mask. Can 1515Replaces the event mask of the pty watcher by the given event mask. Can
1220be used to suppress input and output handling to the pty/tty. See the 1516be used to suppress input and output handling to the pty/tty. See the
1221description of C<< urxvt::timer->events >>. Make sure to always restore 1517description of C<< urxvt::timer->events >>. Make sure to always restore
1222the previous value. 1518the previous value.
1223 1519
1520=item $fd = $term->pty_fd
1521
1522Returns the master file descriptor for the pty in use, or C<-1> if no pty
1523is used.
1524
1224=item $windowid = $term->parent 1525=item $windowid = $term->parent
1225 1526
1226Return the window id of the toplevel window. 1527Return the window id of the toplevel window.
1227 1528
1228=item $windowid = $term->vt 1529=item $windowid = $term->vt
… …
1234Adds the specified events to the vt event mask. Useful e.g. when you want 1535Adds the specified events to the vt event mask. Useful e.g. when you want
1235to receive pointer events all the times: 1536to receive pointer events all the times:
1236 1537
1237 $term->vt_emask_add (urxvt::PointerMotionMask); 1538 $term->vt_emask_add (urxvt::PointerMotionMask);
1238 1539
1540=item $term->focus_in
1541
1542=item $term->focus_out
1543
1544=item $term->key_press ($state, $keycode[, $time])
1545
1546=item $term->key_release ($state, $keycode[, $time])
1547
1548Deliver various fake events to to terminal.
1549
1239=item $window_width = $term->width 1550=item $window_width = $term->width
1240 1551
1241=item $window_height = $term->height 1552=item $window_height = $term->height
1242 1553
1243=item $font_width = $term->fwidth 1554=item $font_width = $term->fwidth
… …
1273=item $env = $term->env 1584=item $env = $term->env
1274 1585
1275Returns a copy of the environment in effect for the terminal as a hashref 1586Returns a copy of the environment in effect for the terminal as a hashref
1276similar to C<\%ENV>. 1587similar to C<\%ENV>.
1277 1588
1589=item @envv = $term->envv
1590
1591Returns the environment as array of strings of the form C<VAR=VALUE>.
1592
1593=item @argv = $term->argv
1594
1595Return the argument vector as this terminal, similar to @ARGV, but
1596includes the program name as first element.
1597
1278=cut 1598=cut
1279 1599
1280sub env { 1600sub env {
1281 if (my $env = $_[0]->_env) {
1282 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env } 1601 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), $_[0]->envv }
1283 } else {
1284 +{ %ENV }
1285 }
1286} 1602}
1287 1603
1288=item $modifiermask = $term->ModLevel3Mask 1604=item $modifiermask = $term->ModLevel3Mask
1289 1605
1290=item $modifiermask = $term->ModMetaMask 1606=item $modifiermask = $term->ModMetaMask
1291 1607
1292=item $modifiermask = $term->ModNumLockMask 1608=item $modifiermask = $term->ModNumLockMask
1293 1609
1294Return the modifier masks corresponding to the "ISO Level 3 Shift" (often 1610Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
1295AltGr), the meta key (often Alt) and the num lock key, if applicable. 1611AltGr), the meta key (often Alt) and the num lock key, if applicable.
1612
1613=item $screen = $term->current_screen
1614
1615Returns the currently displayed screen (0 primary, 1 secondary).
1616
1617=item $cursor_is_hidden = $term->hidden_cursor
1618
1619Returns whether the cursor is currently hidden or not.
1296 1620
1297=item $view_start = $term->view_start ([$newvalue]) 1621=item $view_start = $term->view_start ([$newvalue])
1298 1622
1299Returns the row number of the topmost displayed line. Maximum value is 1623Returns the row number of the topmost displayed line. Maximum value is
1300C<0>, which displays the normal terminal contents. Lower values scroll 1624C<0>, which displays the normal terminal contents. Lower values scroll
… …
1308 1632
1309Used after changing terminal contents to display them. 1633Used after changing terminal contents to display them.
1310 1634
1311=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]]) 1635=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
1312 1636
1313Returns the text of the entire row with number C<$row_number>. Row C<0> 1637Returns the text of the entire row with number C<$row_number>. Row C<< $term->top_row >>
1314is the topmost terminal line, row C<< $term->$ncol-1 >> is the bottommost 1638is the topmost terminal line, row C<< $term->nrow-1 >> is the bottommost
1315terminal line. The scrollback buffer starts at line C<-1> and extends to
1316line C<< -$term->nsaved >>. Nothing will be returned if a nonexistent line 1639terminal line. Nothing will be returned if a nonexistent line
1317is requested. 1640is requested.
1318 1641
1319If C<$new_text> is specified, it will replace characters in the current 1642If C<$new_text> is specified, it will replace characters in the current
1320line, starting at column C<$start_col> (default C<0>), which is useful 1643line, starting at column C<$start_col> (default C<0>), which is useful
1321to replace only parts of a line. The font index in the rendition will 1644to replace only parts of a line. The font index in the rendition will
1322automatically be updated. 1645automatically be updated.
1323 1646
1324C<$text> is in a special encoding: tabs and wide characters that use more 1647C<$text> is in a special encoding: tabs and wide characters that use more
1325than one cell when displayed are padded with urxvt::NOCHAR characters 1648than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535)
1326(C<chr 65535>). Characters with combining characters and other characters 1649characters. Characters with combining characters and other characters that
1327that do not fit into the normal tetx encoding will be replaced with 1650do not fit into the normal text encoding will be replaced with characters
1328characters in the private use area. 1651in the private use area.
1329 1652
1330You have to obey this encoding when changing text. The advantage is 1653You have to obey this encoding when changing text. The advantage is
1331that C<substr> and similar functions work on screen cells and not on 1654that C<substr> and similar functions work on screen cells and not on
1332characters. 1655characters.
1333 1656
… …
1477where one character corresponds to one screen cell. See 1800where one character corresponds to one screen cell. See
1478C<< $term->ROW_t >> for details. 1801C<< $term->ROW_t >> for details.
1479 1802
1480=item $string = $term->special_decode $text 1803=item $string = $term->special_decode $text
1481 1804
1482Converts rxvt-unicodes text reprsentation into a perl string. See 1805Converts rxvt-unicodes text representation into a perl string. See
1483C<< $term->ROW_t >> for details. 1806C<< $term->ROW_t >> for details.
1484 1807
1485=item $success = $term->grab_button ($button, $modifiermask) 1808=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1486 1809
1810=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1811
1487Registers a synchronous button grab. See the XGrabButton manpage. 1812Register/unregister a synchronous button grab. See the XGrabButton
1813manpage.
1488 1814
1489=item $success = $term->grab ($eventtime[, $sync]) 1815=item $success = $term->grab ($eventtime[, $sync])
1490 1816
1491Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1817Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1492synchronous (C<$sync> is true). Also remembers the grab timestampe. 1818synchronous (C<$sync> is true). Also remembers the grab timestamp.
1493 1819
1494=item $term->allow_events_async 1820=item $term->allow_events_async
1495 1821
1496Calls XAllowEvents with AsyncBoth for the most recent grab. 1822Calls XAllowEvents with AsyncBoth for the most recent grab.
1497 1823
… …
1507=item $term->ungrab 1833=item $term->ungrab
1508 1834
1509Calls XUngrab for the most recent grab. Is called automatically on 1835Calls XUngrab for the most recent grab. Is called automatically on
1510evaluation errors, as it is better to lose the grab in the error case as 1836evaluation errors, as it is better to lose the grab in the error case as
1511the session. 1837the session.
1838
1839=item $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
1840
1841=item $atom_name = $term->XGetAtomName ($atom)
1842
1843=item @atoms = $term->XListProperties ($window)
1844
1845=item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
1846
1847=item $term->XChangeProperty ($window, $property, $type, $format, $octets)
1848
1849=item $term->XDeleteProperty ($window, $property)
1850
1851=item $window = $term->DefaultRootWindow
1852
1853=item $term->XReparentWindow ($window, $parent, [$x, $y])
1854
1855=item $term->XMapWindow ($window)
1856
1857=item $term->XUnmapWindow ($window)
1858
1859=item $term->XMoveResizeWindow ($window, $x, $y, $width, $height)
1860
1861=item ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x, $y)
1862
1863=item $term->XChangeInput ($window, $add_events[, $del_events])
1864
1865Various X or X-related functions. The C<$term> object only serves as
1866the source of the display, otherwise those functions map more-or-less
1867directory onto the X functions of the same name.
1512 1868
1513=back 1869=back
1514 1870
1515=cut 1871=cut
1516 1872
… …
1580 my ($self, $text, $cb) = @_; 1936 my ($self, $text, $cb) = @_;
1581 1937
1582 $self->add_item ({ type => "button", text => $text, activate => $cb}); 1938 $self->add_item ({ type => "button", text => $text, activate => $cb});
1583} 1939}
1584 1940
1585=item $popup->add_toggle ($text, $cb, $initial_value) 1941=item $popup->add_toggle ($text, $initial_value, $cb)
1586 1942
1587Adds a toggle/checkbox item to the popup. Teh callback gets called 1943Adds a toggle/checkbox item to the popup. The callback gets called
1588whenever it gets toggled, with a boolean indicating its value as its first 1944whenever it gets toggled, with a boolean indicating its new value as its
1589argument. 1945first argument.
1590 1946
1591=cut 1947=cut
1592 1948
1593sub add_toggle { 1949sub add_toggle {
1594 my ($self, $text, $cb, $value) = @_; 1950 my ($self, $text, $value, $cb) = @_;
1595 1951
1596 my $item; $item = { 1952 my $item; $item = {
1597 type => "button", 1953 type => "button",
1598 text => " $text", 1954 text => " $text",
1599 value => $value, 1955 value => $value,
… …
1618 my $env = $self->{term}->env; 1974 my $env = $self->{term}->env;
1619 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE. 1975 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
1620 delete $env->{LC_ALL}; 1976 delete $env->{LC_ALL};
1621 $env->{LC_CTYPE} = $self->{term}->locale; 1977 $env->{LC_CTYPE} = $self->{term}->locale;
1622 1978
1623 urxvt::term->new ($env, "popup", 1979 my $term = urxvt::term->new (
1980 $env, "popup",
1624 "--perl-lib" => "", "--perl-ext-common" => "", 1981 "--perl-lib" => "", "--perl-ext-common" => "",
1625 "-pty-fd" => -1, "-sl" => 0, 1982 "-pty-fd" => -1, "-sl" => 0,
1626 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect", 1983 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect",
1627 "--transient-for" => $self->{term}->parent, 1984 "--transient-for" => $self->{term}->parent,
1628 "-display" => $self->{term}->display_id, 1985 "-display" => $self->{term}->display_id,
1629 "-pe" => "urxvt-popup") 1986 "-pe" => "urxvt-popup",
1630 or die "unable to create popup window\n"; 1987 ) or die "unable to create popup window\n";
1988
1989 unless (delete $term->{urxvt_popup_init_done}) {
1990 $term->ungrab;
1991 $term->destroy;
1992 die "unable to initialise popup window\n";
1993 }
1631} 1994}
1632 1995
1633sub DESTROY { 1996sub DESTROY {
1634 my ($self) = @_; 1997 my ($self) = @_;
1635 1998
1636 delete $self->{term}{_destroy}{$self}; 1999 delete $self->{term}{_destroy}{$self};
1637 $self->{term}->ungrab; 2000 $self->{term}->ungrab;
1638} 2001}
1639 2002
1640=back 2003=back
2004
2005=cut
2006
2007package urxvt::watcher;
1641 2008
1642=head2 The C<urxvt::timer> Class 2009=head2 The C<urxvt::timer> Class
1643 2010
1644This class implements timer watchers/events. Time is represented as a 2011This class implements timer watchers/events. Time is represented as a
1645fractional number of seconds since the epoch. Example: 2012fractional number of seconds since the epoch. Example:
… …
1649 ->new 2016 ->new
1650 ->interval (1) 2017 ->interval (1)
1651 ->cb (sub { 2018 ->cb (sub {
1652 $term->{overlay}->set (0, 0, 2019 $term->{overlay}->set (0, 0,
1653 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]); 2020 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
1654 }); 2021 });
1655 2022
1656=over 4 2023=over 4
1657 2024
1658=item $timer = new urxvt::timer 2025=item $timer = new urxvt::timer
1659 2026
… …
1702 2069
1703 $term->{socket} = ... 2070 $term->{socket} = ...
1704 $term->{iow} = urxvt::iow 2071 $term->{iow} = urxvt::iow
1705 ->new 2072 ->new
1706 ->fd (fileno $term->{socket}) 2073 ->fd (fileno $term->{socket})
1707 ->events (urxvt::EVENT_READ) 2074 ->events (urxvt::EV_READ)
1708 ->start 2075 ->start
1709 ->cb (sub { 2076 ->cb (sub {
1710 my ($iow, $revents) = @_; 2077 my ($iow, $revents) = @_;
1711 # $revents must be 1 here, no need to check 2078 # $revents must be 1 here, no need to check
1712 sysread $term->{socket}, my $buf, 8192 2079 sysread $term->{socket}, my $buf, 8192
… …
1725Set the callback to be called when io events are triggered. C<$reventmask> 2092Set the callback to be called when io events are triggered. C<$reventmask>
1726is a bitset as described in the C<events> method. 2093is a bitset as described in the C<events> method.
1727 2094
1728=item $iow = $iow->fd ($fd) 2095=item $iow = $iow->fd ($fd)
1729 2096
1730Set the filedescriptor (not handle) to watch. 2097Set the file descriptor (not handle) to watch.
1731 2098
1732=item $iow = $iow->events ($eventmask) 2099=item $iow = $iow->events ($eventmask)
1733 2100
1734Set the event mask to watch. The only allowed values are 2101Set the event mask to watch. The only allowed values are
1735C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed 2102C<urxvt::EV_READ> and C<urxvt::EV_WRITE>, which might be ORed
1736together, or C<urxvt::EVENT_NONE>. 2103together, or C<urxvt::EV_NONE>.
1737 2104
1738=item $iow = $iow->start 2105=item $iow = $iow->start
1739 2106
1740Start watching for requested events on the given handle. 2107Start watching for requested events on the given handle.
1741 2108
1742=item $iow = $iow->stop 2109=item $iow = $iow->stop
1743 2110
1744Stop watching for events on the given filehandle. 2111Stop watching for events on the given file handle.
2112
2113=back
2114
2115=head2 The C<urxvt::iw> Class
2116
2117This class implements idle watchers, that get called automatically when
2118the process is idle. They should return as fast as possible, after doing
2119some useful work.
2120
2121=over 4
2122
2123=item $iw = new urxvt::iw
2124
2125Create a new idle watcher object in stopped state.
2126
2127=item $iw = $iw->cb (sub { my ($iw) = @_; ... })
2128
2129Set the callback to be called when the watcher triggers.
2130
2131=item $timer = $timer->start
2132
2133Start the watcher.
2134
2135=item $timer = $timer->stop
2136
2137Stop the watcher.
2138
2139=back
2140
2141=head2 The C<urxvt::pw> Class
2142
2143This class implements process watchers. They create an event whenever a
2144process exits, after which they stop automatically.
2145
2146 my $pid = fork;
2147 ...
2148 $term->{pw} = urxvt::pw
2149 ->new
2150 ->start ($pid)
2151 ->cb (sub {
2152 my ($pw, $exit_status) = @_;
2153 ...
2154 });
2155
2156=over 4
2157
2158=item $pw = new urxvt::pw
2159
2160Create a new process watcher in stopped state.
2161
2162=item $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
2163
2164Set the callback to be called when the timer triggers.
2165
2166=item $pw = $timer->start ($pid)
2167
2168Tells the watcher to start watching for process C<$pid>.
2169
2170=item $pw = $pw->stop
2171
2172Stop the watcher.
1745 2173
1746=back 2174=back
1747 2175
1748=head1 ENVIRONMENT 2176=head1 ENVIRONMENT
1749 2177
… …
1758 2186
1759=item >= 3 - script loading and management 2187=item >= 3 - script loading and management
1760 2188
1761=item >=10 - all called hooks 2189=item >=10 - all called hooks
1762 2190
1763=item >=11 - hook reutrn values 2191=item >=11 - hook return values
1764 2192
1765=back 2193=back
1766 2194
1767=head1 AUTHOR 2195=head1 AUTHOR
1768 2196
… …
1770 http://software.schmorp.de/pkg/rxvt-unicode 2198 http://software.schmorp.de/pkg/rxvt-unicode
1771 2199
1772=cut 2200=cut
1773 2201
17741 22021
2203
2204# vim: sw=3:

Diff Legend

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