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.115 by root, Fri Jan 20 15:57:21 2006 UTC vs.
Revision 1.208 by root, Tue Jun 5 22:23:07 2012 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.
165the message into vi commands to load the file. 223the message into vi commands to load the file.
166 224
167=item tabbed 225=item tabbed
168 226
169This transforms the terminal into a tabbar with additional terminals, that 227This transforms the terminal into a tabbar with additional terminals, that
170is, it implements what is commonly refered to as "tabbed terminal". The topmost line 228is, it implements what is commonly referred to as "tabbed terminal". The topmost line
171displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one 229displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one
172button per tab. 230button per tab.
173 231
174Clicking a button will activate that tab. Pressing Shift-Left and 232Clicking a button will activate that tab. Pressing B<Shift-Left> and
175Shift-Right will switch to the tab left or right of the current one. 233B<Shift-Right> will switch to the tab left or right of the current one,
234while B<Shift-Down> creates a new tab.
176 235
177=item mark-urls 236The tabbar itself can be configured similarly to a normal terminal, but
237with a resource class of C<URxvt.tabbed>. In addition, it supports the
238following four resources (shown with defaults):
178 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
179Uses per-line display filtering (C<on_line_update>) to underline urls and 250Uses per-line display filtering (C<on_line_update>) to underline text
180make them clickable. When middle-clicked, the program specified in the 251matching a certain pattern and make it clickable. When clicked with the
181resource C<urlLauncher> (default C<x-www-browser>) will be started with 252mouse button specified in the C<matcher.button> resource (default 2, or
182the 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.
183 258
184=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.
185 263
186This is basically a one-line extension that dynamically changes the background pixmap offset 264It is possible to activate the most recently seen match or a list of matches
187to the window position, in effect creating the same effect as pseudo transparency with 265from the keyboard. Simply bind a keysym to "perl:matcher:last" or
188a custom pixmap. No scaling is supported in this mode. Exmaple: 266"perl:matcher:list" as seen in the example below.
189 267
190 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background 268Example configuration:
269
270 URxvt.perl-ext: default,matcher
271 URxvt.urlLauncher: sensible-browser
272 URxvt.keysym.C-Delete: perl:matcher:last
273 URxvt.keysym.M-Delete: perl:matcher:list
274 URxvt.matcher.button: 1
275 URxvt.matcher.pattern.1: \\bwww\\.[\\w-]+\\.[\\w./?&@#-]*[\\w/-]
276 URxvt.matcher.pattern.2: \\B(/\\S+?):(\\d+)(?=:|$)
277 URxvt.matcher.launcher.2: gvim +$2 $1
278
279=item xim-onthespot
280
281This (experimental) perl extension implements OnTheSpot editing. It does
282not work perfectly, and some input methods don't seem to work well with
283OnTheSpot editing in general, but it seems to work at least for SCIM and
284kinput2.
285
286You enable it by specifying this extension and a preedit style of
287C<OnTheSpot>, i.e.:
288
289 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot
290
291=item kuake<hotkey>
292
293A very primitive quake-console-like extension. It was inspired by a
294description of how the programs C<kuake> and C<yakuake> work: Whenever the
295user presses a global accelerator key (by default C<F10>), the terminal
296will show or hide itself. Another press of the accelerator key will hide
297or show it again.
298
299Initially, the window will not be shown when using this extension.
300
301This is useful if you need a single terminal that is not using any desktop
302space most of the time but is quickly available at the press of a key.
303
304The accelerator key is grabbed regardless of any modifiers, so this
305extension will actually grab a physical key just for this function.
306
307If you want a quake-like animation, tell your window manager to do so
308(fvwm can do it).
309
310=item overlay-osc
311
312This extension implements some OSC commands to display timed popups on the
313screen - useful for status displays from within scripts. You have to read
314the sources for more info.
191 315
192=item block-graphics-to-ascii 316=item block-graphics-to-ascii
193 317
194A not very useful example of filtering all text output to the terminal, 318A not very useful example of filtering all text output to the terminal
195by replacing all line-drawing characters (U+2500 .. U+259F) by a 319by replacing all line-drawing characters (U+2500 .. U+259F) by a
196similar-looking ascii character. 320similar-looking ascii character.
197 321
198=item digital-clock 322=item digital-clock
199 323
200Displays a digital clock using the built-in overlay. 324Displays a digital clock using the built-in overlay.
325
326=item remote-clipboard
327
328Somewhat of a misnomer, this extension adds two menu entries to the
329selection popup that allows one to run external commands to store the
330selection somewhere and fetch it again.
331
332We use it to implement a "distributed selection mechanism", which just
333means that one command uploads the file to a remote server, and another
334reads it.
335
336The commands can be set using the C<URxvt.remote-selection.store> and
337C<URxvt.remote-selection.fetch> resources. The first should read the
338selection to store from STDIN (always in UTF-8), the second should provide
339the selection data on STDOUT (also in UTF-8).
340
341The defaults (which are likely useless to you) use rsh and cat:
342
343 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
344 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
345
346=item selection-pastebin
347
348This is a little rarely useful extension that uploads the selection as
349textfile to a remote site (or does other things). (The implementation is
350not currently secure for use in a multiuser environment as it writes to
351F</tmp> directly.).
352
353It listens to the C<selection-pastebin:remote-pastebin> keyboard command,
354i.e.
355
356 URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin
357
358Pressing this combination runs a command with C<%> replaced by the name of
359the textfile. This command can be set via a resource:
360
361 URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
362
363And the default is likely not useful to anybody but the few people around
364here :)
365
366The name of the textfile is the hex encoded md5 sum of the selection, so
367the same content should lead to the same filename.
368
369After a successful upload the selection will be replaced by the text given
370in the C<selection-pastebin-url> resource (again, the % is the placeholder
371for the filename):
372
373 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
374
375I<Note to xrdb users:> xrdb uses the C preprocessor, which might interpret
376the double C</> characters as comment start. Use C<\057\057> instead,
377which works regardless of whether xrdb is used to parse the resource file
378or not.
379
380=item macosx-clipboard and macosx-clipboard-native
381
382These two modules implement an extended clipboard for Mac OS X. They are
383used like this:
384
385 URxvt.perl-ext-common: default,macosx-clipboard
386 URxvt.keysym.M-c: perl:macosx-clipboard:copy
387 URxvt.keysym.M-v: perl:macosx-clipboard:paste
388
389The difference between them is that the native variant requires a
390perl from apple's devkit or so, and C<macosx-clipboard> requires the
391C<Mac::Pasteboard> module, works with other perls, has fewer bugs, is
392simpler etc. etc.
201 393
202=item example-refresh-hooks 394=item example-refresh-hooks
203 395
204Displays a very simple digital clock in the upper right corner of the 396Displays a very simple digital clock in the upper right corner of the
205window. Illustrates overwriting the refresh callbacks to create your own 397window. Illustrates overwriting the refresh callbacks to create your own
206overlays or changes. 398overlays or changes.
207 399
208=item selection-pastebin 400=item confirm-paste
209 401
210This is a little rarely useful extension that Uploads the selection as 402Displays a confirmation dialog when a paste containing at least a full
211textfile to a remote site (or does other things). (The implementation is 403line is detected.
212not currently secure for use in a multiuser environment as it writes to
213F</tmp> directly.).
214 404
215It listens to the C<selection-pastebin:remote-pastebin> keyboard command, 405=item bell-command
216i.e.
217 406
218 URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin 407Runs the command specified by the C<URxvt.bell-command> resource when
408a bell event occurs. For example, the following pops up a notification
409bubble with the text "Beep, Beep" using notify-send:
219 410
220Pressing this combination runs a command with C<%> replaced by the name of 411 URxvt.bell-command: notify-send "Beep, Beep"
221the textfile. This command can be set via a resource:
222
223 URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
224
225And the default is likely not useful to anybody but the few people around
226here :)
227
228The name of the textfile is the hex encoded md5 sum of the selection, so
229the same content should lead to the same filename.
230
231After a successful upload the selection will be replaced by the text given
232in the C<selection-pastebin-url> resource (again, the % is the placeholder
233for the filename):
234
235 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
236 412
237=back 413=back
238 414
239=head1 API DOCUMENTATION 415=head1 API DOCUMENTATION
240 416
256 432
257=over 4 433=over 4
258 434
259=item $text 435=item $text
260 436
261Rxvt-unicodes special way of encoding text, where one "unicode" character 437Rxvt-unicode's special way of encoding text, where one "unicode" character
262always represents one screen cell. See L<ROW_t> for a discussion of this format. 438always represents one screen cell. See L<ROW_t> for a discussion of this format.
263 439
264=item $string 440=item $string
265 441
266A perl text string, with an emphasis on I<text>. It can store all unicode 442A perl text string, with an emphasis on I<text>. It can store all unicode
270=item $octets 446=item $octets
271 447
272Either binary data or - more common - a text string encoded in a 448Either binary data or - more common - a text string encoded in a
273locale-specific way. 449locale-specific way.
274 450
451=item $keysym
452
453an integer that is a valid X11 keysym code. You can convert a string
454into a keysym and viceversa by using C<XStringToKeysym> and
455C<XKeysymToString>.
456
275=back 457=back
276 458
277=head2 Extension Objects 459=head2 Extension Objects
278 460
279Very perl extension is a perl class. A separate perl object is created 461Every perl extension is a perl class. A separate perl object is created
280for each terminal and each extension and passed as the first parameter to 462for each terminal, and each terminal has its own set of extension objects,
281hooks. So extensions can use their C<$self> object without having to think 463which are passed as the first parameter to hooks. So extensions can use
282about other extensions, with the exception of methods and members that 464their C<$self> object without having to think about clashes with other
465extensions or other terminals, with the exception of methods and members
283begin with an underscore character C<_>: these are reserved for internal 466that begin with an underscore character C<_>: these are reserved for
284use. 467internal use.
285 468
286Although it isn't a C<urxvt::term> object, you can call all methods of the 469Although it isn't a C<urxvt::term> object, you can call all methods of the
287C<urxvt::term> class on this object. 470C<urxvt::term> class on this object.
288 471
289It has the following methods and data members: 472It has the following methods and data members:
310=head2 Hooks 493=head2 Hooks
311 494
312The following subroutines can be declared in extension files, and will be 495The following subroutines can be declared in extension files, and will be
313called whenever the relevant event happens. 496called whenever the relevant event happens.
314 497
315The first argument passed to them is an extension oject as described in 498The first argument passed to them is an extension object as described in
316the in the C<Extension Objects> section. 499the in the C<Extension Objects> section.
317 500
318B<All> of these hooks must return a boolean value. If any of the called 501B<All> of these hooks must return a boolean value. If any of the called
319hooks returns true, then the event counts as being I<consumed>, and the 502hooks returns true, then the event counts as being I<consumed>, and the
320relevant action might not be carried out by the C++ code. 503relevant action might not be carried out by the C++ code.
333place. 516place.
334 517
335=item on_start $term 518=item on_start $term
336 519
337Called at the very end of initialisation of a new terminal, just before 520Called at the very end of initialisation of a new terminal, just before
338trying to map (display) the toplevel and returning to the mainloop. 521trying to map (display) the toplevel and returning to the main loop.
339 522
340=item on_destroy $term 523=item on_destroy $term
341 524
342Called whenever something tries to destroy terminal, before doing anything 525Called whenever something tries to destroy terminal, when the terminal is
343yet. If this hook returns true, then destruction is skipped, but this is 526still fully functional (not for long, though).
344rarely a good idea.
345 527
346=item on_reset $term 528=item on_reset $term
347 529
348Called after the screen is "reset" for any reason, such as resizing or 530Called after the screen is "reset" for any reason, such as resizing or
349control sequences. Here is where you can react on changes to size-related 531control sequences. Here is where you can react on changes to size-related
371 553
372Called whenever a selection has been copied, but before the selection is 554Called whenever a selection has been copied, but before the selection is
373requested from the server. The selection text can be queried and changed 555requested from the server. The selection text can be queried and changed
374by calling C<< $term->selection >>. 556by calling C<< $term->selection >>.
375 557
376Returning a true value aborts selection grabbing. It will still be hilighted. 558Returning a true value aborts selection grabbing. It will still be highlighted.
377 559
378=item on_sel_extend $term 560=item on_sel_extend $term
379 561
380Called whenever the user tries to extend the selection (e.g. with a double 562Called whenever the user tries to extend the selection (e.g. with a double
381click) and is either supposed to return false (normal operation), or 563click) and is either supposed to return false (normal operation), or
382should extend the selection itelf and return true to suppress the built-in 564should extend the selection itself and return true to suppress the built-in
383processing. This can happen multiple times, as long as the callback 565processing. This can happen multiple times, as long as the callback
384returns true, it will be called on every further click by the user and is 566returns true, it will be called on every further click by the user and is
385supposed to enlarge the selection more and more, if possible. 567supposed to enlarge the selection more and more, if possible.
386 568
387See the F<selection> example extension. 569See the F<selection> example extension.
388 570
389=item on_view_change $term, $offset 571=item on_view_change $term, $offset
390 572
391Called whenever the view offset changes, i..e the user or program 573Called whenever the view offset changes, i.e. the user or program
392scrolls. Offset C<0> means display the normal terminal, positive values 574scrolls. Offset C<0> means display the normal terminal, positive values
393show this many lines of scrollback. 575show this many lines of scrollback.
394 576
395=item on_scroll_back $term, $lines, $saved 577=item on_scroll_back $term, $lines, $saved
396 578
400 582
401It is called before lines are scrolled out (so rows 0 .. min ($lines - 1, 583It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
402$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total 584$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
403number of lines that will be in the scrollback buffer. 585number of lines that will be in the scrollback buffer.
404 586
405=item on_osc_seq $term, $string 587=item on_osc_seq $term, $op, $args, $resp
588
589Called on every OSC sequence and can be used to suppress it or modify its
590behaviour. The default should be to return an empty list. A true value
591suppresses execution of the request completely. Make sure you don't get
592confused by recursive invocations when you output an OSC sequence within
593this callback.
594
595C<on_osc_seq_perl> should be used for new behaviour.
596
597=item on_osc_seq_perl $term, $args, $resp
406 598
407Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 599Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
408operating system command) is processed. Cursor position and other state 600operating system command) is processed. Cursor position and other state
409information is up-to-date when this happens. For interoperability, the 601information is up-to-date when this happens. For interoperability, the
410string should start with the extension name and a colon, to distinguish 602string should start with the extension name (sans -osc) and a semicolon,
411it from commands for other extensions, and this might be enforced in the 603to distinguish it from commands for other extensions, and this might be
412future. 604enforced in the future.
605
606For example, C<overlay-osc> uses this:
607
608 sub on_osc_seq_perl {
609 my ($self, $osc, $resp) = @_;
610
611 return unless $osc =~ s/^overlay;//;
612
613 ... process remaining $osc string
614 }
413 615
414Be careful not ever to trust (in a security sense) the data you receive, 616Be careful not ever to trust (in a security sense) the data you receive,
415as its source can not easily be controleld (e-mail content, messages from 617as its source can not easily be controlled (e-mail content, messages from
416other users on the same system etc.). 618other users on the same system etc.).
619
620For responses, C<$resp> contains the end-of-args separator used by the
621sender.
417 622
418=item on_add_lines $term, $string 623=item on_add_lines $term, $string
419 624
420Called whenever text is about to be output, with the text as argument. You 625Called whenever text is about to be output, with the text as argument. You
421can filter/change and output the text yourself by returning a true value 626can filter/change and output the text yourself by returning a true value
426=item on_tt_write $term, $octets 631=item on_tt_write $term, $octets
427 632
428Called whenever some data is written to the tty/pty and can be used to 633Called whenever some data is written to the tty/pty and can be used to
429suppress or filter tty input. 634suppress or filter tty input.
430 635
636=item on_tt_paste $term, $octets
637
638Called whenever text is about to be pasted, with the text as argument. You
639can filter/change and paste the text yourself by returning a true value
640and calling C<< $term->tt_paste >> yourself. C<$octets> is
641locale-encoded.
642
431=item on_line_update $term, $row 643=item on_line_update $term, $row
432 644
433Called whenever a line was updated or changed. Can be used to filter 645Called whenever a line was updated or changed. Can be used to filter
434screen output (e.g. underline urls or other useless stuff). Only lines 646screen output (e.g. underline urls or other useless stuff). Only lines
435that are being shown will be filtered, and, due to performance reasons, 647that are being shown will be filtered, and, due to performance reasons,
442later with the already-modified line (e.g. if unrelated parts change), so 654later with the already-modified line (e.g. if unrelated parts change), so
443you cannot just toggle rendition bits, but only set them. 655you cannot just toggle rendition bits, but only set them.
444 656
445=item on_refresh_begin $term 657=item on_refresh_begin $term
446 658
447Called just before the screen gets redrawn. Can be used for overlay 659Called just before the screen gets redrawn. Can be used for overlay or
448or similar effects by modify terminal contents in refresh_begin, and 660similar effects by modifying the terminal contents in refresh_begin, and
449restoring them in refresh_end. The built-in overlay and selection display 661restoring them in refresh_end. The built-in overlay and selection display
450code is run after this hook, and takes precedence. 662code is run after this hook, and takes precedence.
451 663
452=item on_refresh_end $term 664=item on_refresh_end $term
453 665
454Called just after the screen gets redrawn. See C<on_refresh_begin>. 666Called just after the screen gets redrawn. See C<on_refresh_begin>.
455 667
456=item on_keyboard_command $term, $string 668=item on_user_command $term, $string
457 669
458Called whenever the user presses a key combination that has a 670Called whenever a user-configured event is being activated (e.g. via
459C<perl:string> action bound to it (see description of the B<keysym> 671a C<perl:string> action bound to a key, see description of the B<keysym>
460resource in the @@RXVT_NAME@@(1) manpage). 672resource in the @@RXVT_NAME@@(1) manpage).
673
674The event is simply the action string. This interface is assumed to change
675slightly in the future.
676
677=item on_register_command $term, $keysym, $modifiermask, $string
678
679Called after parsing a keysym resource but before registering the
680associated binding. If this hook returns TRUE the binding is not
681registered. It can be used to modify a binding by calling
682C<register_command>.
683
684=item on_resize_all_windows $term, $new_width, $new_height
685
686Called just after the new window size has been calculated, but before
687windows are actually being resized or hints are being set. If this hook
688returns TRUE, setting of the window hints is being skipped.
461 689
462=item on_x_event $term, $event 690=item on_x_event $term, $event
463 691
464Called on every X event received on the vt window (and possibly other 692Called on every X event received on the vt window (and possibly other
465windows). Should only be used as a last resort. Most event structure 693windows). Should only be used as a last resort. Most event structure
466members are not passed. 694members are not passed.
467 695
696=item on_root_event $term, $event
697
698Like C<on_x_event>, but is called for events on the root window.
699
468=item on_focus_in $term 700=item on_focus_in $term
469 701
470Called whenever the window gets the keyboard focus, before rxvt-unicode 702Called whenever the window gets the keyboard focus, before rxvt-unicode
471does focus in processing. 703does focus in processing.
472 704
473=item on_focus_out $term 705=item on_focus_out $term
474 706
475Called wheneever the window loses keyboard focus, before rxvt-unicode does 707Called whenever the window loses keyboard focus, before rxvt-unicode does
476focus out processing. 708focus out processing.
477 709
478=item on_configure_notify $term, $event 710=item on_configure_notify $term, $event
479 711
712=item on_property_notify $term, $event
713
480=item on_key_press $term, $event, $keysym, $octets 714=item on_key_press $term, $event, $keysym, $octets
481 715
482=item on_key_release $term, $event, $keysym 716=item on_key_release $term, $event, $keysym
483 717
484=item on_button_press $term, $event 718=item on_button_press $term, $event
489 723
490=item on_map_notify $term, $event 724=item on_map_notify $term, $event
491 725
492=item on_unmap_notify $term, $event 726=item on_unmap_notify $term, $event
493 727
494Called whenever the corresponding X event is received for the terminal If 728Called whenever the corresponding X event is received for the terminal. If
495the hook returns true, then the even will be ignored by rxvt-unicode. 729the hook returns true, then the event will be ignored by rxvt-unicode.
496 730
497The event is a hash with most values as named by Xlib (see the XEvent 731The event is a hash with most values as named by Xlib (see the XEvent
498manpage), with the additional members C<row> and C<col>, which are the row 732manpage), with the additional members C<row> and C<col>, which are the
499and column under the mouse cursor. 733(real, not screen-based) row and column under the mouse cursor.
500 734
501C<on_key_press> additionally receives the string rxvt-unicode would 735C<on_key_press> additionally receives the string rxvt-unicode would
502output, if any, in locale-specific encoding. 736output, if any, in locale-specific encoding.
503 737
504subwindow. 738subwindow.
509 743
510=item on_wm_delete_window $term, $event 744=item on_wm_delete_window $term, $event
511 745
512Called when various types of ClientMessage events are received (all with 746Called when various types of ClientMessage events are received (all with
513format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW). 747format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
748
749=item on_bell $term
750
751Called on receipt of a bell character.
514 752
515=back 753=back
516 754
517=cut 755=cut
518 756
535our $LIBDIR; 773our $LIBDIR;
536our $RESNAME; 774our $RESNAME;
537our $RESCLASS; 775our $RESCLASS;
538our $RXVTNAME; 776our $RXVTNAME;
539 777
778our $NOCHAR = chr 0xffff;
779
540=head2 Variables in the C<urxvt> Package 780=head2 Variables in the C<urxvt> Package
541 781
542=over 4 782=over 4
543 783
544=item $urxvt::LIBDIR 784=item $urxvt::LIBDIR
559The current terminal. This variable stores the current C<urxvt::term> 799The current terminal. This variable stores the current C<urxvt::term>
560object, whenever a callback/hook is executing. 800object, whenever a callback/hook is executing.
561 801
562=item @urxvt::TERM_INIT 802=item @urxvt::TERM_INIT
563 803
564All coderefs in this array will be called as methods of the next newly 804All code references in this array will be called as methods of the next newly
565created C<urxvt::term> object (during the C<on_init> phase). The array 805created C<urxvt::term> object (during the C<on_init> phase). The array
566gets cleared before the codereferences that were in it are being executed, 806gets cleared before the code references that were in it are being executed,
567so coderefs can push themselves onto it again if they so desire. 807so references can push themselves onto it again if they so desire.
568 808
569This complements to the perl-eval commandline option, but gets executed 809This complements to the perl-eval command line option, but gets executed
570first. 810first.
571 811
572=item @urxvt::TERM_EXT 812=item @urxvt::TERM_EXT
573 813
574Works similar to C<@TERM_INIT>, but contains perl package/class names, which 814Works similar to C<@TERM_INIT>, but contains perl package/class names, which
581 821
582=over 4 822=over 4
583 823
584=item urxvt::fatal $errormessage 824=item urxvt::fatal $errormessage
585 825
586Fatally aborts execution with the given error message. Avoid at all 826Fatally aborts execution with the given error message (which should
587costs! The only time this is acceptable is when the terminal process 827include a trailing newline). Avoid at all costs! The only time this
588starts up. 828is acceptable (and useful) is in the init hook, where it prevents the
829terminal from starting up.
589 830
590=item urxvt::warn $string 831=item urxvt::warn $string
591 832
592Calls C<rxvt_warn> with the given string which should not include a 833Calls C<rxvt_warn> with the given string which should include a trailing
593newline. The module also overwrites the C<warn> builtin with a function 834newline. The module also overwrites the C<warn> builtin with a function
594that calls this function. 835that calls this function.
595 836
596Using this function has the advantage that its output ends up in the 837Using this function has the advantage that its output ends up in the
597correct place, e.g. on stderr of the connecting urxvtc client. 838correct place, e.g. on stderr of the connecting urxvtc client.
598 839
599Messages have a size limit of 1023 bytes currently. 840Messages have a size limit of 1023 bytes currently.
841
842=item @terms = urxvt::termlist
843
844Returns all urxvt::term objects that exist in this process, regardless of
845whether they are started, being destroyed etc., so be careful. Only term
846objects that have perl extensions attached will be returned (because there
847is no urxvt::term object associated with others).
600 848
601=item $time = urxvt::NOW 849=item $time = urxvt::NOW
602 850
603Returns the "current time" (as per the event loop). 851Returns the "current time" (as per the event loop).
604 852
647 895
648=item $rend = urxvt::OVERLAY_RSTYLE 896=item $rend = urxvt::OVERLAY_RSTYLE
649 897
650Return the rendition mask used for overlays by default. 898Return the rendition mask used for overlays by default.
651 899
652=item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline 900=item $rendbit = urxvt::RS_Bold, urxvt::RS_Italic, urxvt::RS_Blink,
901urxvt::RS_RVid, urxvt::RS_Uline
653 902
654Return the bit that enabled bold, italic, blink, reverse-video and 903Return the bit that enabled bold, italic, blink, reverse-video and
655underline, respectively. To enable such a style, just logically OR it into 904underline, respectively. To enable such a style, just logically OR it into
656the bitset. 905the bitset.
657 906
662Return the foreground/background colour index, respectively. 911Return the foreground/background colour index, respectively.
663 912
664=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour 913=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
665 914
666=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour 915=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
916
917=item $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
667 918
668Replace the foreground/background colour in the rendition mask with the 919Replace the foreground/background colour in the rendition mask with the
669specified one. 920specified one.
670 921
671=item $value = urxvt::GET_CUSTOM $rend 922=item $value = urxvt::GET_CUSTOM $rend
690 unless $msg =~ /\n$/; 941 unless $msg =~ /\n$/;
691 urxvt::warn ($msg); 942 urxvt::warn ($msg);
692 }; 943 };
693} 944}
694 945
946no warnings 'utf8';
947
948sub resource {
949 my ($term, $name, $isarg, $flag, $value) = @_;
950
951 $term->scan_meta;
952
953 warn "resourece<@_>\n";#d#
954
955 0
956}
957
958sub usage {
959 my ($term, $usage_type) = @_;
960
961 $term->scan_meta;
962
963 my $r = $term->{meta}{resource};
964
965 for my $regex (sort keys %$r) {
966 my ($ext, $type, $desc) = @{ $r->{$regex} };
967
968 $desc .= " (-pe $ext)";
969
970 if ($usage_type == 1) {
971 if ($type eq "boolean") {
972 urxvt::log sprintf " -%-20.20s %s\n", "/+$regex", $desc;
973 } else {
974 urxvt::log sprintf " -%-20.20s %s\n", "$regex $type", $desc;
975 }
976 } else {
977 urxvt::log sprintf " %-19.19s %s\n", "$regex:", $type;
978 }
979 }
980}
981
695my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 982my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
696 983
697sub verbose { 984sub verbose {
698 my ($level, $msg) = @_; 985 my ($level, $msg) = @_;
699 warn "$msg\n" if $level <= $verbosity; 986 warn "$msg\n" if $level <= $verbosity;
715 1002
716 open my $fh, "<:raw", $path 1003 open my $fh, "<:raw", $path
717 or die "$path: $!"; 1004 or die "$path: $!";
718 1005
719 my $source = 1006 my $source =
720 "package $pkg; use strict; use utf8;\n" 1007 "package $pkg; use strict; use utf8; no warnings 'utf8';\n"
721 . "#line 1 \"$path\"\n{\n" 1008 . "#line 1 \"$path\"\n{\n"
722 . (do { local $/; <$fh> }) 1009 . (do { local $/; <$fh> })
723 . "\n};\n1"; 1010 . "\n};\n1";
724 1011
725 eval $source 1012 eval $source
735sub invoke { 1022sub invoke {
736 local $TERM = shift; 1023 local $TERM = shift;
737 my $htype = shift; 1024 my $htype = shift;
738 1025
739 if ($htype == 0) { # INIT 1026 if ($htype == 0) { # INIT
740 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 1027 my @dirs = $TERM->perl_libdirs;
741 1028
742 my %ext_arg; 1029 my %ext_arg;
743 1030
744 { 1031 {
745 my @init = @TERM_INIT; 1032 my @init = @TERM_INIT;
746 @TERM_INIT = (); 1033 @TERM_INIT = ();
750 $TERM->register_package ($_) for @pkg; 1037 $TERM->register_package ($_) for @pkg;
751 } 1038 }
752 1039
753 for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) { 1040 for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
754 if ($_ eq "default") { 1041 if ($_ eq "default") {
755 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback); 1042 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback readline);
756 } elsif (/^-(.*)$/) { 1043 } elsif (/^-(.*)$/) {
757 delete $ext_arg{$1}; 1044 delete $ext_arg{$1};
758 } elsif (/^([^<]+)<(.*)>$/) { 1045 } elsif (/^([^<]+)<(.*)>$/) {
759 push @{ $ext_arg{$1} }, $2; 1046 push @{ $ext_arg{$1} }, $2;
760 } else { 1047 } else {
761 $ext_arg{$_} ||= []; 1048 $ext_arg{$_} ||= [];
762 } 1049 }
763 } 1050 }
764 1051
765 while (my ($ext, $argv) = each %ext_arg) { 1052 for my $ext (sort keys %ext_arg) {
766 my @files = grep -f $_, map "$_/$ext", @dirs; 1053 my @files = grep -f $_, map "$_/$ext", @dirs;
767 1054
768 if (@files) { 1055 if (@files) {
769 $TERM->register_package (extension_package $files[0], $argv); 1056 $TERM->register_package (extension_package $files[0], $ext_arg{$ext});
770 } else { 1057 } else {
771 warn "perl extension '$ext' not found in perl library search path\n"; 1058 warn "perl extension '$ext' not found in perl library search path\n";
772 } 1059 }
773 } 1060 }
774 1061
780 1067
781 if (my $cb = $TERM->{_hook}[$htype]) { 1068 if (my $cb = $TERM->{_hook}[$htype]) {
782 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")" 1069 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
783 if $verbosity >= 10; 1070 if $verbosity >= 10;
784 1071
785 keys %$cb; 1072 for my $pkg (keys %$cb) {
786
787 while (my ($pkg, $cb) = each %$cb) {
788 my $retval_ = eval { $cb->($TERM->{_pkg}{$pkg}, @_) }; 1073 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg}, @_) };
789 $retval ||= $retval_; 1074 $retval ||= $retval_;
790 1075
791 if ($@) { 1076 if ($@) {
792 $TERM->ungrab; # better to lose the grab than the session 1077 $TERM->ungrab; # better to lose the grab than the session
793 warn $@; 1078 warn $@;
805 # clear package 1090 # clear package
806 %$TERM = (); 1091 %$TERM = ();
807 } 1092 }
808 1093
809 $retval 1094 $retval
1095}
1096
1097sub SET_COLOR($$$) {
1098 SET_BGCOLOR (SET_FGCOLOR ($_[0], $_[1]), $_[2])
1099}
1100
1101sub rend2mask {
1102 no strict 'refs';
1103 my ($str, $mask) = (@_, 0);
1104 my %color = ( fg => undef, bg => undef );
1105 my @failed;
1106 for my $spec ( split /\s+/, $str ) {
1107 if ( $spec =~ /^([fb]g)[_:-]?(\d+)/i ) {
1108 $color{lc($1)} = $2;
1109 } else {
1110 my $neg = $spec =~ s/^[-^]//;
1111 unless ( exists &{"RS_$spec"} ) {
1112 push @failed, $spec;
1113 next;
1114 }
1115 my $cur = &{"RS_$spec"};
1116 if ( $neg ) {
1117 $mask &= ~$cur;
1118 } else {
1119 $mask |= $cur;
1120 }
1121 }
1122 }
1123 ($mask, @color{qw(fg bg)}, \@failed)
810} 1124}
811 1125
812# urxvt::term::extension 1126# urxvt::term::extension
813 1127
814package urxvt::term::extension; 1128package urxvt::term::extension;
885is that you cannot use blocking APIs, but the non-blocking variant should 1199is that you cannot use blocking APIs, but the non-blocking variant should
886work. 1200work.
887 1201
888=cut 1202=cut
889 1203
890our $VERSION = 1; 1204our $VERSION = '5.23';
891 1205
892$INC{"urxvt/anyevent.pm"} = 1; # mark us as there 1206$INC{"urxvt/anyevent.pm"} = 1; # mark us as there
893push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::]; 1207push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
894 1208
895sub timer { 1209sub timer {
897 1211
898 my $cb = $arg{cb}; 1212 my $cb = $arg{cb};
899 1213
900 urxvt::timer 1214 urxvt::timer
901 ->new 1215 ->new
902 ->start (urxvt::NOW + $arg{after}) 1216 ->after ($arg{after}, $arg{interval})
903 ->cb (sub { 1217 ->cb ($arg{interval} ? $cb : sub {
904 $_[0]->stop; # need to cancel manually 1218 $_[0]->stop; # need to cancel manually
905 $cb->(); 1219 $cb->();
906 }) 1220 })
907} 1221}
908 1222
909sub io { 1223sub io {
910 my ($class, %arg) = @_; 1224 my ($class, %arg) = @_;
911 1225
912 my $cb = $arg{cb}; 1226 my $cb = $arg{cb};
1227 my $fd = fileno $arg{fh};
1228 defined $fd or $fd = $arg{fh};
913 1229
914 bless [$arg{fh}, urxvt::iow 1230 bless [$arg{fh}, urxvt::iow
915 ->new 1231 ->new
916 ->fd (fileno $arg{fh}) 1232 ->fd ($fd)
917 ->events (($arg{poll} =~ /r/ ? 1 : 0) 1233 ->events (($arg{poll} =~ /r/ ? 1 : 0)
918 | ($arg{poll} =~ /w/ ? 2 : 0)) 1234 | ($arg{poll} =~ /w/ ? 2 : 0))
919 ->start 1235 ->start
920 ->cb (sub { 1236 ->cb ($cb)
921 $cb->(($_[1] & 1 ? 'r' : '')
922 . ($_[1] & 2 ? 'w' : ''));
923 })],
924 urxvt::anyevent:: 1237 ], urxvt::anyevent::
1238}
1239
1240sub idle {
1241 my ($class, %arg) = @_;
1242
1243 my $cb = $arg{cb};
1244
1245 urxvt::iw
1246 ->new
1247 ->start
1248 ->cb ($cb)
1249}
1250
1251sub child {
1252 my ($class, %arg) = @_;
1253
1254 my $cb = $arg{cb};
1255
1256 urxvt::pw
1257 ->new
1258 ->start ($arg{pid})
1259 ->cb (sub {
1260 $_[0]->stop; # need to cancel manually
1261 $cb->($_[0]->rpid, $_[0]->rstatus);
1262 })
925} 1263}
926 1264
927sub DESTROY { 1265sub DESTROY {
928 $_[0][1]->stop; 1266 $_[0][1]->stop;
929} 1267}
930 1268
931sub condvar { 1269# only needed for AnyEvent < 6 compatibility
932 bless \my $flag, urxvt::anyevent::condvar:: 1270sub one_event {
933}
934
935sub urxvt::anyevent::condvar::broadcast {
936 ${$_[0]}++;
937}
938
939sub urxvt::anyevent::condvar::wait {
940 unless (${$_[0]}) {
941 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API"; 1271 Carp::croak "AnyEvent->one_event blocking wait unsupported in urxvt, use a non-blocking API";
942 }
943} 1272}
944 1273
945package urxvt::term; 1274package urxvt::term;
946 1275
947=head2 The C<urxvt::term> Class 1276=head2 The C<urxvt::term> Class
974 $proxy->enable ($name => $ref); 1303 $proxy->enable ($name => $ref);
975 } 1304 }
976 } 1305 }
977} 1306}
978 1307
1308sub perl_libdirs {
1309 map { split /:/ }
1310 $_[0]->resource ("perl_lib"),
1311 $ENV{URXVT_PERL_LIB},
1312 "$ENV{HOME}/.urxvt/ext",
1313 "$LIBDIR/perl"
1314}
1315
1316sub scan_meta {
1317 my ($self) = @_;
1318 my @libdirs = perl_libdirs $self;
1319
1320 return if $self->{meta_libdirs} eq join "\x00", @libdirs;
1321
1322 my %meta;
1323
1324 $self->{meta_libdirs} = join "\x00", @libdirs;
1325 $self->{meta} = \%meta;
1326
1327 for my $dir (reverse @libdirs) {
1328 opendir my $fh, $dir
1329 or next;
1330 for my $ext (readdir $fh) {
1331 $ext ne "."
1332 and $ext ne ".."
1333 and open my $fh, "<", "$dir/$ext"
1334 or next;
1335
1336 while (<$fh>) {
1337 if (/^#:META:RESOURCE:(.*)/) {
1338 my ($regex, $type, $desc) = split /:/, $1;
1339 $regex =~ s/\$\$/$ext/g; # $$ in regex == extension name
1340 $meta{resource}{$regex} = [$ext, $type, $desc];
1341 } elsif (/^\s*(?:#|$)/) {
1342 # skip other comments and empty lines
1343 } else {
1344 last; # stop parsing on first non-empty non-comment line
1345 }
1346 }
1347 }
1348 }
1349}
1350
979=item $term = new urxvt::term $envhashref, $rxvtname, [arg...] 1351=item $term = new urxvt::term $envhashref, $rxvtname, [arg...]
980 1352
981Creates a new terminal, very similar as if you had started it with system 1353Creates a new terminal, very similar as if you had started it with system
982C<$rxvtname, arg...>. C<$envhashref> must be a reference to a C<%ENV>-like 1354C<$rxvtname, arg...>. C<$envhashref> must be a reference to a C<%ENV>-like
983hash which defines the environment of the new terminal. 1355hash which defines the environment of the new terminal.
984 1356
985Croaks (and probably outputs an error message) if the new instance 1357Croaks (and probably outputs an error message) if the new instance
986couldn't be created. Returns C<undef> if the new instance didn't 1358couldn't be created. Returns C<undef> if the new instance didn't
987initialise perl, and the terminal object otherwise. The C<init> and 1359initialise perl, and the terminal object otherwise. The C<init> and
988C<start> hooks will be called during this call. 1360C<start> hooks will be called before this call returns, and are free to
1361refer to global data (which is race free).
989 1362
990=cut 1363=cut
991 1364
992sub new { 1365sub new {
993 my ($class, $env, @args) = @_; 1366 my ($class, $env, @args) = @_;
994 1367
1368 $env or Carp::croak "environment hash missing in call to urxvt::term->new";
1369 @args or Carp::croak "name argument missing in call to urxvt::term->new";
1370
995 _new ([ map "$_=$env->{$_}", keys %$env ], @args); 1371 _new ([ map "$_=$env->{$_}", keys %$env ], \@args);
996} 1372}
997 1373
998=item $term->destroy 1374=item $term->destroy
999 1375
1000Destroy the terminal object (close the window, free resources 1376Destroy the terminal object (close the window, free resources
1030 1406
1031Returns true if the option specified by C<$optval> is enabled, and 1407Returns true if the option specified by C<$optval> is enabled, and
1032optionally change it. All option values are stored by name in the hash 1408optionally change it. All option values are stored by name in the hash
1033C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash. 1409C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
1034 1410
1035Here is a a likely non-exhaustive list of option names, please see the 1411Here is a likely non-exhaustive list of option names, please see the
1036source file F</src/optinc.h> to see the actual list: 1412source file F</src/optinc.h> to see the actual list:
1037 1413
1038 borderLess console cursorBlink cursorUnderline hold iconic insecure 1414 borderLess buffered console cursorBlink cursorUnderline hold iconic
1039 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 1415 insecure intensityStyles iso14755 iso14755_52 jumpScroll loginShell
1040 override-redirect pastableTabs pointerBlank reverseVideo scrollBar 1416 mapAlert meta8 mouseWheelScrollPage override_redirect pastableTabs
1041 scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput 1417 pointerBlank reverseVideo scrollBar scrollBar_floating scrollBar_right
1042 scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs 1418 scrollTtyKeypress scrollTtyOutput scrollWithBuffer secondaryScreen
1043 transparent tripleclickwords utmpInhibit visualBell 1419 secondaryScroll skipBuiltinGlyphs skipScroll transparent tripleclickwords
1420 urgentOnBell utmpInhibit visualBell
1044 1421
1045=item $value = $term->resource ($name[, $newval]) 1422=item $value = $term->resource ($name[, $newval])
1046 1423
1047Returns the current resource value associated with a given name and 1424Returns the current resource value associated with a given name and
1048optionally sets a new value. Setting values is most useful in the C<init> 1425optionally sets a new value. Setting values is most useful in the C<init>
1057likely change). 1434likely change).
1058 1435
1059Please note that resource strings will currently only be freed when the 1436Please note that resource strings will currently only be freed when the
1060terminal is destroyed, so changing options frequently will eat memory. 1437terminal is destroyed, so changing options frequently will eat memory.
1061 1438
1062Here is a a likely non-exhaustive list of resource names, not all of which 1439Here is a likely non-exhaustive list of resource names, not all of which
1063are supported in every build, please see the source file F</src/rsinc.h> 1440are supported in every build, please see the source file F</src/rsinc.h>
1064to see the actual list: 1441to see the actual list:
1065 1442
1066 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1443 answerbackstring backgroundPixmap backspace_key blendtype blurradius
1067 borderLess color cursorBlink cursorUnderline cutchars delete_key 1444 boldFont boldItalicFont borderLess buffered chdir color cursorBlink
1068 display_name embed ext_bwidth fade font geometry hold iconName 1445 cursorUnderline cutchars delete_key depth display_name embed ext_bwidth
1069 imFont imLocale inputMethod insecure int_bwidth intensityStyles 1446 fade font geometry hold iconName iconfile imFont imLocale inputMethod
1447 insecure int_bwidth intensityStyles iso14755 iso14755_52 italicFont
1070 italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier 1448 jumpScroll letterSpace lineSpace loginShell mapAlert meta8 modifier
1071 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval 1449 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
1072 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay 1450 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
1073 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar 1451 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
1074 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness 1452 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
1075 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle 1453 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
1076 secondaryScreen secondaryScroll selectstyle shade term_name title 1454 secondaryScreen secondaryScroll shade skipBuiltinGlyphs skipScroll
1077 transient_for transparent transparent_all tripleclickwords utmpInhibit 1455 term_name title transient_for transparent tripleclickwords urgentOnBell
1078 visualBell 1456 utmpInhibit visualBell
1079 1457
1080=cut 1458=cut
1081 1459
1082sub resource($$;$) { 1460sub resource($$;$) {
1083 my ($self, $name) = (shift, shift); 1461 my ($self, $name) = (shift, shift);
1084 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 1462 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
1085 &urxvt::term::_resource 1463 goto &urxvt::term::_resource
1086} 1464}
1087 1465
1088=item $value = $term->x_resource ($pattern) 1466=item $value = $term->x_resource ($pattern)
1089 1467
1090Returns the X-Resource for the given pattern, excluding the program or 1468Returns the X-Resource for the given pattern, excluding the program or
1094 1472
1095This method should only be called during the C<on_start> hook, as there is 1473This method should only be called during the C<on_start> hook, as there is
1096only one resource database per display, and later invocations might return 1474only one resource database per display, and later invocations might return
1097the wrong resources. 1475the wrong resources.
1098 1476
1099=item $success = $term->parse_keysym ($keysym_spec, $command_string) 1477=item $success = $term->parse_keysym ($key, $octets)
1100 1478
1101Adds a keymap translation exactly as specified via a resource. See the 1479Adds a key binding exactly as specified via a resource. See the
1102C<keysym> resource in the @@RXVT_NAME@@(1) manpage. 1480C<keysym> resource in the @@RXVT_NAME@@(1) manpage.
1481
1482=item $term->register_command ($keysym, $modifiermask, $string)
1483
1484Adds a key binding. This is a lower level api compared to
1485C<parse_keysym>, as it expects a parsed key description, and can be
1486used only inside either the C<on_init> hook, to add a binding, or the
1487C<on_register_command> hook, to modify a parsed binding.
1103 1488
1104=item $rend = $term->rstyle ([$new_rstyle]) 1489=item $rend = $term->rstyle ([$new_rstyle])
1105 1490
1106Return and optionally change the current rendition. Text that is output by 1491Return and optionally change the current rendition. Text that is output by
1107the terminal application will use this style. 1492the terminal application will use this style.
1115 1500
1116=item ($row, $col) = $term->selection_beg ([$row, $col]) 1501=item ($row, $col) = $term->selection_beg ([$row, $col])
1117 1502
1118=item ($row, $col) = $term->selection_end ([$row, $col]) 1503=item ($row, $col) = $term->selection_end ([$row, $col])
1119 1504
1120Return the current values of the selection mark, begin or end positions, 1505Return the current values of the selection mark, begin or end positions.
1121and optionally set them to new values. 1506
1507When arguments are given, then the selection coordinates are set to
1508C<$row> and C<$col>, and the selection screen is set to the current
1509screen.
1510
1511=item $screen = $term->selection_screen ([$screen])
1512
1513Returns the current selection screen, and then optionally sets it.
1122 1514
1123=item $term->selection_make ($eventtime[, $rectangular]) 1515=item $term->selection_make ($eventtime[, $rectangular])
1124 1516
1125Tries to make a selection as set by C<selection_beg> and 1517Tries to make a selection as set by C<selection_beg> and
1126C<selection_end>. If C<$rectangular> is true (default: false), a 1518C<selection_end>. If C<$rectangular> is true (default: false), a
1127rectangular selection will be made. This is the prefered function to make 1519rectangular selection will be made. This is the preferred function to make
1128a selection. 1520a selection.
1129 1521
1130=item $success = $term->selection_grab ($eventtime) 1522=item $success = $term->selection_grab ($eventtime[, $clipboard])
1131 1523
1132Try to request the primary selection text from the server (for example, as 1524Try to acquire ownership of the primary (clipboard if C<$clipboard> is
1525true) selection from the server. The corresponding text can be set
1133set by the next method). No visual feedback will be given. This function 1526with the next method. No visual feedback will be given. This function
1134is mostly useful from within C<on_sel_grab> hooks. 1527is mostly useful from within C<on_sel_grab> hooks.
1135 1528
1136=item $oldtext = $term->selection ([$newtext]) 1529=item $oldtext = $term->selection ([$newtext, $clipboard])
1137 1530
1138Return the current selection text and optionally replace it by C<$newtext>. 1531Return the current selection (clipboard if C<$clipboard> is true) text
1532and optionally replace it by C<$newtext>.
1533
1534=item $term->selection_clear ([$clipboard])
1535
1536Revoke ownership of the primary (clipboard if C<$clipboard> is true) selection.
1139 1537
1140=item $term->overlay_simple ($x, $y, $text) 1538=item $term->overlay_simple ($x, $y, $text)
1141 1539
1142Create a simple multi-line overlay box. See the next method for details. 1540Create a simple multi-line overlay box. See the next method for details.
1143 1541
1173 1571
1174The methods currently supported on C<urxvt::overlay> objects are: 1572The methods currently supported on C<urxvt::overlay> objects are:
1175 1573
1176=over 4 1574=over 4
1177 1575
1178=item $overlay->set ($x, $y, $text, $rend) 1576=item $overlay->set ($x, $y, $text[, $rend])
1179 1577
1180Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts 1578Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts
1181text in rxvt-unicode's special encoding and an array of rendition values 1579text in rxvt-unicode's special encoding and an array of rendition values
1182at a specific position inside the overlay. 1580at a specific position inside the overlay.
1581
1582If C<$rend> is missing, then the rendition will not be changed.
1183 1583
1184=item $overlay->hide 1584=item $overlay->hide
1185 1585
1186If visible, hide the overlay, but do not destroy it. 1586If visible, hide the overlay, but do not destroy it.
1187 1587
1257 1657
1258Normally its not a good idea to use this function, as programs might be 1658Normally its not a good idea to use this function, as programs might be
1259confused by changes in cursor position or scrolling. Its useful inside a 1659confused by changes in cursor position or scrolling. Its useful inside a
1260C<on_add_lines> hook, though. 1660C<on_add_lines> hook, though.
1261 1661
1662=item $term->scr_change_screen ($screen)
1663
1664Switch to given screen - 0 primary, 1 secondary.
1665
1262=item $term->cmd_parse ($octets) 1666=item $term->cmd_parse ($octets)
1263 1667
1264Similar to C<scr_add_lines>, but the argument must be in the 1668Similar to C<scr_add_lines>, but the argument must be in the
1265locale-specific encoding of the terminal and can contain command sequences 1669locale-specific encoding of the terminal and can contain command sequences
1266(escape codes) that will be interpreted. 1670(escape codes) that will be interpreted.
1267 1671
1268=item $term->tt_write ($octets) 1672=item $term->tt_write ($octets)
1269 1673
1270Write the octets given in C<$data> to the tty (i.e. as program input). To 1674Write the octets given in C<$octets> to the tty (i.e. as program input). To
1271pass characters instead of octets, you should convert your strings first 1675pass characters instead of octets, you should convert your strings first
1272to the locale-specific encoding using C<< $term->locale_encode >>. 1676to the locale-specific encoding using C<< $term->locale_encode >>.
1677
1678=item $term->tt_paste ($octets)
1679
1680Write the octets given in C<$octets> to the tty as a paste, converting NL to
1681CR and bracketing the data with control sequences if bracketed paste mode
1682is set.
1273 1683
1274=item $old_events = $term->pty_ev_events ([$new_events]) 1684=item $old_events = $term->pty_ev_events ([$new_events])
1275 1685
1276Replaces the event mask of the pty watcher by the given event mask. Can 1686Replaces the event mask of the pty watcher by the given event mask. Can
1277be used to suppress input and output handling to the pty/tty. See the 1687be used to suppress input and output handling to the pty/tty. See the
1278description of C<< urxvt::timer->events >>. Make sure to always restore 1688description of C<< urxvt::timer->events >>. Make sure to always restore
1279the previous value. 1689the previous value.
1280 1690
1691=item $fd = $term->pty_fd
1692
1693Returns the master file descriptor for the pty in use, or C<-1> if no pty
1694is used.
1695
1281=item $windowid = $term->parent 1696=item $windowid = $term->parent
1282 1697
1283Return the window id of the toplevel window. 1698Return the window id of the toplevel window.
1284 1699
1285=item $windowid = $term->vt 1700=item $windowid = $term->vt
1291Adds the specified events to the vt event mask. Useful e.g. when you want 1706Adds the specified events to the vt event mask. Useful e.g. when you want
1292to receive pointer events all the times: 1707to receive pointer events all the times:
1293 1708
1294 $term->vt_emask_add (urxvt::PointerMotionMask); 1709 $term->vt_emask_add (urxvt::PointerMotionMask);
1295 1710
1711=item $term->set_urgency ($set)
1712
1713Enable/disable the urgency hint on the toplevel window.
1714
1715=item $term->focus_in
1716
1717=item $term->focus_out
1718
1719=item $term->key_press ($state, $keycode[, $time])
1720
1721=item $term->key_release ($state, $keycode[, $time])
1722
1723Deliver various fake events to to terminal.
1724
1296=item $window_width = $term->width 1725=item $window_width = $term->width
1297 1726
1298=item $window_height = $term->height 1727=item $window_height = $term->height
1299 1728
1300=item $font_width = $term->fwidth 1729=item $font_width = $term->fwidth
1330=item $env = $term->env 1759=item $env = $term->env
1331 1760
1332Returns a copy of the environment in effect for the terminal as a hashref 1761Returns a copy of the environment in effect for the terminal as a hashref
1333similar to C<\%ENV>. 1762similar to C<\%ENV>.
1334 1763
1764=item @envv = $term->envv
1765
1766Returns the environment as array of strings of the form C<VAR=VALUE>.
1767
1768=item @argv = $term->argv
1769
1770Return the argument vector as this terminal, similar to @ARGV, but
1771includes the program name as first element.
1772
1335=cut 1773=cut
1336 1774
1337sub env { 1775sub env {
1338 if (my $env = $_[0]->_env) {
1339 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env } 1776 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), $_[0]->envv }
1340 } else {
1341 +{ %ENV }
1342 }
1343} 1777}
1344 1778
1345=item $modifiermask = $term->ModLevel3Mask 1779=item $modifiermask = $term->ModLevel3Mask
1346 1780
1347=item $modifiermask = $term->ModMetaMask 1781=item $modifiermask = $term->ModMetaMask
1348 1782
1349=item $modifiermask = $term->ModNumLockMask 1783=item $modifiermask = $term->ModNumLockMask
1350 1784
1351Return the modifier masks corresponding to the "ISO Level 3 Shift" (often 1785Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
1352AltGr), the meta key (often Alt) and the num lock key, if applicable. 1786AltGr), the meta key (often Alt) and the num lock key, if applicable.
1787
1788=item $screen = $term->current_screen
1789
1790Returns the currently displayed screen (0 primary, 1 secondary).
1791
1792=item $cursor_is_hidden = $term->hidden_cursor
1793
1794Returns whether the cursor is currently hidden or not.
1353 1795
1354=item $view_start = $term->view_start ([$newvalue]) 1796=item $view_start = $term->view_start ([$newvalue])
1355 1797
1356Returns the row number of the topmost displayed line. Maximum value is 1798Returns the row number of the topmost displayed line. Maximum value is
1357C<0>, which displays the normal terminal contents. Lower values scroll 1799C<0>, which displays the normal terminal contents. Lower values scroll
1365 1807
1366Used after changing terminal contents to display them. 1808Used after changing terminal contents to display them.
1367 1809
1368=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]]) 1810=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
1369 1811
1370Returns the text of the entire row with number C<$row_number>. Row C<0> 1812Returns the text of the entire row with number C<$row_number>. Row C<< $term->top_row >>
1371is the topmost terminal line, row C<< $term->$ncol-1 >> is the bottommost 1813is the topmost terminal line, row C<< $term->nrow-1 >> is the bottommost
1372terminal line. The scrollback buffer starts at line C<-1> and extends to
1373line C<< -$term->nsaved >>. Nothing will be returned if a nonexistent line 1814terminal line. Nothing will be returned if a nonexistent line
1374is requested. 1815is requested.
1375 1816
1376If C<$new_text> is specified, it will replace characters in the current 1817If C<$new_text> is specified, it will replace characters in the current
1377line, starting at column C<$start_col> (default C<0>), which is useful 1818line, starting at column C<$start_col> (default C<0>), which is useful
1378to replace only parts of a line. The font index in the rendition will 1819to replace only parts of a line. The font index in the rendition will
1379automatically be updated. 1820automatically be updated.
1380 1821
1381C<$text> is in a special encoding: tabs and wide characters that use more 1822C<$text> is in a special encoding: tabs and wide characters that use more
1382than one cell when displayed are padded with urxvt::NOCHAR characters 1823than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535)
1383(C<chr 65535>). Characters with combining characters and other characters 1824characters. Characters with combining characters and other characters that
1384that do not fit into the normal tetx encoding will be replaced with 1825do not fit into the normal text encoding will be replaced with characters
1385characters in the private use area. 1826in the private use area.
1386 1827
1387You have to obey this encoding when changing text. The advantage is 1828You have to obey this encoding when changing text. The advantage is
1388that C<substr> and similar functions work on screen cells and not on 1829that C<substr> and similar functions work on screen cells and not on
1389characters. 1830characters.
1390 1831
1534where one character corresponds to one screen cell. See 1975where one character corresponds to one screen cell. See
1535C<< $term->ROW_t >> for details. 1976C<< $term->ROW_t >> for details.
1536 1977
1537=item $string = $term->special_decode $text 1978=item $string = $term->special_decode $text
1538 1979
1539Converts rxvt-unicodes text reprsentation into a perl string. See 1980Converts rxvt-unicodes text representation into a perl string. See
1540C<< $term->ROW_t >> for details. 1981C<< $term->ROW_t >> for details.
1541 1982
1542=item $success = $term->grab_button ($button, $modifiermask) 1983=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1543 1984
1985=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1986
1544Registers a synchronous button grab. See the XGrabButton manpage. 1987Register/unregister a synchronous button grab. See the XGrabButton
1988manpage.
1545 1989
1546=item $success = $term->grab ($eventtime[, $sync]) 1990=item $success = $term->grab ($eventtime[, $sync])
1547 1991
1548Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1992Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1549synchronous (C<$sync> is true). Also remembers the grab timestampe. 1993synchronous (C<$sync> is true). Also remembers the grab timestamp.
1550 1994
1551=item $term->allow_events_async 1995=item $term->allow_events_async
1552 1996
1553Calls XAllowEvents with AsyncBoth for the most recent grab. 1997Calls XAllowEvents with AsyncBoth for the most recent grab.
1554 1998
1561Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most 2005Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most
1562recent grab. 2006recent grab.
1563 2007
1564=item $term->ungrab 2008=item $term->ungrab
1565 2009
1566Calls XUngrab for the most recent grab. Is called automatically on 2010Calls XUngrabPointer and XUngrabKeyboard for the most recent grab. Is called automatically on
1567evaluation errors, as it is better to lose the grab in the error case as 2011evaluation errors, as it is better to lose the grab in the error case as
1568the session. 2012the session.
2013
2014=item $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
2015
2016=item $atom_name = $term->XGetAtomName ($atom)
2017
2018=item @atoms = $term->XListProperties ($window)
2019
2020=item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
2021
2022=item $term->XChangeProperty ($window, $property, $type, $format, $octets)
2023
2024=item $term->XDeleteProperty ($window, $property)
2025
2026=item $window = $term->DefaultRootWindow
2027
2028=item $term->XReparentWindow ($window, $parent, [$x, $y])
2029
2030=item $term->XMapWindow ($window)
2031
2032=item $term->XUnmapWindow ($window)
2033
2034=item $term->XMoveResizeWindow ($window, $x, $y, $width, $height)
2035
2036=item ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x, $y)
2037
2038=item $term->XChangeInput ($window, $add_events[, $del_events])
2039
2040=item $keysym = $term->XStringToKeysym ($string)
2041
2042=item $string = $term->XKeysymToString ($keysym)
2043
2044Various X or X-related functions. The C<$term> object only serves as
2045the source of the display, otherwise those functions map more-or-less
2046directly onto the X functions of the same name.
1569 2047
1570=back 2048=back
1571 2049
1572=cut 2050=cut
1573 2051
1637 my ($self, $text, $cb) = @_; 2115 my ($self, $text, $cb) = @_;
1638 2116
1639 $self->add_item ({ type => "button", text => $text, activate => $cb}); 2117 $self->add_item ({ type => "button", text => $text, activate => $cb});
1640} 2118}
1641 2119
1642=item $popup->add_toggle ($text, $cb, $initial_value) 2120=item $popup->add_toggle ($text, $initial_value, $cb)
1643 2121
1644Adds a toggle/checkbox item to the popup. Teh callback gets called 2122Adds a toggle/checkbox item to the popup. The callback gets called
1645whenever it gets toggled, with a boolean indicating its value as its first 2123whenever it gets toggled, with a boolean indicating its new value as its
1646argument. 2124first argument.
1647 2125
1648=cut 2126=cut
1649 2127
1650sub add_toggle { 2128sub add_toggle {
1651 my ($self, $text, $cb, $value) = @_; 2129 my ($self, $text, $value, $cb) = @_;
1652 2130
1653 my $item; $item = { 2131 my $item; $item = {
1654 type => "button", 2132 type => "button",
1655 text => " $text", 2133 text => " $text",
1656 value => $value, 2134 value => $value,
1675 my $env = $self->{term}->env; 2153 my $env = $self->{term}->env;
1676 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE. 2154 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
1677 delete $env->{LC_ALL}; 2155 delete $env->{LC_ALL};
1678 $env->{LC_CTYPE} = $self->{term}->locale; 2156 $env->{LC_CTYPE} = $self->{term}->locale;
1679 2157
1680 urxvt::term->new ($env, "popup", 2158 my $term = urxvt::term->new (
2159 $env, "popup",
1681 "--perl-lib" => "", "--perl-ext-common" => "", 2160 "--perl-lib" => "", "--perl-ext-common" => "",
1682 "-pty-fd" => -1, "-sl" => 0, 2161 "-pty-fd" => -1, "-sl" => 0,
1683 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect", 2162 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect",
1684 "--transient-for" => $self->{term}->parent, 2163 "--transient-for" => $self->{term}->parent,
1685 "-display" => $self->{term}->display_id, 2164 "-display" => $self->{term}->display_id,
1686 "-pe" => "urxvt-popup") 2165 "-pe" => "urxvt-popup",
1687 or die "unable to create popup window\n"; 2166 ) or die "unable to create popup window\n";
2167
2168 unless (delete $term->{urxvt_popup_init_done}) {
2169 $term->ungrab;
2170 $term->destroy;
2171 die "unable to initialise popup window\n";
2172 }
1688} 2173}
1689 2174
1690sub DESTROY { 2175sub DESTROY {
1691 my ($self) = @_; 2176 my ($self) = @_;
1692 2177
1697=back 2182=back
1698 2183
1699=cut 2184=cut
1700 2185
1701package urxvt::watcher; 2186package urxvt::watcher;
1702
1703@urxvt::timer::ISA = __PACKAGE__;
1704@urxvt::iow::ISA = __PACKAGE__;
1705@urxvt::pw::ISA = __PACKAGE__;
1706@urxvt::iw::ISA = __PACKAGE__;
1707 2187
1708=head2 The C<urxvt::timer> Class 2188=head2 The C<urxvt::timer> Class
1709 2189
1710This class implements timer watchers/events. Time is represented as a 2190This class implements timer watchers/events. Time is represented as a
1711fractional number of seconds since the epoch. Example: 2191fractional number of seconds since the epoch. Example:
1715 ->new 2195 ->new
1716 ->interval (1) 2196 ->interval (1)
1717 ->cb (sub { 2197 ->cb (sub {
1718 $term->{overlay}->set (0, 0, 2198 $term->{overlay}->set (0, 0,
1719 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]); 2199 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
1720 }); 2200 });
1721 2201
1722=over 4 2202=over 4
1723 2203
1724=item $timer = new urxvt::timer 2204=item $timer = new urxvt::timer
1725 2205
1728 2208
1729=item $timer = $timer->cb (sub { my ($timer) = @_; ... }) 2209=item $timer = $timer->cb (sub { my ($timer) = @_; ... })
1730 2210
1731Set the callback to be called when the timer triggers. 2211Set the callback to be called when the timer triggers.
1732 2212
1733=item $tstamp = $timer->at
1734
1735Return the time this watcher will fire next.
1736
1737=item $timer = $timer->set ($tstamp) 2213=item $timer = $timer->set ($tstamp[, $interval])
1738 2214
1739Set the time the event is generated to $tstamp. 2215Set the time the event is generated to $tstamp (and optionally specifies a
2216new $interval).
1740 2217
1741=item $timer = $timer->interval ($interval) 2218=item $timer = $timer->interval ($interval)
1742 2219
1743Normally (and when C<$interval> is C<0>), the timer will automatically 2220By default (and when C<$interval> is C<0>), the timer will automatically
1744stop after it has fired once. If C<$interval> is non-zero, then the timer 2221stop after it has fired once. If C<$interval> is non-zero, then the timer
1745is automatically rescheduled at the given intervals. 2222is automatically rescheduled at the given intervals.
1746 2223
1747=item $timer = $timer->start 2224=item $timer = $timer->start
1748 2225
1749Start the timer. 2226Start the timer.
1750 2227
1751=item $timer = $timer->start ($tstamp) 2228=item $timer = $timer->start ($tstamp[, $interval])
1752 2229
1753Set the event trigger time to C<$tstamp> and start the timer. 2230Set the event trigger time to C<$tstamp> and start the timer. Optionally
2231also replaces the interval.
1754 2232
1755=item $timer = $timer->after ($delay) 2233=item $timer = $timer->after ($delay[, $interval])
1756 2234
1757Like C<start>, but sets the expiry timer to c<urxvt::NOW + $delay>. 2235Like C<start>, but sets the expiry timer to c<urxvt::NOW + $delay>.
1758 2236
1759=item $timer = $timer->stop 2237=item $timer = $timer->stop
1760 2238
1768 2246
1769 $term->{socket} = ... 2247 $term->{socket} = ...
1770 $term->{iow} = urxvt::iow 2248 $term->{iow} = urxvt::iow
1771 ->new 2249 ->new
1772 ->fd (fileno $term->{socket}) 2250 ->fd (fileno $term->{socket})
1773 ->events (urxvt::EVENT_READ) 2251 ->events (urxvt::EV_READ)
1774 ->start 2252 ->start
1775 ->cb (sub { 2253 ->cb (sub {
1776 my ($iow, $revents) = @_; 2254 my ($iow, $revents) = @_;
1777 # $revents must be 1 here, no need to check 2255 # $revents must be 1 here, no need to check
1778 sysread $term->{socket}, my $buf, 8192 2256 sysread $term->{socket}, my $buf, 8192
1791Set the callback to be called when io events are triggered. C<$reventmask> 2269Set the callback to be called when io events are triggered. C<$reventmask>
1792is a bitset as described in the C<events> method. 2270is a bitset as described in the C<events> method.
1793 2271
1794=item $iow = $iow->fd ($fd) 2272=item $iow = $iow->fd ($fd)
1795 2273
1796Set the filedescriptor (not handle) to watch. 2274Set the file descriptor (not handle) to watch.
1797 2275
1798=item $iow = $iow->events ($eventmask) 2276=item $iow = $iow->events ($eventmask)
1799 2277
1800Set the event mask to watch. The only allowed values are 2278Set the event mask to watch. The only allowed values are
1801C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed 2279C<urxvt::EV_READ> and C<urxvt::EV_WRITE>, which might be ORed
1802together, or C<urxvt::EVENT_NONE>. 2280together, or C<urxvt::EV_NONE>.
1803 2281
1804=item $iow = $iow->start 2282=item $iow = $iow->start
1805 2283
1806Start watching for requested events on the given handle. 2284Start watching for requested events on the given handle.
1807 2285
1808=item $iow = $iow->stop 2286=item $iow = $iow->stop
1809 2287
1810Stop watching for events on the given filehandle. 2288Stop watching for events on the given file handle.
1811 2289
1812=back 2290=back
1813 2291
1814=head2 The C<urxvt::iw> Class 2292=head2 The C<urxvt::iw> Class
1815 2293
1848 ->new 2326 ->new
1849 ->start ($pid) 2327 ->start ($pid)
1850 ->cb (sub { 2328 ->cb (sub {
1851 my ($pw, $exit_status) = @_; 2329 my ($pw, $exit_status) = @_;
1852 ... 2330 ...
1853 }); 2331 });
1854 2332
1855=over 4 2333=over 4
1856 2334
1857=item $pw = new urxvt::pw 2335=item $pw = new urxvt::pw
1858 2336
1862 2340
1863Set the callback to be called when the timer triggers. 2341Set the callback to be called when the timer triggers.
1864 2342
1865=item $pw = $timer->start ($pid) 2343=item $pw = $timer->start ($pid)
1866 2344
1867Tells the wqtcher to start watching for process C<$pid>. 2345Tells the watcher to start watching for process C<$pid>.
1868 2346
1869=item $pw = $pw->stop 2347=item $pw = $pw->stop
1870 2348
1871Stop the watcher. 2349Stop the watcher.
1872 2350
1885 2363
1886=item >= 3 - script loading and management 2364=item >= 3 - script loading and management
1887 2365
1888=item >=10 - all called hooks 2366=item >=10 - all called hooks
1889 2367
1890=item >=11 - hook reutrn values 2368=item >=11 - hook return values
1891 2369
1892=back 2370=back
1893 2371
1894=head1 AUTHOR 2372=head1 AUTHOR
1895 2373
1896 Marc Lehmann <pcg@goof.com> 2374 Marc Lehmann <schmorp@schmorp.de>
1897 http://software.schmorp.de/pkg/rxvt-unicode 2375 http://software.schmorp.de/pkg/rxvt-unicode
1898 2376
1899=cut 2377=cut
1900 2378
19011 23791
2380
2381# vim: sw=3:

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines