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.162 by ayin, Mon Dec 17 16:57:57 2007 UTC vs.
Revision 1.248 by root, Fri Dec 26 21:01:46 2014 UTC

1=encoding utf8 1=encoding utf8
2 2
3=head1 NAME 3=head1 NAME
4 4
5@@RXVT_NAME@@perl - rxvt-unicode's embedded perl interpreter 5urxvtperl - rxvt-unicode's embedded perl interpreter
6 6
7=head1 SYNOPSIS 7=head1 SYNOPSIS
8 8
9 # create a file grab_test in $HOME: 9 # create a file grab_test in $HOME:
10 10
11 sub on_sel_grab { 11 sub on_sel_grab {
12 warn "you selected ", $_[0]->selection; 12 warn "you selected ", $_[0]->selection;
13 () 13 ()
14 } 14 }
15 15
16 # start a @@RXVT_NAME@@ using it: 16 # start a urxvt using it:
17 17
18 @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test 18 urxvt --perl-lib $HOME -pe grab_test
19 19
20=head1 DESCRIPTION 20=head1 DESCRIPTION
21 21
22Every time 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 "vars"' 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 urxvtd, 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" 31You can disable the embedded perl interpreter by setting both "perl-ext"
32and "perl-ext-common" resources to the empty string. 32and "perl-ext-common" resources to the empty string.
33 33
34=head1 PREPACKAGED EXTENSIONS 34=head1 PREPACKAGED EXTENSIONS
35 35
36This section describes the extensions delivered with this release. You can 36A number of extensions are delivered with this release. You can find them
37find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>. 37in F<< <libdir>/urxvt/perl/ >>, and the documentation can be viewed using
38F<< man urxvt-<EXTENSIONNAME> >>.
38 39
39You can activate them like this: 40You can activate them like this:
40 41
41 @@RXVT_NAME@@ -pe <extensionname> 42 urxvt -pe <extensionname>
42 43
43Or by adding them to the resource for extensions loaded by default: 44Or by adding them to the resource for extensions loaded by default:
44 45
45 URxvt.perl-ext-common: default,selection-autotransform 46 URxvt.perl-ext-common: default,selection-autotransform
46 47
47=over 4 48Extensions may add additional resources and C<actions>, i.e., methods
48 49which can be bound to a key and invoked by the user. An extension can
49=item selection (enabled by default) 50define the resources it support and also default bindings for one or
50 51more actions it provides using so called META comments, described
51(More) intelligent selection. This extension tries to be more intelligent 52below. Similarly to builtin resources, extension resources can also be
52when the user extends selections (double-click and further clicks). Right 53specified on the command line as long options (with C<.> replaced by
53now, it tries to select words, urls and complete shell-quoted 54C<->), in which case the corresponding extension is loaded
54arguments, which is very convenient, too, if your F<ls> supports 55automatically. For this to work the extension B<must> define META
55C<--quoting-style=shell>. 56comments for its resources.
56
57A double-click usually selects the word under the cursor, further clicks
58will enlarge the selection.
59
60The selection works by trying to match a number of regexes and displaying
61them in increasing order of length. You can add your own regexes by
62specifying resources of the form:
63
64 URxvt.selection.pattern-0: perl-regex
65 URxvt.selection.pattern-1: perl-regex
66 ...
67
68The index number (0, 1...) must not have any holes, and each regex must
69contain at least one pair of capturing parentheses, which will be used for
70the match. For example, the following adds a regex that matches everything
71between two vertical bars:
72
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: ^(/[^:]+):\
81
82You can look at the source of the selection extension to see more
83interesting uses, such as parsing a line from beginning to end.
84
85This extension also offers following bindable keyboard commands:
86
87=over 4
88
89=item rot13
90
91Rot-13 the selection when activated. Used via keyboard trigger:
92
93 URxvt.keysym.C-M-r: perl:selection:rot13
94
95=back
96
97=item option-popup (enabled by default)
98
99Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at
100runtime.
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
119=item selection-popup (enabled by default)
120
121Binds a popup menu to Ctrl-Button3 that lets you convert the selection
122text into various other formats/action (such as uri unescaping, perl
123evaluation, web-browser starting etc.), depending on content.
124
125Other extensions can extend this popup menu by pushing a code reference
126onto C<@{ $term->{selection_popup_hook} }>, which gets called whenever the
127popup is being displayed.
128
129Its sole argument is the popup menu, which can be modified. The selection
130is in C<$_>, which can be used to decide whether to add something or not.
131It should either return nothing or a string and a code reference. The
132string will be used as button text and the code reference will be called
133when the button gets activated and should transform C<$_>.
134
135The following will add an entry C<a to b> that transforms all C<a>s in
136the selection to C<b>s, but only if the selection currently contains any
137C<a>s:
138
139 push @{ $self->{term}{selection_popup_hook} }, sub {
140 /a/ ? ("a to b" => sub { s/a/b/g }
141 : ()
142 };
143
144=item searchable-scrollback<hotkey> (enabled by default)
145
146Adds regex search functionality to the scrollback buffer, triggered
147by a hotkey (default: C<M-s>). While in search mode, normal terminal
148input/output is suspended and a regex is displayed at the bottom of the
149screen.
150
151Inputting characters appends them to the regex and continues incremental
152search. C<BackSpace> removes a character from the regex, C<Up> and C<Down>
153search upwards/downwards in the scrollback buffer, C<End> jumps to the
154bottom. C<Escape> leaves search mode and returns to the point where search
155was started, while C<Enter> or C<Return> stay at the current position and
156additionally stores the first match in the current line into the primary
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.
189
190=item selection-autotransform
191
192This selection allows you to do automatic transforms on a selection
193whenever a selection is made.
194
195It works by specifying perl snippets (most useful is a single C<s///>
196operator) that modify C<$_> as resources:
197
198 URxvt.selection-autotransform.0: transform
199 URxvt.selection-autotransform.1: transform
200 ...
201
202For example, the following will transform selections of the form
203C<filename:number>, often seen in compiler messages, into C<vi +$filename
204$word>:
205
206 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
207
208And this example matches the same,but replaces it with vi-commands you can
209paste directly into your (vi :) editor:
210
211 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/
212
213Of course, this can be modified to suit your needs and your editor :)
214
215To expand the example above to typical perl error messages ("XXX at
216FILENAME line YYY."), you need a slightly more elaborate solution:
217
218 URxvt.selection.pattern-0: ( at .*? line \\d+[,.])
219 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/
220
221The first line tells the selection code to treat the unchanging part of
222every error message as a selection pattern, and the second line transforms
223the message into vi commands to load the file.
224
225=item tabbed
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
250Uses per-line display filtering (C<on_line_update>) to underline text
251matching a certain pattern and make it clickable. When clicked with the
252mouse button specified in the C<matcher.button> resource (default 2, or
253middle), the program specified in the C<matcher.launcher> resource
254(default, the C<urlLauncher> resource, C<sensible-browser>) will be started
255with the matched text as first argument. The default configuration is
256suitable for matching URLs and launching a web browser, like the
257former "mark-urls" extension.
258
259The default pattern to match URLs can be overridden with the
260C<matcher.pattern.0> resource, and additional patterns can be specified
261with numbered patterns, in a manner similar to the "selection" extension.
262The launcher can also be overridden on a per-pattern basis.
263
264It is possible to activate the most recently seen match from the keyboard.
265Simply bind a keysym to "perl:matcher" as seen in the example below.
266
267Example configuration:
268
269 URxvt.perl-ext: default,matcher
270 URxvt.urlLauncher: sensible-browser
271 URxvt.keysym.C-Delete: perl:matcher
272 URxvt.matcher.button: 1
273 URxvt.matcher.pattern.1: \\bwww\\.[\\w-]+\\.[\\w./?&@#-]*[\\w/-]
274 URxvt.matcher.pattern.2: \\B(/\\S+?):(\\d+)(?=:|$)
275 URxvt.matcher.launcher.2: gvim +$2 $1
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 block-graphics-to-ascii
309
310A not very useful example of filtering all text output to the terminal
311by replacing all line-drawing characters (U+2500 .. U+259F) by a
312similar-looking ascii character.
313
314=item digital-clock
315
316Displays a digital clock using the built-in overlay.
317
318=item remote-clipboard
319
320Somewhat of a misnomer, this extension adds two menu entries to the
321selection popup that allows one to run external commands to store the
322selection somewhere and fetch it again.
323
324We use it to implement a "distributed selection mechanism", which just
325means that one command uploads the file to a remote server, and another
326reads it.
327
328The commands can be set using the C<URxvt.remote-selection.store> and
329C<URxvt.remote-selection.fetch> resources. The first should read the
330selection to store from STDIN (always in UTF-8), the second should provide
331the selection data on STDOUT (also in UTF-8).
332
333The defaults (which are likely useless to you) use rsh and cat:
334
335 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
336 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
337
338=item selection-pastebin
339
340This is a little rarely useful extension that Uploads the selection as
341textfile to a remote site (or does other things). (The implementation is
342not currently secure for use in a multiuser environment as it writes to
343F</tmp> directly.).
344
345It listens to the C<selection-pastebin:remote-pastebin> keyboard command,
346i.e.
347
348 URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin
349
350Pressing this combination runs a command with C<%> replaced by the name of
351the textfile. This command can be set via a resource:
352
353 URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
354
355And the default is likely not useful to anybody but the few people around
356here :)
357
358The name of the textfile is the hex encoded md5 sum of the selection, so
359the same content should lead to the same filename.
360
361After a successful upload the selection will be replaced by the text given
362in the C<selection-pastebin-url> resource (again, the % is the placeholder
363for the filename):
364
365 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
366
367I<Note to xrdb users:> xrdb uses the C preprocessor, which might interpret
368the double C</> characters as comment start. Use C<\057\057> instead,
369which works regardless of wether xrdb is used to parse the resource file
370or not.
371
372=item example-refresh-hooks
373
374Displays a very simple digital clock in the upper right corner of the
375window. Illustrates overwriting the refresh callbacks to create your own
376overlays or changes.
377
378=back
379 57
380=head1 API DOCUMENTATION 58=head1 API DOCUMENTATION
381 59
382=head2 General API Considerations 60=head2 General API Considerations
383 61
397 75
398=over 4 76=over 4
399 77
400=item $text 78=item $text
401 79
402Rxvt-unicodes special way of encoding text, where one "unicode" character 80Rxvt-unicode's special way of encoding text, where one "unicode" character
403always represents one screen cell. See L<ROW_t> for a discussion of this format. 81always represents one screen cell. See L<ROW_t> for a discussion of this format.
404 82
405=item $string 83=item $string
406 84
407A perl text string, with an emphasis on I<text>. It can store all unicode 85A perl text string, with an emphasis on I<text>. It can store all unicode
411=item $octets 89=item $octets
412 90
413Either binary data or - more common - a text string encoded in a 91Either binary data or - more common - a text string encoded in a
414locale-specific way. 92locale-specific way.
415 93
94=item $keysym
95
96an integer that is a valid X11 keysym code. You can convert a string
97into a keysym and viceversa by using C<XStringToKeysym> and
98C<XKeysymToString>.
99
416=back 100=back
417 101
418=head2 Extension Objects 102=head2 Extension Objects
419 103
420Every perl extension is a perl class. A separate perl object is created 104Every perl extension is a perl class. A separate perl object is created
421for each terminal, and each terminal has its own set of extenion objects, 105for each terminal, and each terminal has its own set of extension objects,
422which are passed as the first parameter to hooks. So extensions can use 106which are passed as the first parameter to hooks. So extensions can use
423their C<$self> object without having to think about clashes with other 107their C<$self> object without having to think about clashes with other
424extensions or other terminals, with the exception of methods and members 108extensions or other terminals, with the exception of methods and members
425that begin with an underscore character C<_>: these are reserved for 109that begin with an underscore character C<_>: these are reserved for
426internal use. 110internal use.
427 111
428Although it isn't a C<urxvt::term> object, you can call all methods of the 112Although it isn't a C<urxvt::term> object, you can call all methods of the
429C<urxvt::term> class on this object. 113C<urxvt::term> class on this object.
430 114
431It has the following methods and data members: 115Additional methods only supported for extension objects are described in
116the C<urxvt::extension> section below.
117
118=head2 META comments
119
120Rxvt-unicode recognizes special meta comments in extensions that define
121different types of metadata.
122
123Currently, it recxognises only one such comment:
432 124
433=over 4 125=over 4
434 126
435=item $urxvt_term = $self->{term} 127=item #:META:RESOURCE:name:type:desc
436 128
437Returns the C<urxvt::term> object associated with this instance of the 129The RESOURCE comment defines a resource used by the extension, where
438extension. This member I<must not> be changed in any way. 130C<name> is the resource name, C<type> is the resource type, C<boolean>
439 131or C<string>, and C<desc> is the resource description.
440=item $self->enable ($hook_name => $cb, [$hook_name => $cb..])
441
442Dynamically enable the given hooks (named without the C<on_> prefix) for
443this extension, replacing any previous hook. This is useful when you want
444to overwrite time-critical hooks only temporarily.
445
446=item $self->disable ($hook_name[, $hook_name..])
447
448Dynamically disable the given hooks.
449 132
450=back 133=back
451 134
452=head2 Hooks 135=head2 Hooks
453 136
541 224
542It is called before lines are scrolled out (so rows 0 .. min ($lines - 1, 225It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
543$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total 226$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
544number of lines that will be in the scrollback buffer. 227number of lines that will be in the scrollback buffer.
545 228
546=item on_osc_seq $term, $op, $args 229=item on_osc_seq $term, $op, $args, $resp
547 230
548Called on every OSC sequence and can be used to suppress it or modify its 231Called on every OSC sequence and can be used to suppress it or modify its
549behaviour. The default should be to return an empty list. A true value 232behaviour. The default should be to return an empty list. A true value
550suppresses execution of the request completely. Make sure you don't get 233suppresses execution of the request completely. Make sure you don't get
551confused by recursive invocations when you output an osc sequence within 234confused by recursive invocations when you output an OSC sequence within
552this callback. 235this callback.
553 236
554C<on_osc_seq_perl> should be used for new behaviour. 237C<on_osc_seq_perl> should be used for new behaviour.
555 238
556=item on_osc_seq_perl $term, $string 239=item on_osc_seq_perl $term, $args, $resp
557 240
558Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 241Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
559operating system command) is processed. Cursor position and other state 242operating system command) is processed. Cursor position and other state
560information is up-to-date when this happens. For interoperability, the 243information is up-to-date when this happens. For interoperability, the
561string should start with the extension name and a colon, to distinguish 244string should start with the extension name (sans -osc) and a semicolon,
562it from commands for other extensions, and this might be enforced in the 245to distinguish it from commands for other extensions, and this might be
563future. 246enforced in the future.
247
248For example, C<overlay-osc> uses this:
249
250 sub on_osc_seq_perl {
251 my ($self, $osc, $resp) = @_;
252
253 return unless $osc =~ s/^overlay;//;
254
255 ... process remaining $osc string
256 }
564 257
565Be careful not ever to trust (in a security sense) the data you receive, 258Be careful not ever to trust (in a security sense) the data you receive,
566as its source can not easily be controlled (e-mail content, messages from 259as its source can not easily be controlled (e-mail content, messages from
567other users on the same system etc.). 260other users on the same system etc.).
261
262For responses, C<$resp> contains the end-of-args separator used by the
263sender.
568 264
569=item on_add_lines $term, $string 265=item on_add_lines $term, $string
570 266
571Called whenever text is about to be output, with the text as argument. You 267Called whenever text is about to be output, with the text as argument. You
572can filter/change and output the text yourself by returning a true value 268can filter/change and output the text yourself by returning a true value
577=item on_tt_write $term, $octets 273=item on_tt_write $term, $octets
578 274
579Called whenever some data is written to the tty/pty and can be used to 275Called whenever some data is written to the tty/pty and can be used to
580suppress or filter tty input. 276suppress or filter tty input.
581 277
278=item on_tt_paste $term, $octets
279
280Called whenever text is about to be pasted, with the text as argument. You
281can filter/change and paste the text yourself by returning a true value
282and calling C<< $term->tt_paste >> yourself. C<$octets> is
283locale-encoded.
284
582=item on_line_update $term, $row 285=item on_line_update $term, $row
583 286
584Called whenever a line was updated or changed. Can be used to filter 287Called whenever a line was updated or changed. Can be used to filter
585screen output (e.g. underline urls or other useless stuff). Only lines 288screen output (e.g. underline urls or other useless stuff). Only lines
586that are being shown will be filtered, and, due to performance reasons, 289that are being shown will be filtered, and, due to performance reasons,
593later with the already-modified line (e.g. if unrelated parts change), so 296later with the already-modified line (e.g. if unrelated parts change), so
594you cannot just toggle rendition bits, but only set them. 297you cannot just toggle rendition bits, but only set them.
595 298
596=item on_refresh_begin $term 299=item on_refresh_begin $term
597 300
598Called just before the screen gets redrawn. Can be used for overlay 301Called just before the screen gets redrawn. Can be used for overlay or
599or similar effects by modify terminal contents in refresh_begin, and 302similar effects by modifying the terminal contents in refresh_begin, and
600restoring them in refresh_end. The built-in overlay and selection display 303restoring them in refresh_end. The built-in overlay and selection display
601code is run after this hook, and takes precedence. 304code is run after this hook, and takes precedence.
602 305
603=item on_refresh_end $term 306=item on_refresh_end $term
604 307
605Called just after the screen gets redrawn. See C<on_refresh_begin>. 308Called just after the screen gets redrawn. See C<on_refresh_begin>.
606 309
310=item on_action $term, $string
311
312Called whenever an action is invoked for the corresponding extension
313(e.g. via a C<extension:string> builtin action bound to a key, see
314description of the B<keysym> resource in the urxvt(1) manpage). The
315event is simply the action string. Note that an action event is always
316associated to a single extension.
317
607=item on_user_command $term, $string 318=item on_user_command $term, $string *DEPRECATED*
608 319
609Called whenever a user-configured event is being activated (e.g. via 320Called whenever a user-configured event is being activated (e.g. via
610a C<perl:string> action bound to a key, see description of the B<keysym> 321a C<perl:string> action bound to a key, see description of the B<keysym>
611resource in the @@RXVT_NAME@@(1) manpage). 322resource in the urxvt(1) manpage).
612 323
613The event is simply the action string. This interface is assumed to change 324The event is simply the action string. This interface is going away in
614slightly in the future. 325preference to the C<on_action> hook.
615 326
616=item on_resize_all_windows $tern, $new_width, $new_height 327=item on_resize_all_windows $term, $new_width, $new_height
617 328
618Called just after the new window size has been calculated, but before 329Called just after the new window size has been calculated, but before
619windows are actually being resized or hints are being set. If this hook 330windows are actually being resized or hints are being set. If this hook
620returns TRUE, setting of the window hints is being skipped. 331returns a true value, setting of the window hints is being skipped.
621 332
622=item on_x_event $term, $event 333=item on_x_event $term, $event
623 334
624Called on every X event received on the vt window (and possibly other 335Called on every X event received on the vt window (and possibly other
625windows). Should only be used as a last resort. Most event structure 336windows). Should only be used as a last resort. Most event structure
655 366
656=item on_map_notify $term, $event 367=item on_map_notify $term, $event
657 368
658=item on_unmap_notify $term, $event 369=item on_unmap_notify $term, $event
659 370
660Called whenever the corresponding X event is received for the terminal If 371Called whenever the corresponding X event is received for the terminal. If
661the hook returns true, then the even will be ignored by rxvt-unicode. 372the hook returns true, then the event will be ignored by rxvt-unicode.
662 373
663The event is a hash with most values as named by Xlib (see the XEvent 374The event is a hash with most values as named by Xlib (see the XEvent
664manpage), with the additional members C<row> and C<col>, which are the 375manpage), with the additional members C<row> and C<col>, which are the
665(real, not screen-based) row and column under the mouse cursor. 376(real, not screen-based) row and column under the mouse cursor.
666 377
667C<on_key_press> additionally receives the string rxvt-unicode would 378C<on_key_press> additionally receives the string rxvt-unicode would
668output, if any, in locale-specific encoding. 379output, if any, in locale-specific encoding.
669 380
670subwindow.
671
672=item on_client_message $term, $event 381=item on_client_message $term, $event
673 382
674=item on_wm_protocols $term, $event 383=item on_wm_protocols $term, $event
675 384
676=item on_wm_delete_window $term, $event 385=item on_wm_delete_window $term, $event
677 386
678Called when various types of ClientMessage events are received (all with 387Called when various types of ClientMessage events are received (all with
679format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW). 388format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
680 389
390=item on_bell $term
391
392Called on receipt of a bell character.
393
681=back 394=back
682 395
683=cut 396=cut
684 397
685package urxvt; 398package urxvt;
686 399
687use utf8; 400use utf8;
688use strict; 401use strict 'vars';
689use Carp (); 402use Carp ();
690use Scalar::Util (); 403use Scalar::Util ();
691use List::Util (); 404use List::Util ();
692 405
693our $VERSION = 1; 406our $VERSION = 1;
694our $TERM; 407our $TERM;
695our @TERM_INIT; 408our @TERM_INIT; # should go, prevents async I/O etc.
696our @TERM_EXT; 409our @TERM_EXT; # should go, prevents async I/O etc.
697our @HOOKNAME; 410our @HOOKNAME;
698our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME; 411our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
699our %OPTION; 412our %OPTION;
700 413
701our $LIBDIR; 414our $LIBDIR;
749 462
750=over 4 463=over 4
751 464
752=item urxvt::fatal $errormessage 465=item urxvt::fatal $errormessage
753 466
754Fatally aborts execution with the given error message. Avoid at all 467Fatally aborts execution with the given error message (which should
755costs! The only time this is acceptable is when the terminal process 468include a trailing newline). Avoid at all costs! The only time this
756starts up. 469is acceptable (and useful) is in the init hook, where it prevents the
470terminal from starting up.
757 471
758=item urxvt::warn $string 472=item urxvt::warn $string
759 473
760Calls C<rxvt_warn> with the given string which should not include a 474Calls C<rxvt_warn> with the given string which should include a trailing
761newline. The module also overwrites the C<warn> builtin with a function 475newline. The module also overwrites the C<warn> builtin with a function
762that calls this function. 476that calls this function.
763 477
764Using this function has the advantage that its output ends up in the 478Using this function has the advantage that its output ends up in the
765correct place, e.g. on stderr of the connecting urxvtc client. 479correct place, e.g. on stderr of the connecting urxvtc client.
769=item @terms = urxvt::termlist 483=item @terms = urxvt::termlist
770 484
771Returns all urxvt::term objects that exist in this process, regardless of 485Returns all urxvt::term objects that exist in this process, regardless of
772whether they are started, being destroyed etc., so be careful. Only term 486whether they are started, being destroyed etc., so be careful. Only term
773objects that have perl extensions attached will be returned (because there 487objects that have perl extensions attached will be returned (because there
774is no urxvt::term objet associated with others). 488is no urxvt::term object associated with others).
775 489
776=item $time = urxvt::NOW 490=item $time = urxvt::NOW
777 491
778Returns the "current time" (as per the event loop). 492Returns the "current time" (as per the event loop).
779 493
822 536
823=item $rend = urxvt::OVERLAY_RSTYLE 537=item $rend = urxvt::OVERLAY_RSTYLE
824 538
825Return the rendition mask used for overlays by default. 539Return the rendition mask used for overlays by default.
826 540
827=item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline 541=item $rendbit = urxvt::RS_Bold, urxvt::RS_Italic, urxvt::RS_Blink,
542urxvt::RS_RVid, urxvt::RS_Uline
828 543
829Return the bit that enabled bold, italic, blink, reverse-video and 544Return the bit that enabled bold, italic, blink, reverse-video and
830underline, respectively. To enable such a style, just logically OR it into 545underline, respectively. To enable such a style, just logically OR it into
831the bitset. 546the bitset.
832 547
869 }; 584 };
870} 585}
871 586
872no warnings 'utf8'; 587no warnings 'utf8';
873 588
589sub parse_resource {
590 my ($term, $name, $isarg, $longopt, $flag, $value) = @_;
591
592 $term->scan_extensions;
593
594 my $r = $term->{meta}{resource};
595 keys %$r; # reset iterator
596 while (my ($k, $v) = each %$r) {
597 my $pattern = $k;
598 $pattern =~ y/./-/ if $isarg;
599 my $prefix = $name;
600 my $suffix;
601 if ($pattern =~ /\-$/) {
602 $prefix = substr $name, 0, length $pattern;
603 $suffix = substr $name, length $pattern;
604 }
605 if ($pattern eq $prefix) {
606 $name = "$urxvt::RESCLASS.$k$suffix";
607
608 push @{ $term->{perl_ext_3} }, $v->[0];
609
610 if ($v->[1] eq "boolean") {
611 $term->put_option_db ($name, $flag ? "true" : "false");
612 return 1;
613 } else {
614 $term->put_option_db ($name, $value);
615 return 1 + 2;
616 }
617 }
618 }
619
620 0
621}
622
623sub usage {
624 my ($term, $usage_type) = @_;
625
626 $term->scan_extensions;
627
628 my $r = $term->{meta}{resource};
629
630 for my $pattern (sort keys %$r) {
631 my ($ext, $type, $desc) = @{ $r->{$pattern} };
632
633 $desc .= " (-pe $ext)";
634
635 if ($usage_type == 1) {
636 $pattern =~ y/./-/;
637 $pattern =~ s/-$/-.../g;
638
639 if ($type eq "boolean") {
640 urxvt::log sprintf " -%-30s %s\n", "/+$pattern", $desc;
641 } else {
642 urxvt::log sprintf " -%-30s %s\n", "$pattern $type", $desc;
643 }
644 } else {
645 $pattern =~ s/\.$/.*/g;
646 urxvt::log sprintf " %-31s %s\n", "$pattern:", $type;
647 }
648 }
649}
650
874my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 651my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
875 652
876sub verbose { 653sub verbose {
877 my ($level, $msg) = @_; 654 my ($level, $msg) = @_;
878 warn "$msg\n" if $level <= $verbosity; 655 warn "$msg\n" if $level <= $verbosity;
890 $pkg =~ s/[^[:word:]]/_/g; 667 $pkg =~ s/[^[:word:]]/_/g;
891 $pkg = "urxvt::ext::$pkg"; 668 $pkg = "urxvt::ext::$pkg";
892 669
893 verbose 3, "loading extension '$path' into package '$pkg'"; 670 verbose 3, "loading extension '$path' into package '$pkg'";
894 671
672 (${"$pkg\::_NAME"} = $path) =~ s/^.*[\\\/]//; # hackish
673
895 open my $fh, "<:raw", $path 674 open my $fh, "<:raw", $path
896 or die "$path: $!"; 675 or die "$path: $!";
897 676
898 my $source = 677 my $source =
899 "package $pkg; use strict; use utf8; no warnings 'utf8';\n" 678 "package $pkg; use strict 'vars'; use utf8; no warnings 'utf8';\n"
900 . "#line 1 \"$path\"\n{\n" 679 . "#line 1 \"$path\"\n{\n"
901 . (do { local $/; <$fh> }) 680 . (do { local $/; <$fh> })
902 . "\n};\n1"; 681 . "\n};\n1";
903 682
904 eval $source 683 eval $source
913# called by the rxvt core 692# called by the rxvt core
914sub invoke { 693sub invoke {
915 local $TERM = shift; 694 local $TERM = shift;
916 my $htype = shift; 695 my $htype = shift;
917 696
918 if ($htype == 0) { # INIT 697 if ($htype == HOOK_INIT) {
919 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 698 my @dirs = $TERM->perl_libdirs;
699
700 $TERM->scan_extensions;
920 701
921 my %ext_arg; 702 my %ext_arg;
922 703
923 { 704 {
924 my @init = @TERM_INIT; 705 my @init = @TERM_INIT;
927 my @pkg = @TERM_EXT; 708 my @pkg = @TERM_EXT;
928 @TERM_EXT = (); 709 @TERM_EXT = ();
929 $TERM->register_package ($_) for @pkg; 710 $TERM->register_package ($_) for @pkg;
930 } 711 }
931 712
713 for (
932 for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) { 714 (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2),
715 @{ delete $TERM->{perl_ext_3} }
716 ) {
933 if ($_ eq "default") { 717 if ($_ eq "default") {
718
719 $ext_arg{$_} = []
934 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback readline); 720 for qw(selection option-popup selection-popup readline searchable-scrollback);
721
722 for ($TERM->_keysym_resources) {
723 next if /^(?:string|command|builtin|builtin-string|perl)/;
724 next unless /^([A-Za-z0-9_\-]+):/;
725
726 my $ext = $1;
727
728 $ext_arg{$ext} = [];
729 }
730
935 } elsif (/^-(.*)$/) { 731 } elsif (/^-(.*)$/) {
936 delete $ext_arg{$1}; 732 delete $ext_arg{$1};
733
937 } elsif (/^([^<]+)<(.*)>$/) { 734 } elsif (/^([^<]+)<(.*)>$/) {
938 push @{ $ext_arg{$1} }, $2; 735 push @{ $ext_arg{$1} }, $2;
736
939 } else { 737 } else {
940 $ext_arg{$_} ||= []; 738 $ext_arg{$_} ||= [];
941 } 739 }
942 } 740 }
943 741
959 757
960 if (my $cb = $TERM->{_hook}[$htype]) { 758 if (my $cb = $TERM->{_hook}[$htype]) {
961 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")" 759 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
962 if $verbosity >= 10; 760 if $verbosity >= 10;
963 761
762 if ($htype == HOOK_ACTION) {
763 # this hook is only sent to the extension with the name
764 # matching the first arg
765 my $pkg = shift;
766 $pkg =~ y/-/_/;
767 $pkg = "urxvt::ext::$pkg";
768
769 $cb = $cb->{$pkg}
770 or return undef; #TODO: maybe warn user?
771
772 $cb = { $pkg => $cb };
773 }
774
964 for my $pkg (keys %$cb) { 775 for my $pkg (keys %$cb) {
965 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg}, @_) }; 776 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg} || $TERM, @_) };
966 $retval ||= $retval_; 777 $retval ||= $retval_;
967 778
968 if ($@) { 779 if ($@) {
969 $TERM->ungrab; # better to lose the grab than the session 780 $TERM->ungrab; # better to lose the grab than the session
970 warn $@; 781 warn $@;
973 784
974 verbose 11, "$HOOKNAME[$htype] returning <$retval>" 785 verbose 11, "$HOOKNAME[$htype] returning <$retval>"
975 if $verbosity >= 11; 786 if $verbosity >= 11;
976 } 787 }
977 788
978 if ($htype == 1) { # DESTROY 789 if ($htype == HOOK_DESTROY) {
979 # clear package objects 790 # clear package objects
980 %$_ = () for values %{ $TERM->{_pkg} }; 791 %$_ = () for values %{ $TERM->{_pkg} };
981 792
982 # clear package 793 # clear package
983 %$TERM = (); 794 %$TERM = ();
1013 } 824 }
1014 } 825 }
1015 ($mask, @color{qw(fg bg)}, \@failed) 826 ($mask, @color{qw(fg bg)}, \@failed)
1016} 827}
1017 828
1018# urxvt::term::extension
1019
1020package urxvt::term::extension; 829package urxvt::term::extension;
1021 830
1022sub enable { 831=head2 The C<urxvt::term::extension> class
1023 my ($self, %hook) = @_;
1024 my $pkg = $self->{_pkg};
1025 832
1026 while (my ($name, $cb) = each %hook) { 833Each extension attached to a terminal object is represented by
1027 my $htype = $HOOKTYPE{uc $name}; 834a C<urxvt::term::extension> object.
1028 defined $htype
1029 or Carp::croak "unsupported hook type '$name'";
1030 835
1031 $self->set_should_invoke ($htype, +1) 836You can use these objects, which are passed to all callbacks to store any
1032 unless exists $self->{term}{_hook}[$htype]{$pkg}; 837state related to the terminal and extension instance.
1033 838
1034 $self->{term}{_hook}[$htype]{$pkg} = $cb; 839The methods (And data members) documented below can be called on extension
1035 } 840objects, in addition to call methods documented for the <urxvt::term>
1036} 841class.
1037 842
1038sub disable { 843=over 4
1039 my ($self, @hook) = @_;
1040 my $pkg = $self->{_pkg};
1041 844
1042 for my $name (@hook) { 845=item $urxvt_term = $self->{term}
1043 my $htype = $HOOKTYPE{uc $name};
1044 defined $htype
1045 or Carp::croak "unsupported hook type '$name'";
1046 846
1047 $self->set_should_invoke ($htype, -1) 847Returns the C<urxvt::term> object associated with this instance of the
1048 if delete $self->{term}{_hook}[$htype]{$pkg}; 848extension. This member I<must not> be changed in any way.
1049 } 849
1050} 850=cut
1051 851
1052our $AUTOLOAD; 852our $AUTOLOAD;
1053 853
1054sub AUTOLOAD { 854sub AUTOLOAD {
1055 $AUTOLOAD =~ /:([^:]+)$/ 855 $AUTOLOAD =~ /:([^:]+)$/
1068 868
1069sub DESTROY { 869sub DESTROY {
1070 # nop 870 # nop
1071} 871}
1072 872
1073# urxvt::destroy_hook 873# urxvt::destroy_hook (basically a cheap Guard:: implementation)
1074 874
1075sub urxvt::destroy_hook::DESTROY { 875sub urxvt::destroy_hook::DESTROY {
1076 ${$_[0]}->(); 876 ${$_[0]}->();
1077} 877}
1078 878
1079sub urxvt::destroy_hook(&) { 879sub urxvt::destroy_hook(&) {
1080 bless \shift, urxvt::destroy_hook:: 880 bless \shift, urxvt::destroy_hook::
1081} 881}
882
883=item $self->enable ($hook_name => $cb[, $hook_name => $cb..])
884
885Dynamically enable the given hooks (named without the C<on_> prefix) for
886this extension, replacing any hook previously installed via C<enable> in
887this extension.
888
889This is useful when you want to overwrite time-critical hooks only
890temporarily.
891
892To install additional callbacks for the same hook, you can use the C<on>
893method of the C<urxvt::term> class.
894
895=item $self->disable ($hook_name[, $hook_name..])
896
897Dynamically disable the given hooks.
898
899=cut
900
901sub enable {
902 my ($self, %hook) = @_;
903 my $pkg = $self->{_pkg};
904
905 while (my ($name, $cb) = each %hook) {
906 my $htype = $HOOKTYPE{uc $name};
907 defined $htype
908 or Carp::croak "unsupported hook type '$name'";
909
910 $self->set_should_invoke ($htype, +1)
911 unless exists $self->{term}{_hook}[$htype]{$pkg};
912
913 $self->{term}{_hook}[$htype]{$pkg} = $cb;
914 }
915}
916
917sub disable {
918 my ($self, @hook) = @_;
919 my $pkg = $self->{_pkg};
920
921 for my $name (@hook) {
922 my $htype = $HOOKTYPE{uc $name};
923 defined $htype
924 or Carp::croak "unsupported hook type '$name'";
925
926 $self->set_should_invoke ($htype, -1)
927 if delete $self->{term}{_hook}[$htype]{$pkg};
928 }
929}
930
931=item $guard = $self->on ($hook_name => $cb[, $hook_name => $cb..])
932
933Similar to the C<enable> enable, but installs additional callbacks for
934the given hook(s) (that is, it doesn't replace existing callbacks), and
935returns a guard object. When the guard object is destroyed the callbacks
936are disabled again.
937
938=cut
939
940sub urxvt::extension::on_disable::DESTROY {
941 my $disable = shift;
942
943 my $term = delete $disable->{""};
944
945 while (my ($htype, $id) = each %$disable) {
946 delete $term->{_hook}[$htype]{$id};
947 $term->set_should_invoke ($htype, -1);
948 }
949}
950
951sub on {
952 my ($self, %hook) = @_;
953
954 my $term = $self->{term};
955
956 my %disable = ( "" => $term );
957
958 while (my ($name, $cb) = each %hook) {
959 my $htype = $HOOKTYPE{uc $name};
960 defined $htype
961 or Carp::croak "unsupported hook type '$name'";
962
963 $term->set_should_invoke ($htype, +1);
964 $term->{_hook}[$htype]{ $disable{$htype} = $cb+0 }
965 = sub { shift; $cb->($self, @_) }; # very ugly indeed
966 }
967
968 bless \%disable, "urxvt::extension::on_disable"
969}
970
971=item $self->bind_action ($hotkey, $action)
972
973=item $self->x_resource ($pattern)
974
975=item $self->x_resource_boolean ($pattern)
976
977These methods support an additional C<%> prefix for C<$action> or
978C<$pattern> when called on an extension object, compared to the
979C<urxvt::term> methods of the same name - see the description of these
980methods in the C<urxvt::term> class for details.
981
982=cut
983
984sub bind_action {
985 my ($self, $hotkey, $action) = @_;
986 $action =~ s/^%:/$_[0]{_name}:/;
987 $self->{term}->bind_action ($hotkey, $action)
988}
989
990sub x_resource {
991 my ($self, $name) = @_;
992 $name =~ s/^%(\.|$)/$_[0]{_name}$1/;
993 $self->{term}->x_resource ($name)
994}
995
996sub x_resource_boolean {
997 my ($self, $name) = @_;
998 $name =~ s/^%(\.|$)/$_[0]{_name}$1/;
999 $self->{term}->x_resource_boolean ($name)
1000}
1001
1002=back
1003
1004=cut
1082 1005
1083package urxvt::anyevent; 1006package urxvt::anyevent;
1084 1007
1085=head2 The C<urxvt::anyevent> Class 1008=head2 The C<urxvt::anyevent> Class
1086 1009
1087The sole purpose of this class is to deliver an interface to the 1010The sole purpose of this class is to deliver an interface to the
1088C<AnyEvent> module - any module using it will work inside urxvt without 1011C<AnyEvent> module - any module using it will work inside urxvt without
1089further programming. The only exception is that you cannot wait on 1012further programming. The only exception is that you cannot wait on
1090condition variables, but non-blocking condvar use is ok. What this means 1013condition variables, but non-blocking condvar use is ok.
1091is that you cannot use blocking APIs, but the non-blocking variant should
1092work.
1093 1014
1094=cut 1015In practical terms this means is that you cannot use blocking APIs, but
1016the non-blocking variant should work.
1095 1017
1018=cut
1019
1096our $VERSION = 1; 1020our $VERSION = '5.23';
1097 1021
1098$INC{"urxvt/anyevent.pm"} = 1; # mark us as there 1022$INC{"urxvt/anyevent.pm"} = 1; # mark us as there
1099push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::]; 1023push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
1100 1024
1101sub timer { 1025sub timer {
1103 1027
1104 my $cb = $arg{cb}; 1028 my $cb = $arg{cb};
1105 1029
1106 urxvt::timer 1030 urxvt::timer
1107 ->new 1031 ->new
1108 ->start (urxvt::NOW + $arg{after}) 1032 ->after ($arg{after}, $arg{interval})
1109 ->cb (sub { 1033 ->cb ($arg{interval} ? $cb : sub {
1110 $_[0]->stop; # need to cancel manually 1034 $_[0]->stop; # need to cancel manually
1111 $cb->(); 1035 $cb->();
1112 }) 1036 })
1113} 1037}
1114 1038
1115sub io { 1039sub io {
1116 my ($class, %arg) = @_; 1040 my ($class, %arg) = @_;
1117 1041
1118 my $cb = $arg{cb}; 1042 my $cb = $arg{cb};
1043 my $fd = fileno $arg{fh};
1044 defined $fd or $fd = $arg{fh};
1119 1045
1120 bless [$arg{fh}, urxvt::iow 1046 bless [$arg{fh}, urxvt::iow
1121 ->new 1047 ->new
1122 ->fd (fileno $arg{fh}) 1048 ->fd ($fd)
1123 ->events (($arg{poll} =~ /r/ ? 1 : 0) 1049 ->events (($arg{poll} =~ /r/ ? 1 : 0)
1124 | ($arg{poll} =~ /w/ ? 2 : 0)) 1050 | ($arg{poll} =~ /w/ ? 2 : 0))
1125 ->start 1051 ->start
1126 ->cb (sub { 1052 ->cb ($cb)
1127 $cb->(($_[1] & 1 ? 'r' : '')
1128 . ($_[1] & 2 ? 'w' : ''));
1129 })],
1130 urxvt::anyevent:: 1053 ], urxvt::anyevent::
1054}
1055
1056sub idle {
1057 my ($class, %arg) = @_;
1058
1059 my $cb = $arg{cb};
1060
1061 urxvt::iw
1062 ->new
1063 ->start
1064 ->cb ($cb)
1065}
1066
1067sub child {
1068 my ($class, %arg) = @_;
1069
1070 my $cb = $arg{cb};
1071
1072 urxvt::pw
1073 ->new
1074 ->start ($arg{pid})
1075 ->cb (sub {
1076 $_[0]->stop; # need to cancel manually
1077 $cb->($_[0]->rpid, $_[0]->rstatus);
1078 })
1131} 1079}
1132 1080
1133sub DESTROY { 1081sub DESTROY {
1134 $_[0][1]->stop; 1082 $_[0][1]->stop;
1135} 1083}
1136 1084
1137sub condvar { 1085# only needed for AnyEvent < 6 compatibility
1138 bless \my $flag, urxvt::anyevent::
1139}
1140
1141sub broadcast {
1142 ${$_[0]}++;
1143}
1144
1145sub wait {
1146 unless (${$_[0]}) {
1147 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API";
1148 }
1149}
1150
1151sub one_event { 1086sub one_event {
1152 Carp::croak "AnyEvent->one_event blocking wait unsupported in urxvt, use a non-blocking API"; 1087 Carp::croak "AnyEvent->one_event blocking wait unsupported in urxvt, use a non-blocking API";
1153} 1088}
1154 1089
1155package urxvt::term; 1090package urxvt::term;
1170 urxvt::verbose 6, "register package $pkg to $self"; 1105 urxvt::verbose 6, "register package $pkg to $self";
1171 1106
1172 @{"$pkg\::ISA"} = urxvt::term::extension::; 1107 @{"$pkg\::ISA"} = urxvt::term::extension::;
1173 1108
1174 my $proxy = bless { 1109 my $proxy = bless {
1175 _pkg => $pkg, 1110 _pkg => $pkg,
1111 _name => ${"$pkg\::_NAME"}, # hackish
1176 argv => $argv, 1112 argv => $argv,
1177 }, $pkg; 1113 }, $pkg;
1178 Scalar::Util::weaken ($proxy->{term} = $self); 1114 Scalar::Util::weaken ($proxy->{term} = $self);
1179 1115
1180 $self->{_pkg}{$pkg} = $proxy; 1116 $self->{_pkg}{$pkg} = $proxy;
1181 1117
1184 $proxy->enable ($name => $ref); 1120 $proxy->enable ($name => $ref);
1185 } 1121 }
1186 } 1122 }
1187} 1123}
1188 1124
1125sub perl_libdirs {
1126 map { split /:/ }
1127 $_[0]->resource ("perl_lib"),
1128 $ENV{URXVT_PERL_LIB},
1129 "$ENV{HOME}/.urxvt/ext",
1130 "$LIBDIR/perl"
1131}
1132
1133# scan for available extensions and collect their metadata
1134sub scan_extensions {
1135 my ($self) = @_;
1136
1137 return if exists $self->{meta};
1138
1139 my @libdirs = perl_libdirs $self;
1140
1141# return if $self->{meta_libdirs} eq join "\x00", @libdirs;#d#
1142
1143# $self->{meta_libdirs} = join "\x00", @libdirs;#d#
1144 $self->{meta} = \my %meta;
1145
1146 # first gather extensions
1147 for my $dir (reverse @libdirs) {
1148 opendir my $fh, $dir
1149 or next;
1150 for my $ext (readdir $fh) {
1151 $ext !~ /^\./
1152 and open my $fh, "<", "$dir/$ext"
1153 or next;
1154
1155 my %ext = (dir => $dir);
1156
1157 while (<$fh>) {
1158 if (/^#:META:(?:X_)?RESOURCE:(.*)/) {
1159 my ($pattern, $type, $desc) = split /:/, $1;
1160 $pattern =~ s/^%(\.|$)/$ext$1/g; # % in pattern == extension name
1161 if ($pattern =~ /[^a-zA-Z0-9\-\.]/) {
1162 warn "$dir/$ext: meta resource '$pattern' contains illegal characters (not alphanumeric nor . nor *)\n";
1163 } else {
1164 $ext{resource}{$pattern} = [$ext, $type, $desc];
1165 }
1166 } elsif (/^\s*(?:#|$)/) {
1167 # skip other comments and empty lines
1168 } else {
1169 last; # stop parsing on first non-empty non-comment line
1170 }
1171 }
1172
1173 $meta{ext}{$ext} = \%ext;
1174 }
1175 }
1176
1177 # and now merge resources
1178 while (my ($k, $v) = each %{ $meta{ext} }) {
1179 #TODO: should check for extensions overriding each other
1180 %{ $meta{resource} } = (%{ $meta{resource} }, %{ $v->{resource} });
1181 }
1182}
1183
1189=item $term = new urxvt::term $envhashref, $rxvtname, [arg...] 1184=item $term = new urxvt::term $envhashref, $rxvtname, [arg...]
1190 1185
1191Creates a new terminal, very similar as if you had started it with system 1186Creates a new terminal, very similar as if you had started it with system
1192C<$rxvtname, arg...>. C<$envhashref> must be a reference to a C<%ENV>-like 1187C<$rxvtname, arg...>. C<$envhashref> must be a reference to a C<%ENV>-like
1193hash which defines the environment of the new terminal. 1188hash which defines the environment of the new terminal.
1210} 1205}
1211 1206
1212=item $term->destroy 1207=item $term->destroy
1213 1208
1214Destroy the terminal object (close the window, free resources 1209Destroy the terminal object (close the window, free resources
1215etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event 1210etc.). Please note that urxvt will not exit as long as any event
1216watchers (timers, io watchers) are still active. 1211watchers (timers, io watchers) are still active.
1217 1212
1218=item $term->exec_async ($cmd[, @args]) 1213=item $term->exec_async ($cmd[, @args])
1219 1214
1220Works like the combination of the C<fork>/C<exec> builtins, which executes 1215Works like the combination of the C<fork>/C<exec> builtins, which executes
1247C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash. 1242C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
1248 1243
1249Here is a likely non-exhaustive list of option names, please see the 1244Here is a likely non-exhaustive list of option names, please see the
1250source file F</src/optinc.h> to see the actual list: 1245source file F</src/optinc.h> to see the actual list:
1251 1246
1252 borderLess console cursorBlink cursorUnderline hold iconic insecure 1247 borderLess buffered console cursorBlink cursorUnderline hold iconic
1253 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 1248 insecure intensityStyles iso14755 iso14755_52 jumpScroll loginShell
1254 override-redirect pastableTabs pointerBlank reverseVideo scrollBar 1249 mapAlert meta8 mouseWheelScrollPage override_redirect pastableTabs
1255 scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput 1250 pointerBlank reverseVideo scrollBar scrollBar_floating scrollBar_right
1256 scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs 1251 scrollTtyKeypress scrollTtyOutput scrollWithBuffer secondaryScreen
1257 transparent tripleclickwords utmpInhibit visualBell 1252 secondaryScroll skipBuiltinGlyphs skipScroll transparent tripleclickwords
1253 urgentOnBell utmpInhibit visualBell
1258 1254
1259=item $value = $term->resource ($name[, $newval]) 1255=item $value = $term->resource ($name[, $newval])
1260 1256
1261Returns the current resource value associated with a given name and 1257Returns the current resource value associated with a given name and
1262optionally sets a new value. Setting values is most useful in the C<init> 1258optionally sets a new value. Setting values is most useful in the C<init>
1275 1271
1276Here is a likely non-exhaustive list of resource names, not all of which 1272Here is a likely non-exhaustive list of resource names, not all of which
1277are supported in every build, please see the source file F</src/rsinc.h> 1273are supported in every build, please see the source file F</src/rsinc.h>
1278to see the actual list: 1274to see the actual list:
1279 1275
1280 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1276 answerbackstring backgroundPixmap backspace_key blurradius
1281 borderLess color cursorBlink cursorUnderline cutchars delete_key 1277 boldFont boldItalicFont borderLess buffered chdir color cursorBlink
1282 display_name embed ext_bwidth fade font geometry hold iconName 1278 cursorUnderline cutchars delete_key depth display_name embed ext_bwidth
1283 imFont imLocale inputMethod insecure int_bwidth intensityStyles 1279 fade font geometry hold iconName iconfile imFont imLocale inputMethod
1280 insecure int_bwidth intensityStyles iso14755 iso14755_52 italicFont
1284 italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier 1281 jumpScroll letterSpace lineSpace loginShell mapAlert meta8 modifier
1285 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval 1282 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
1286 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay 1283 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
1287 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar 1284 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
1288 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness 1285 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
1289 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle 1286 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
1290 secondaryScreen secondaryScroll selectstyle shade term_name title 1287 secondaryScreen secondaryScroll shade skipBuiltinGlyphs skipScroll
1291 transient_for transparent transparent_all tripleclickwords utmpInhibit 1288 term_name title transient_for transparent tripleclickwords urgentOnBell
1292 visualBell 1289 utmpInhibit visualBell
1293 1290
1294=cut 1291=cut
1295 1292
1296sub resource($$;$) { 1293sub resource($$;$) {
1297 my ($self, $name) = (shift, shift); 1294 my ($self, $name) = (shift, shift);
1298 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 1295 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
1299 &urxvt::term::_resource 1296 goto &urxvt::term::_resource
1300} 1297}
1301 1298
1302=item $value = $term->x_resource ($pattern) 1299=item $value = $term->x_resource ($pattern)
1303 1300
1304Returns the X-Resource for the given pattern, excluding the program or 1301Returns the X-Resource for the given pattern, excluding the program or
1305class name, i.e. C<< $term->x_resource ("boldFont") >> should return the 1302class name, i.e. C<< $term->x_resource ("boldFont") >> should return the
1306same value as used by this instance of rxvt-unicode. Returns C<undef> if no 1303same value as used by this instance of rxvt-unicode. Returns C<undef> if no
1307resource with that pattern exists. 1304resource with that pattern exists.
1308 1305
1306Extensions that define extra resources also need to call this method
1307to access their values.
1308
1309If the method is called on an extension object (basically, from an
1310extension), then the special prefix C<%.> will be replaced by the name of
1311the extension and a dot, and the lone string C<%> will be replaced by the
1312extension name itself. This makes it possible to code extensions so you
1313can rename them and get a new set of resources without having to change
1314the actual code.
1315
1309This method should only be called during the C<on_start> hook, as there is 1316This method should only be called during the C<on_start> hook, as there is
1310only one resource database per display, and later invocations might return 1317only one resource database per display, and later invocations might return
1311the wrong resources. 1318the wrong resources.
1312 1319
1313=item $success = $term->parse_keysym ($keysym_spec, $command_string) 1320=item $value = $term->x_resource_boolean ($pattern)
1314 1321
1322Like C<x_resource>, above, but interprets the string value as a boolean
1323and returns C<1> for true values, C<0> for false values and C<undef> if
1324the resource or option isn't specified.
1325
1326You should always use this method to parse boolean resources.
1327
1328=cut
1329
1330sub x_resource_boolean {
1331 my $res = &x_resource;
1332
1333 $res =~ /^\s*(?:true|yes|on|1)\s*$/i ? 1 : defined $res && 0
1334}
1335
1336=item $success = $term->bind_action ($key, $action)
1337
1315Adds a keymap translation exactly as specified via a resource. See the 1338Adds a key binding exactly as specified via a C<keysym> resource. See the
1316C<keysym> resource in the @@RXVT_NAME@@(1) manpage. 1339C<keysym> resource in the urxvt(1) manpage.
1340
1341To add default bindings for an extension, the extension should call C<<
1342->bind_action >> on it's C<init> hook for every such binding. Doing it
1343in the C<init> hook allows users the override or remove the the binding
1344again.
1345
1346Example: the C<searchable-scrollback> by default binds itself
1347on C<Meta-s>, using C<< $self->bind_action >>, which calls C<<
1348$term->bind_action >>.
1349
1350 sub init {
1351 my ($self) = @_;
1352
1353 $self->bind_action ("M-s" => "%:start");
1354 }
1317 1355
1318=item $rend = $term->rstyle ([$new_rstyle]) 1356=item $rend = $term->rstyle ([$new_rstyle])
1319 1357
1320Return and optionally change the current rendition. Text that is output by 1358Return and optionally change the current rendition. Text that is output by
1321the terminal application will use this style. 1359the terminal application will use this style.
1329 1367
1330=item ($row, $col) = $term->selection_beg ([$row, $col]) 1368=item ($row, $col) = $term->selection_beg ([$row, $col])
1331 1369
1332=item ($row, $col) = $term->selection_end ([$row, $col]) 1370=item ($row, $col) = $term->selection_end ([$row, $col])
1333 1371
1334Return the current values of the selection mark, begin or end positions, 1372Return the current values of the selection mark, begin or end positions.
1335and optionally set them to new values. 1373
1374When arguments are given, then the selection coordinates are set to
1375C<$row> and C<$col>, and the selection screen is set to the current
1376screen.
1377
1378=item $screen = $term->selection_screen ([$screen])
1379
1380Returns the current selection screen, and then optionally sets it.
1336 1381
1337=item $term->selection_make ($eventtime[, $rectangular]) 1382=item $term->selection_make ($eventtime[, $rectangular])
1338 1383
1339Tries to make a selection as set by C<selection_beg> and 1384Tries to make a selection as set by C<selection_beg> and
1340C<selection_end>. If C<$rectangular> is true (default: false), a 1385C<selection_end>. If C<$rectangular> is true (default: false), a
1341rectangular selection will be made. This is the prefered function to make 1386rectangular selection will be made. This is the preferred function to make
1342a selection. 1387a selection.
1343 1388
1344=item $success = $term->selection_grab ($eventtime) 1389=item $success = $term->selection_grab ($eventtime[, $clipboard])
1345 1390
1346Try to request the primary selection text from the server (for example, as 1391Try to acquire ownership of the primary (clipboard if C<$clipboard> is
1392true) selection from the server. The corresponding text can be set
1347set by the next method). No visual feedback will be given. This function 1393with the next method. No visual feedback will be given. This function
1348is mostly useful from within C<on_sel_grab> hooks. 1394is mostly useful from within C<on_sel_grab> hooks.
1349 1395
1350=item $oldtext = $term->selection ([$newtext]) 1396=item $oldtext = $term->selection ([$newtext, $clipboard])
1351 1397
1352Return the current selection text and optionally replace it by C<$newtext>. 1398Return the current selection (clipboard if C<$clipboard> is true) text
1399and optionally replace it by C<$newtext>.
1400
1401=item $term->selection_clear ([$clipboard])
1402
1403Revoke ownership of the primary (clipboard if C<$clipboard> is true) selection.
1353 1404
1354=item $term->overlay_simple ($x, $y, $text) 1405=item $term->overlay_simple ($x, $y, $text)
1355 1406
1356Create a simple multi-line overlay box. See the next method for details. 1407Create a simple multi-line overlay box. See the next method for details.
1357 1408
1387 1438
1388The methods currently supported on C<urxvt::overlay> objects are: 1439The methods currently supported on C<urxvt::overlay> objects are:
1389 1440
1390=over 4 1441=over 4
1391 1442
1392=item $overlay->set ($x, $y, $text, $rend) 1443=item $overlay->set ($x, $y, $text[, $rend])
1393 1444
1394Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts 1445Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts
1395text in rxvt-unicode's special encoding and an array of rendition values 1446text in rxvt-unicode's special encoding and an array of rendition values
1396at a specific position inside the overlay. 1447at a specific position inside the overlay.
1448
1449If C<$rend> is missing, then the rendition will not be changed.
1397 1450
1398=item $overlay->hide 1451=item $overlay->hide
1399 1452
1400If visible, hide the overlay, but do not destroy it. 1453If visible, hide the overlay, but do not destroy it.
1401 1454
1464 1517
1465=item $term->scr_add_lines ($string) 1518=item $term->scr_add_lines ($string)
1466 1519
1467Write the given text string to the screen, as if output by the application 1520Write the given text string to the screen, as if output by the application
1468running inside the terminal. It may not contain command sequences (escape 1521running inside the terminal. It may not contain command sequences (escape
1469codes), but is free to use line feeds, carriage returns and tabs. The 1522codes - see C<cmd_parse> for that), but is free to use line feeds,
1470string is a normal text string, not in locale-dependent encoding. 1523carriage returns and tabs. The string is a normal text string, not in
1524locale-dependent encoding.
1471 1525
1472Normally its not a good idea to use this function, as programs might be 1526Normally its not a good idea to use this function, as programs might be
1473confused by changes in cursor position or scrolling. Its useful inside a 1527confused by changes in cursor position or scrolling. Its useful inside a
1474C<on_add_lines> hook, though. 1528C<on_add_lines> hook, though.
1475 1529
1483locale-specific encoding of the terminal and can contain command sequences 1537locale-specific encoding of the terminal and can contain command sequences
1484(escape codes) that will be interpreted. 1538(escape codes) that will be interpreted.
1485 1539
1486=item $term->tt_write ($octets) 1540=item $term->tt_write ($octets)
1487 1541
1488Write the octets given in C<$data> to the tty (i.e. as program input). To 1542Write the octets given in C<$octets> to the tty (i.e. as user input
1543to the program, see C<cmd_parse> for the opposite direction). To pass
1489pass characters instead of octets, you should convert your strings first 1544characters instead of octets, you should convert your strings first to the
1490to the locale-specific encoding using C<< $term->locale_encode >>. 1545locale-specific encoding using C<< $term->locale_encode >>.
1546
1547=item $term->tt_write_user_input ($octets)
1548
1549Like C<tt_write>, but should be used when writing strings in response to
1550the user pressing a key, to invoke the additional actions requested by
1551the user for that case (C<tt_write> doesn't do that).
1552
1553The typical use case would be inside C<on_action> hooks.
1554
1555=item $term->tt_paste ($octets)
1556
1557Write the octets given in C<$octets> to the tty as a paste, converting NL to
1558CR and bracketing the data with control sequences if bracketed paste mode
1559is set.
1491 1560
1492=item $old_events = $term->pty_ev_events ([$new_events]) 1561=item $old_events = $term->pty_ev_events ([$new_events])
1493 1562
1494Replaces the event mask of the pty watcher by the given event mask. Can 1563Replaces the event mask of the pty watcher by the given event mask. Can
1495be used to suppress input and output handling to the pty/tty. See the 1564be used to suppress input and output handling to the pty/tty. See the
1514Adds the specified events to the vt event mask. Useful e.g. when you want 1583Adds the specified events to the vt event mask. Useful e.g. when you want
1515to receive pointer events all the times: 1584to receive pointer events all the times:
1516 1585
1517 $term->vt_emask_add (urxvt::PointerMotionMask); 1586 $term->vt_emask_add (urxvt::PointerMotionMask);
1518 1587
1588=item $term->set_urgency ($set)
1589
1590Enable/disable the urgency hint on the toplevel window.
1591
1519=item $term->focus_in 1592=item $term->focus_in
1520 1593
1521=item $term->focus_out 1594=item $term->focus_out
1522 1595
1523=item $term->key_press ($state, $keycode[, $time]) 1596=item $term->key_press ($state, $keycode[, $time])
1611 1684
1612Used after changing terminal contents to display them. 1685Used after changing terminal contents to display them.
1613 1686
1614=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]]) 1687=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
1615 1688
1616Returns the text of the entire row with number C<$row_number>. Row C<0> 1689Returns the text of the entire row with number C<$row_number>. Row C<< $term->top_row >>
1617is the topmost terminal line, row C<< $term->$ncol-1 >> is the bottommost 1690is the topmost terminal line, row C<< $term->nrow-1 >> is the bottommost
1618terminal line. The scrollback buffer starts at line C<-1> and extends to
1619line C<< -$term->nsaved >>. Nothing will be returned if a nonexistent line 1691terminal line. Nothing will be returned if a nonexistent line
1620is requested. 1692is requested.
1621 1693
1622If C<$new_text> is specified, it will replace characters in the current 1694If C<$new_text> is specified, it will replace characters in the current
1623line, starting at column C<$start_col> (default C<0>), which is useful 1695line, starting at column C<$start_col> (default C<0>), which is useful
1624to replace only parts of a line. The font index in the rendition will 1696to replace only parts of a line. The font index in the rendition will
1720} 1792}
1721 1793
1722sub urxvt::line::t { 1794sub urxvt::line::t {
1723 my ($self) = @_; 1795 my ($self) = @_;
1724 1796
1725 if (@_ > 1) 1797 if (@_ > 1) {
1726 {
1727 $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol}) 1798 $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
1728 for $self->{beg} .. $self->{end}; 1799 for $self->{beg} .. $self->{end};
1729 } 1800 }
1730 1801
1731 defined wantarray && 1802 defined wantarray &&
1732 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}), 1803 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
1733 0, $self->{len} 1804 0, $self->{len}
1734} 1805}
1735 1806
1736sub urxvt::line::r { 1807sub urxvt::line::r {
1737 my ($self) = @_; 1808 my ($self) = @_;
1738 1809
1739 if (@_ > 1) 1810 if (@_ > 1) {
1740 {
1741 $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol}) 1811 $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
1742 for $self->{beg} .. $self->{end}; 1812 for $self->{beg} .. $self->{end};
1743 } 1813 }
1744 1814
1745 if (defined wantarray) { 1815 if (defined wantarray) {
1746 my $rend = [ 1816 my $rend = [
1747 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end} 1817 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
1748 ]; 1818 ];
1810Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most 1880Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most
1811recent grab. 1881recent grab.
1812 1882
1813=item $term->ungrab 1883=item $term->ungrab
1814 1884
1815Calls XUngrab for the most recent grab. Is called automatically on 1885Calls XUngrabPointer and XUngrabKeyboard for the most recent grab. Is called automatically on
1816evaluation errors, as it is better to lose the grab in the error case as 1886evaluation errors, as it is better to lose the grab in the error case as
1817the session. 1887the session.
1818 1888
1819=item $atom = $term->XInternAtom ($atom_name[, $only_if_exists]) 1889=item $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
1820 1890
1822 1892
1823=item @atoms = $term->XListProperties ($window) 1893=item @atoms = $term->XListProperties ($window)
1824 1894
1825=item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property) 1895=item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
1826 1896
1827=item $term->XChangeWindowProperty ($window, $property, $type, $format, $octets) 1897=item $term->XChangeProperty ($window, $property, $type, $format, $octets)
1828 1898
1829=item $term->XDeleteProperty ($window, $property) 1899=item $term->XDeleteProperty ($window, $property)
1830 1900
1831=item $window = $term->DefaultRootWindow 1901=item $window = $term->DefaultRootWindow
1832 1902
1839=item $term->XMoveResizeWindow ($window, $x, $y, $width, $height) 1909=item $term->XMoveResizeWindow ($window, $x, $y, $width, $height)
1840 1910
1841=item ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x, $y) 1911=item ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x, $y)
1842 1912
1843=item $term->XChangeInput ($window, $add_events[, $del_events]) 1913=item $term->XChangeInput ($window, $add_events[, $del_events])
1914
1915=item $keysym = $term->XStringToKeysym ($string)
1916
1917=item $string = $term->XKeysymToString ($keysym)
1844 1918
1845Various X or X-related functions. The C<$term> object only serves as 1919Various X or X-related functions. The C<$term> object only serves as
1846the source of the display, otherwise those functions map more-or-less 1920the source of the display, otherwise those functions map more-or-less
1847directory onto the X functions of the same name. 1921directly onto the X functions of the same name.
1848 1922
1849=back 1923=back
1850 1924
1851=cut 1925=cut
1852 1926
1954 my $env = $self->{term}->env; 2028 my $env = $self->{term}->env;
1955 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE. 2029 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
1956 delete $env->{LC_ALL}; 2030 delete $env->{LC_ALL};
1957 $env->{LC_CTYPE} = $self->{term}->locale; 2031 $env->{LC_CTYPE} = $self->{term}->locale;
1958 2032
1959 urxvt::term->new ($env, "popup", 2033 my $term = urxvt::term->new (
2034 $env, "popup",
1960 "--perl-lib" => "", "--perl-ext-common" => "", 2035 "--perl-lib" => "", "--perl-ext-common" => "",
1961 "-pty-fd" => -1, "-sl" => 0, 2036 "-pty-fd" => -1, "-sl" => 0,
1962 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect", 2037 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect",
1963 "--transient-for" => $self->{term}->parent, 2038 "--transient-for" => $self->{term}->parent,
1964 "-display" => $self->{term}->display_id, 2039 "-display" => $self->{term}->display_id,
1965 "-pe" => "urxvt-popup") 2040 "-pe" => "urxvt-popup",
1966 or die "unable to create popup window\n"; 2041 ) or die "unable to create popup window\n";
2042
2043 unless (delete $term->{urxvt_popup_init_done}) {
2044 $term->ungrab;
2045 $term->destroy;
2046 die "unable to initialise popup window\n";
2047 }
1967} 2048}
1968 2049
1969sub DESTROY { 2050sub DESTROY {
1970 my ($self) = @_; 2051 my ($self) = @_;
1971 2052
2002 2083
2003=item $timer = $timer->cb (sub { my ($timer) = @_; ... }) 2084=item $timer = $timer->cb (sub { my ($timer) = @_; ... })
2004 2085
2005Set the callback to be called when the timer triggers. 2086Set the callback to be called when the timer triggers.
2006 2087
2007=item $tstamp = $timer->at
2008
2009Return the time this watcher will fire next.
2010
2011=item $timer = $timer->set ($tstamp) 2088=item $timer = $timer->set ($tstamp[, $interval])
2012 2089
2013Set the time the event is generated to $tstamp. 2090Set the time the event is generated to $tstamp (and optionally specifies a
2091new $interval).
2014 2092
2015=item $timer = $timer->interval ($interval) 2093=item $timer = $timer->interval ($interval)
2016 2094
2017Normally (and when C<$interval> is C<0>), the timer will automatically 2095By default (and when C<$interval> is C<0>), the timer will automatically
2018stop after it has fired once. If C<$interval> is non-zero, then the timer 2096stop after it has fired once. If C<$interval> is non-zero, then the timer
2019is automatically rescheduled at the given intervals. 2097is automatically rescheduled at the given intervals.
2020 2098
2021=item $timer = $timer->start 2099=item $timer = $timer->start
2022 2100
2023Start the timer. 2101Start the timer.
2024 2102
2025=item $timer = $timer->start ($tstamp) 2103=item $timer = $timer->start ($tstamp[, $interval])
2026 2104
2027Set the event trigger time to C<$tstamp> and start the timer. 2105Set the event trigger time to C<$tstamp> and start the timer. Optionally
2106also replaces the interval.
2028 2107
2029=item $timer = $timer->after ($delay) 2108=item $timer = $timer->after ($delay[, $interval])
2030 2109
2031Like C<start>, but sets the expiry timer to c<urxvt::NOW + $delay>. 2110Like C<start>, but sets the expiry timer to c<urxvt::NOW + $delay>.
2032 2111
2033=item $timer = $timer->stop 2112=item $timer = $timer->stop
2034 2113
2165 2244
2166=back 2245=back
2167 2246
2168=head1 AUTHOR 2247=head1 AUTHOR
2169 2248
2170 Marc Lehmann <pcg@goof.com> 2249 Marc Lehmann <schmorp@schmorp.de>
2171 http://software.schmorp.de/pkg/rxvt-unicode 2250 http://software.schmorp.de/pkg/rxvt-unicode
2172 2251
2173=cut 2252=cut
2174 2253
21751 22541

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines