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.133 by root, Mon Feb 6 06:14:08 2006 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
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 "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"
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 36A number of extensions are delivered with this release. You can find them
34find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>. 37in F<< <libdir>/urxvt/perl/ >>, and the documentation can be viewed using
38F<< man urxvt-<EXTENSIONNAME> >>.
35 39
36You can activate them like this: 40You can activate them like this:
37 41
38 @@RXVT_NAME@@ -pe <extensionname> 42 urxvt -pe <extensionname>
39 43
40Or by adding them to the resource for extensions loaded by default: 44Or by adding them to the resource for extensions loaded by default:
41 45
42 URxvt.perl-ext-common: default,automove-background,selection-autotransform 46 URxvt.perl-ext-common: default,selection-autotransform
43 47
44=over 4 48Extensions may add additional resources and C<actions>, i.e., methods
45 49which can be bound to a key and invoked by the user. An extension can
46=item selection (enabled by default) 50define the resources it support and also default bindings for one or
47 51more actions it provides using so called META comments, described
48(More) intelligent selection. This extension tries to be more intelligent 52below. Similarly to builtin resources, extension resources can also be
49when the user extends selections (double-click and further clicks). Right 53specified on the command line as long options (with C<.> replaced by
50now, it tries to select words, urls and complete shell-quoted 54C<->), in which case the corresponding extension is loaded
51arguments, which is very convenient, too, if your F<ls> supports 55automatically. For this to work the extension B<must> define META
52C<--quoting-style=shell>. 56comments for its resources.
53
54A double-click usually selects the word under the cursor, further clicks
55will enlarge the selection.
56
57The selection works by trying to match a number of regexes and displaying
58them in increasing order of length. You can add your own regexes by
59specifying resources of the form:
60
61 URxvt.selection.pattern-0: perl-regex
62 URxvt.selection.pattern-1: perl-regex
63 ...
64
65The 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
67the match. For example, the followign adds a regex that matches everything
68between two vertical bars:
69
70 URxvt.selection.pattern-0: \\|([^|]+)\\|
71
72Another example: Programs I use often output "absolute path: " at the
73beginning of a line when they process multiple files. The following
74pattern matches the filename (note, there is a single space at the very
75end):
76
77 URxvt.selection.pattern-0: ^(/[^:]+):\
78
79You can look at the source of the selection extension to see more
80interesting uses, such as parsing a line from beginning to end.
81
82This extension also offers following bindable keyboard commands:
83
84=over 4
85
86=item rot13
87
88Rot-13 the selection when activated. Used via keyboard trigger:
89
90 URxvt.keysym.C-M-r: perl:selection:rot13
91
92=back
93
94=item option-popup (enabled by default)
95
96Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at
97runtime.
98
99Other extensions can extend this popup menu by pushing a code reference
100onto C<@{ $term->{option_popup_hook} }>, which gets called whenever the
101popup is being displayed.
102
103It's sole argument is the popup menu, which can be modified. It should
104either return nothing or a string, the initial boolean value and a code
105reference. The string will be used as button text and the code reference
106will be called when the toggle changes, with the new boolean value as
107first argument.
108
109The following will add an entry C<myoption> that changes
110C<$self->{myoption}>:
111
112 push @{ $self->{term}{option_popup_hook} }, sub {
113 ("my option" => $myoption, sub { $self->{myoption} = $_[0] })
114 };
115
116=item selection-popup (enabled by default)
117
118Binds a popup menu to Ctrl-Button3 that lets you convert the selection
119text into various other formats/action (such as uri unescaping, perl
120evaluation, web-browser starting etc.), depending on content.
121
122Other extensions can extend this popup menu by pushing a code reference
123onto C<@{ $term->{selection_popup_hook} }>, which gets called whenever the
124popup is being displayed.
125
126It's sole argument is the popup menu, which can be modified. The selection
127is in C<$_>, which can be used to decide wether to add something or not.
128It should either return nothing or a string and a code reference. The
129string will be used as button text and the code reference will be called
130when the button gets activated and should transform C<$_>.
131
132The following will add an entry C<a to b> that transforms all C<a>s in
133the selection to C<b>s, but only if the selection currently contains any
134C<a>s:
135
136 push @{ $self->{term}{selection_popup_hook} }, sub {
137 /a/ ? ("a to be" => sub { s/a/b/g }
138 : ()
139 };
140
141=item searchable-scrollback<hotkey> (enabled by default)
142
143Adds regex search functionality to the scrollback buffer, triggered
144by a hotkey (default: C<M-s>). While in search mode, normal terminal
145input/output is suspended and a regex is displayed at the bottom of the
146screen.
147
148Inputting characters appends them to the regex and continues incremental
149search. C<BackSpace> removes a character from the regex, C<Up> and C<Down>
150search upwards/downwards in the scrollback buffer, C<End> jumps to the
151bottom. C<Escape> leaves search mode and returns to the point where search
152was started, while C<Enter> or C<Return> stay at the current position and
153additionally stores the first match in the current line into the primary
154selection.
155
156=item readline (enabled by default)
157
158A support package that tries to make editing with readline easier. At the
159moment, it reacts to clicking with the left mouse button by trying to
160move the text cursor to this position. It does so by generating as many
161cursor-left or cursor-right keypresses as required (the this only works
162for programs that correctly support wide characters).
163
164To avoid too many false positives, this is only done when:
165
166=over 4
167
168=item - the tty is in ICANON state.
169
170=item - the text cursor is visible.
171
172=item - the primary screen is currently being displayed.
173
174=item - the mouse is on the same (multi-row-) line as the text cursor.
175
176=back
177
178The normal selection mechanism isn't disabled, so quick successive clicks
179might interfere with selection creation in harmless ways.
180
181=item selection-autotransform
182
183This selection allows you to do automatic transforms on a selection
184whenever a selection is made.
185
186It works by specifying perl snippets (most useful is a single C<s///>
187operator) that modify C<$_> as resources:
188
189 URxvt.selection-autotransform.0: transform
190 URxvt.selection-autotransform.1: transform
191 ...
192
193For example, the following will transform selections of the form
194C<filename:number>, often seen in compiler messages, into C<vi +$filename
195$word>:
196
197 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
198
199And this example matches the same,but replaces it with vi-commands you can
200paste directly into your (vi :) editor:
201
202 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/
203
204Of course, this can be modified to suit your needs and your editor :)
205
206To expand the example above to typical perl error messages ("XXX at
207FILENAME line YYY."), you need a slightly more elaborate solution:
208
209 URxvt.selection.pattern-0: ( at .*? line \\d+[,.])
210 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/
211
212The first line tells the selection code to treat the unchanging part of
213every error message as a selection pattern, and the second line transforms
214the message into vi commands to load the file.
215
216=item tabbed
217
218This transforms the terminal into a tabbar with additional terminals, that
219is, it implements what is commonly refered to as "tabbed terminal". The topmost line
220displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one
221button per tab.
222
223Clicking a button will activate that tab. Pressing B<Shift-Left> and
224B<Shift-Right> will switch to the tab left or right of the current one,
225while B<Shift-Down> creates a new tab.
226
227The tabbar itself can be configured similarly to a normal terminal, but
228with a resource class of C<URxvt.tabbed>. In addition, it supports the
229following four resources (shown with defaults):
230
231 URxvt.tabbed.tabbar-fg: <colour-index, default 3>
232 URxvt.tabbed.tabbar-bg: <colour-index, default 0>
233 URxvt.tabbed.tab-fg: <colour-index, default 0>
234 URxvt.tabbed.tab-bg: <colour-index, default 1>
235
236See I<COLOR AND GRAPHICS> in the @@RXVT_NAME@@(1) manpage for valid
237indices.
238
239=item mark-urls
240
241Uses per-line display filtering (C<on_line_update>) to underline urls and
242make them clickable. When middle-clicked, the program specified in the
243resource C<urlLauncher> (default C<x-www-browser>) will be started with
244the URL as first argument.
245
246=item xim-onthespot
247
248This (experimental) perl extension implements OnTheSpot editing. It does
249not work perfectly, and some input methods don't seem to work well with
250OnTheSpot editing in general, but it seems to work at leats for SCIM and
251kinput2.
252
253You enable it by specifying this extension and a preedit style of
254C<OnTheSpot>, i.e.:
255
256 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot
257
258=item automove-background
259
260This is basically a one-line extension that dynamically changes the background pixmap offset
261to the window position, in effect creating the same effect as pseudo transparency with
262a custom pixmap. No scaling is supported in this mode. Exmaple:
263
264 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background
265
266=item block-graphics-to-ascii
267
268A not very useful example of filtering all text output to the terminal,
269by replacing all line-drawing characters (U+2500 .. U+259F) by a
270similar-looking ascii character.
271
272=item digital-clock
273
274Displays a digital clock using the built-in overlay.
275
276=item remote-clipboard
277
278Somewhat of a misnomer, this extension adds two menu entries to the
279selection popup that allows one ti run external commands to store the
280selection somewhere and fetch it again.
281
282We use it to implement a "distributed selection mechanism", which just
283means that one command uploads the file to a remote server, and another
284reads it.
285
286The commands can be set using the C<URxvt.remote-selection.store> and
287C<URxvt.remote-selection.fetch> resources. The first should read the
288selection to store from STDIN (always in UTF-8), the second should provide
289the selection data on STDOUT (also in UTF-8).
290
291The defaults (which are likely useless to you) use rsh and cat:
292
293 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
294 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
295
296=item selection-pastebin
297
298This is a little rarely useful extension that Uploads the selection as
299textfile to a remote site (or does other things). (The implementation is
300not currently secure for use in a multiuser environment as it writes to
301F</tmp> directly.).
302
303It listens to the C<selection-pastebin:remote-pastebin> keyboard command,
304i.e.
305
306 URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin
307
308Pressing this combination runs a command with C<%> replaced by the name of
309the textfile. This command can be set via a resource:
310
311 URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
312
313And the default is likely not useful to anybody but the few people around
314here :)
315
316The name of the textfile is the hex encoded md5 sum of the selection, so
317the same content should lead to the same filename.
318
319After a successful upload the selection will be replaced by the text given
320in the C<selection-pastebin-url> resource (again, the % is the placeholder
321for the filename):
322
323 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
324
325=item example-refresh-hooks
326
327Displays a very simple digital clock in the upper right corner of the
328window. Illustrates overwriting the refresh callbacks to create your own
329overlays or changes.
330
331=back
332 57
333=head1 API DOCUMENTATION 58=head1 API DOCUMENTATION
334 59
335=head2 General API Considerations 60=head2 General API Considerations
336 61
350 75
351=over 4 76=over 4
352 77
353=item $text 78=item $text
354 79
355Rxvt-unicodes special way of encoding text, where one "unicode" character 80Rxvt-unicode's special way of encoding text, where one "unicode" character
356always 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.
357 82
358=item $string 83=item $string
359 84
360A 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
364=item $octets 89=item $octets
365 90
366Either binary data or - more common - a text string encoded in a 91Either binary data or - more common - a text string encoded in a
367locale-specific way. 92locale-specific way.
368 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
369=back 100=back
370 101
371=head2 Extension Objects 102=head2 Extension Objects
372 103
373Very 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
374for each terminal and each extension and passed as the first parameter to 105for each terminal, and each terminal has its own set of extension objects,
375hooks. So extensions can use their C<$self> object without having to think 106which are passed as the first parameter to hooks. So extensions can use
376about other extensions, with the exception of methods and members that 107their C<$self> object without having to think about clashes with other
108extensions or other terminals, with the exception of methods and members
377begin with an underscore character C<_>: these are reserved for internal 109that begin with an underscore character C<_>: these are reserved for
378use. 110internal use.
379 111
380Although 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
381C<urxvt::term> class on this object. 113C<urxvt::term> class on this object.
382 114
383It 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:
384 124
385=over 4 125=over 4
386 126
387=item $urxvt_term = $self->{term} 127=item #:META:RESOURCE:name:type:desc
388 128
389Returns the C<urxvt::term> object associated with this instance of the 129The RESOURCE comment defines a resource used by the extension, where
390extension. This member I<must not> be changed in any way. 130C<name> is the resource name, C<type> is the resource type, C<boolean>
391 131or C<string>, and C<desc> is the resource description.
392=item $self->enable ($hook_name => $cb, [$hook_name => $cb..])
393
394Dynamically enable the given hooks (named without the C<on_> prefix) for
395this extension, replacing any previous hook. This is useful when you want
396to overwrite time-critical hooks only temporarily.
397
398=item $self->disable ($hook_name[, $hook_name..])
399
400Dynamically disable the given hooks.
401 132
402=back 133=back
403 134
404=head2 Hooks 135=head2 Hooks
405 136
406The following subroutines can be declared in extension files, and will be 137The following subroutines can be declared in extension files, and will be
407called whenever the relevant event happens. 138called whenever the relevant event happens.
408 139
409The first argument passed to them is an extension oject as described in 140The first argument passed to them is an extension object as described in
410the in the C<Extension Objects> section. 141the in the C<Extension Objects> section.
411 142
412B<All> of these hooks must return a boolean value. If any of the called 143B<All> of these hooks must return a boolean value. If any of the called
413hooks returns true, then the event counts as being I<consumed>, and the 144hooks returns true, then the event counts as being I<consumed>, and the
414relevant action might not be carried out by the C++ code. 145relevant action might not be carried out by the C++ code.
427place. 158place.
428 159
429=item on_start $term 160=item on_start $term
430 161
431Called at the very end of initialisation of a new terminal, just before 162Called at the very end of initialisation of a new terminal, just before
432trying to map (display) the toplevel and returning to the mainloop. 163trying to map (display) the toplevel and returning to the main loop.
433 164
434=item on_destroy $term 165=item on_destroy $term
435 166
436Called whenever something tries to destroy terminal, when the terminal is 167Called whenever something tries to destroy terminal, when the terminal is
437still fully functional (not for long, though). 168still fully functional (not for long, though).
464 195
465Called whenever a selection has been copied, but before the selection is 196Called whenever a selection has been copied, but before the selection is
466requested from the server. The selection text can be queried and changed 197requested from the server. The selection text can be queried and changed
467by calling C<< $term->selection >>. 198by calling C<< $term->selection >>.
468 199
469Returning a true value aborts selection grabbing. It will still be hilighted. 200Returning a true value aborts selection grabbing. It will still be highlighted.
470 201
471=item on_sel_extend $term 202=item on_sel_extend $term
472 203
473Called whenever the user tries to extend the selection (e.g. with a double 204Called whenever the user tries to extend the selection (e.g. with a double
474click) and is either supposed to return false (normal operation), or 205click) and is either supposed to return false (normal operation), or
475should extend the selection itelf and return true to suppress the built-in 206should extend the selection itself and return true to suppress the built-in
476processing. This can happen multiple times, as long as the callback 207processing. This can happen multiple times, as long as the callback
477returns true, it will be called on every further click by the user and is 208returns true, it will be called on every further click by the user and is
478supposed to enlarge the selection more and more, if possible. 209supposed to enlarge the selection more and more, if possible.
479 210
480See the F<selection> example extension. 211See the F<selection> example extension.
481 212
482=item on_view_change $term, $offset 213=item on_view_change $term, $offset
483 214
484Called whenever the view offset changes, i..e the user or program 215Called whenever the view offset changes, i.e. the user or program
485scrolls. Offset C<0> means display the normal terminal, positive values 216scrolls. Offset C<0> means display the normal terminal, positive values
486show this many lines of scrollback. 217show this many lines of scrollback.
487 218
488=item on_scroll_back $term, $lines, $saved 219=item on_scroll_back $term, $lines, $saved
489 220
493 224
494It 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,
495$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
496number of lines that will be in the scrollback buffer. 227number of lines that will be in the scrollback buffer.
497 228
498=item on_osc_seq $term, $string 229=item on_osc_seq $term, $op, $args, $resp
230
231Called on every OSC sequence and can be used to suppress it or modify its
232behaviour. The default should be to return an empty list. A true value
233suppresses execution of the request completely. Make sure you don't get
234confused by recursive invocations when you output an OSC sequence within
235this callback.
236
237C<on_osc_seq_perl> should be used for new behaviour.
238
239=item on_osc_seq_perl $term, $args, $resp
499 240
500Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 241Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
501operating system command) is processed. Cursor position and other state 242operating system command) is processed. Cursor position and other state
502information is up-to-date when this happens. For interoperability, the 243information is up-to-date when this happens. For interoperability, the
503string should start with the extension name and a colon, to distinguish 244string should start with the extension name (sans -osc) and a semicolon,
504it from commands for other extensions, and this might be enforced in the 245to distinguish it from commands for other extensions, and this might be
505future. 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 }
506 257
507Be 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,
508as its source can not easily be controleld (e-mail content, messages from 259as its source can not easily be controlled (e-mail content, messages from
509other 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.
510 264
511=item on_add_lines $term, $string 265=item on_add_lines $term, $string
512 266
513Called 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
514can 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
519=item on_tt_write $term, $octets 273=item on_tt_write $term, $octets
520 274
521Called 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
522suppress or filter tty input. 276suppress or filter tty input.
523 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
524=item on_line_update $term, $row 285=item on_line_update $term, $row
525 286
526Called 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
527screen output (e.g. underline urls or other useless stuff). Only lines 288screen output (e.g. underline urls or other useless stuff). Only lines
528that are being shown will be filtered, and, due to performance reasons, 289that are being shown will be filtered, and, due to performance reasons,
535later 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
536you cannot just toggle rendition bits, but only set them. 297you cannot just toggle rendition bits, but only set them.
537 298
538=item on_refresh_begin $term 299=item on_refresh_begin $term
539 300
540Called just before the screen gets redrawn. Can be used for overlay 301Called just before the screen gets redrawn. Can be used for overlay or
541or similar effects by modify terminal contents in refresh_begin, and 302similar effects by modifying the terminal contents in refresh_begin, and
542restoring them in refresh_end. The built-in overlay and selection display 303restoring them in refresh_end. The built-in overlay and selection display
543code is run after this hook, and takes precedence. 304code is run after this hook, and takes precedence.
544 305
545=item on_refresh_end $term 306=item on_refresh_end $term
546 307
547Called just after the screen gets redrawn. See C<on_refresh_begin>. 308Called just after the screen gets redrawn. See C<on_refresh_begin>.
548 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
549=item on_user_command $term, $string 318=item on_user_command $term, $string *DEPRECATED*
550 319
551Called whenever the a user-configured event is being activated (e.g. via 320Called whenever a user-configured event is being activated (e.g. via
552a 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>
553resource in the @@RXVT_NAME@@(1) manpage). 322resource in the urxvt(1) manpage).
554 323
555The 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
556slightly in the future. 325preference to the C<on_action> hook.
326
327=item on_resize_all_windows $term, $new_width, $new_height
328
329Called just after the new window size has been calculated, but before
330windows are actually being resized or hints are being set. If this hook
331returns a true value, setting of the window hints is being skipped.
557 332
558=item on_x_event $term, $event 333=item on_x_event $term, $event
559 334
560Called 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
561windows). Should only be used as a last resort. Most event structure 336windows). Should only be used as a last resort. Most event structure
562members are not passed. 337members are not passed.
563 338
339=item on_root_event $term, $event
340
341Like C<on_x_event>, but is called for events on the root window.
342
564=item on_focus_in $term 343=item on_focus_in $term
565 344
566Called whenever the window gets the keyboard focus, before rxvt-unicode 345Called whenever the window gets the keyboard focus, before rxvt-unicode
567does focus in processing. 346does focus in processing.
568 347
569=item on_focus_out $term 348=item on_focus_out $term
570 349
571Called wheneever the window loses keyboard focus, before rxvt-unicode does 350Called whenever the window loses keyboard focus, before rxvt-unicode does
572focus out processing. 351focus out processing.
573 352
574=item on_configure_notify $term, $event 353=item on_configure_notify $term, $event
575 354
576=item on_property_notify $term, $event 355=item on_property_notify $term, $event
587 366
588=item on_map_notify $term, $event 367=item on_map_notify $term, $event
589 368
590=item on_unmap_notify $term, $event 369=item on_unmap_notify $term, $event
591 370
592Called whenever the corresponding X event is received for the terminal If 371Called whenever the corresponding X event is received for the terminal. If
593the 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.
594 373
595The 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
596manpage), 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
597(real, not screen-based) row and column under the mouse cursor. 376(real, not screen-based) row and column under the mouse cursor.
598 377
599C<on_key_press> additionally receives the string rxvt-unicode would 378C<on_key_press> additionally receives the string rxvt-unicode would
600output, if any, in locale-specific encoding. 379output, if any, in locale-specific encoding.
601 380
602subwindow.
603
604=item on_client_message $term, $event 381=item on_client_message $term, $event
605 382
606=item on_wm_protocols $term, $event 383=item on_wm_protocols $term, $event
607 384
608=item on_wm_delete_window $term, $event 385=item on_wm_delete_window $term, $event
609 386
610Called when various types of ClientMessage events are received (all with 387Called when various types of ClientMessage events are received (all with
611format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW). 388format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
612 389
390=item on_bell $term
391
392Called on receipt of a bell character.
393
613=back 394=back
614 395
615=cut 396=cut
616 397
617package urxvt; 398package urxvt;
618 399
619use utf8; 400use utf8;
620use strict; 401use strict 'vars';
621use Carp (); 402use Carp ();
622use Scalar::Util (); 403use Scalar::Util ();
623use List::Util (); 404use List::Util ();
624 405
625our $VERSION = 1; 406our $VERSION = 1;
626our $TERM; 407our $TERM;
627our @TERM_INIT; 408our @TERM_INIT; # should go, prevents async I/O etc.
628our @TERM_EXT; 409our @TERM_EXT; # should go, prevents async I/O etc.
629our @HOOKNAME; 410our @HOOKNAME;
630our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME; 411our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
631our %OPTION; 412our %OPTION;
632 413
633our $LIBDIR; 414our $LIBDIR;
659The current terminal. This variable stores the current C<urxvt::term> 440The current terminal. This variable stores the current C<urxvt::term>
660object, whenever a callback/hook is executing. 441object, whenever a callback/hook is executing.
661 442
662=item @urxvt::TERM_INIT 443=item @urxvt::TERM_INIT
663 444
664All coderefs in this array will be called as methods of the next newly 445All code references in this array will be called as methods of the next newly
665created C<urxvt::term> object (during the C<on_init> phase). The array 446created C<urxvt::term> object (during the C<on_init> phase). The array
666gets cleared before the codereferences that were in it are being executed, 447gets cleared before the code references that were in it are being executed,
667so coderefs can push themselves onto it again if they so desire. 448so references can push themselves onto it again if they so desire.
668 449
669This complements to the perl-eval commandline option, but gets executed 450This complements to the perl-eval command line option, but gets executed
670first. 451first.
671 452
672=item @urxvt::TERM_EXT 453=item @urxvt::TERM_EXT
673 454
674Works similar to C<@TERM_INIT>, but contains perl package/class names, which 455Works similar to C<@TERM_INIT>, but contains perl package/class names, which
681 462
682=over 4 463=over 4
683 464
684=item urxvt::fatal $errormessage 465=item urxvt::fatal $errormessage
685 466
686Fatally aborts execution with the given error message. Avoid at all 467Fatally aborts execution with the given error message (which should
687costs! The only time this is acceptable is when the terminal process 468include a trailing newline). Avoid at all costs! The only time this
688starts up. 469is acceptable (and useful) is in the init hook, where it prevents the
470terminal from starting up.
689 471
690=item urxvt::warn $string 472=item urxvt::warn $string
691 473
692Calls 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
693newline. The module also overwrites the C<warn> builtin with a function 475newline. The module also overwrites the C<warn> builtin with a function
694that calls this function. 476that calls this function.
695 477
696Using 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
697correct place, e.g. on stderr of the connecting urxvtc client. 479correct place, e.g. on stderr of the connecting urxvtc client.
699Messages have a size limit of 1023 bytes currently. 481Messages have a size limit of 1023 bytes currently.
700 482
701=item @terms = urxvt::termlist 483=item @terms = urxvt::termlist
702 484
703Returns all urxvt::term objects that exist in this process, regardless of 485Returns all urxvt::term objects that exist in this process, regardless of
704wether they are started, being destroyed etc., so be careful. Only term 486whether they are started, being destroyed etc., so be careful. Only term
705objects that have perl extensions attached will be returned (because there 487objects that have perl extensions attached will be returned (because there
706is no urxvt::term objet associated with others). 488is no urxvt::term object associated with others).
707 489
708=item $time = urxvt::NOW 490=item $time = urxvt::NOW
709 491
710Returns the "current time" (as per the event loop). 492Returns the "current time" (as per the event loop).
711 493
754 536
755=item $rend = urxvt::OVERLAY_RSTYLE 537=item $rend = urxvt::OVERLAY_RSTYLE
756 538
757Return the rendition mask used for overlays by default. 539Return the rendition mask used for overlays by default.
758 540
759=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
760 543
761Return the bit that enabled bold, italic, blink, reverse-video and 544Return the bit that enabled bold, italic, blink, reverse-video and
762underline, respectively. To enable such a style, just logically OR it into 545underline, respectively. To enable such a style, just logically OR it into
763the bitset. 546the bitset.
764 547
801 }; 584 };
802} 585}
803 586
804no warnings 'utf8'; 587no warnings 'utf8';
805 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
806my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 651my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
807 652
808sub verbose { 653sub verbose {
809 my ($level, $msg) = @_; 654 my ($level, $msg) = @_;
810 warn "$msg\n" if $level <= $verbosity; 655 warn "$msg\n" if $level <= $verbosity;
822 $pkg =~ s/[^[:word:]]/_/g; 667 $pkg =~ s/[^[:word:]]/_/g;
823 $pkg = "urxvt::ext::$pkg"; 668 $pkg = "urxvt::ext::$pkg";
824 669
825 verbose 3, "loading extension '$path' into package '$pkg'"; 670 verbose 3, "loading extension '$path' into package '$pkg'";
826 671
672 (${"$pkg\::_NAME"} = $path) =~ s/^.*[\\\/]//; # hackish
673
827 open my $fh, "<:raw", $path 674 open my $fh, "<:raw", $path
828 or die "$path: $!"; 675 or die "$path: $!";
829 676
830 my $source = 677 my $source =
831 "package $pkg; use strict; use utf8; no warnings 'utf8';\n" 678 "package $pkg; use strict 'vars'; use utf8; no warnings 'utf8';\n"
832 . "#line 1 \"$path\"\n{\n" 679 . "#line 1 \"$path\"\n{\n"
833 . (do { local $/; <$fh> }) 680 . (do { local $/; <$fh> })
834 . "\n};\n1"; 681 . "\n};\n1";
835 682
836 eval $source 683 eval $source
845# called by the rxvt core 692# called by the rxvt core
846sub invoke { 693sub invoke {
847 local $TERM = shift; 694 local $TERM = shift;
848 my $htype = shift; 695 my $htype = shift;
849 696
850 if ($htype == 0) { # INIT 697 if ($htype == HOOK_INIT) {
851 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 698 my @dirs = $TERM->perl_libdirs;
852 699
700 $TERM->scan_extensions;
701
853 my %ext_arg; 702 my %ext_arg;
854 703
855 { 704 {
856 my @init = @TERM_INIT; 705 my @init = @TERM_INIT;
857 @TERM_INIT = (); 706 @TERM_INIT = ();
859 my @pkg = @TERM_EXT; 708 my @pkg = @TERM_EXT;
860 @TERM_EXT = (); 709 @TERM_EXT = ();
861 $TERM->register_package ($_) for @pkg; 710 $TERM->register_package ($_) for @pkg;
862 } 711 }
863 712
713 for (
864 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 ) {
865 if ($_ eq "default") { 717 if ($_ eq "default") {
718
719 $ext_arg{$_} = []
866 $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
867 } elsif (/^-(.*)$/) { 731 } elsif (/^-(.*)$/) {
868 delete $ext_arg{$1}; 732 delete $ext_arg{$1};
733
869 } elsif (/^([^<]+)<(.*)>$/) { 734 } elsif (/^([^<]+)<(.*)>$/) {
870 push @{ $ext_arg{$1} }, $2; 735 push @{ $ext_arg{$1} }, $2;
736
871 } else { 737 } else {
872 $ext_arg{$_} ||= []; 738 $ext_arg{$_} ||= [];
873 } 739 }
874 } 740 }
875 741
891 757
892 if (my $cb = $TERM->{_hook}[$htype]) { 758 if (my $cb = $TERM->{_hook}[$htype]) {
893 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")" 759 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
894 if $verbosity >= 10; 760 if $verbosity >= 10;
895 761
896 keys %$cb; 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";
897 768
898 while (my ($pkg, $cb) = each %$cb) { 769 $cb = $cb->{$pkg}
770 or return undef; #TODO: maybe warn user?
771
772 $cb = { $pkg => $cb };
773 }
774
775 for my $pkg (keys %$cb) {
899 my $retval_ = eval { $cb->($TERM->{_pkg}{$pkg}, @_) }; 776 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg} || $TERM, @_) };
900 $retval ||= $retval_; 777 $retval ||= $retval_;
901 778
902 if ($@) { 779 if ($@) {
903 $TERM->ungrab; # better to lose the grab than the session 780 $TERM->ungrab; # better to lose the grab than the session
904 warn $@; 781 warn $@;
907 784
908 verbose 11, "$HOOKNAME[$htype] returning <$retval>" 785 verbose 11, "$HOOKNAME[$htype] returning <$retval>"
909 if $verbosity >= 11; 786 if $verbosity >= 11;
910 } 787 }
911 788
912 if ($htype == 1) { # DESTROY 789 if ($htype == HOOK_DESTROY) {
913 # clear package objects 790 # clear package objects
914 %$_ = () for values %{ $TERM->{_pkg} }; 791 %$_ = () for values %{ $TERM->{_pkg} };
915 792
916 # clear package 793 # clear package
917 %$TERM = (); 794 %$TERM = ();
922 799
923sub SET_COLOR($$$) { 800sub SET_COLOR($$$) {
924 SET_BGCOLOR (SET_FGCOLOR ($_[0], $_[1]), $_[2]) 801 SET_BGCOLOR (SET_FGCOLOR ($_[0], $_[1]), $_[2])
925} 802}
926 803
927# urxvt::term::extension 804sub rend2mask {
805 no strict 'refs';
806 my ($str, $mask) = (@_, 0);
807 my %color = ( fg => undef, bg => undef );
808 my @failed;
809 for my $spec ( split /\s+/, $str ) {
810 if ( $spec =~ /^([fb]g)[_:-]?(\d+)/i ) {
811 $color{lc($1)} = $2;
812 } else {
813 my $neg = $spec =~ s/^[-^]//;
814 unless ( exists &{"RS_$spec"} ) {
815 push @failed, $spec;
816 next;
817 }
818 my $cur = &{"RS_$spec"};
819 if ( $neg ) {
820 $mask &= ~$cur;
821 } else {
822 $mask |= $cur;
823 }
824 }
825 }
826 ($mask, @color{qw(fg bg)}, \@failed)
827}
928 828
929package urxvt::term::extension; 829package urxvt::term::extension;
930 830
931sub enable { 831=head2 The C<urxvt::term::extension> class
932 my ($self, %hook) = @_;
933 my $pkg = $self->{_pkg};
934 832
935 while (my ($name, $cb) = each %hook) { 833Each extension attached to a terminal object is represented by
936 my $htype = $HOOKTYPE{uc $name}; 834a C<urxvt::term::extension> object.
937 defined $htype
938 or Carp::croak "unsupported hook type '$name'";
939 835
940 $self->set_should_invoke ($htype, +1) 836You can use these objects, which are passed to all callbacks to store any
941 unless exists $self->{term}{_hook}[$htype]{$pkg}; 837state related to the terminal and extension instance.
942 838
943 $self->{term}{_hook}[$htype]{$pkg} = $cb; 839The methods (And data members) documented below can be called on extension
944 } 840objects, in addition to call methods documented for the <urxvt::term>
945} 841class.
946 842
947sub disable { 843=over 4
948 my ($self, @hook) = @_;
949 my $pkg = $self->{_pkg};
950 844
951 for my $name (@hook) { 845=item $urxvt_term = $self->{term}
952 my $htype = $HOOKTYPE{uc $name};
953 defined $htype
954 or Carp::croak "unsupported hook type '$name'";
955 846
956 $self->set_should_invoke ($htype, -1) 847Returns the C<urxvt::term> object associated with this instance of the
957 if delete $self->{term}{_hook}[$htype]{$pkg}; 848extension. This member I<must not> be changed in any way.
958 } 849
959} 850=cut
960 851
961our $AUTOLOAD; 852our $AUTOLOAD;
962 853
963sub AUTOLOAD { 854sub AUTOLOAD {
964 $AUTOLOAD =~ /:([^:]+)$/ 855 $AUTOLOAD =~ /:([^:]+)$/
977 868
978sub DESTROY { 869sub DESTROY {
979 # nop 870 # nop
980} 871}
981 872
982# urxvt::destroy_hook 873# urxvt::destroy_hook (basically a cheap Guard:: implementation)
983 874
984sub urxvt::destroy_hook::DESTROY { 875sub urxvt::destroy_hook::DESTROY {
985 ${$_[0]}->(); 876 ${$_[0]}->();
986} 877}
987 878
988sub urxvt::destroy_hook(&) { 879sub urxvt::destroy_hook(&) {
989 bless \shift, urxvt::destroy_hook:: 880 bless \shift, urxvt::destroy_hook::
990} 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
991 1005
992package urxvt::anyevent; 1006package urxvt::anyevent;
993 1007
994=head2 The C<urxvt::anyevent> Class 1008=head2 The C<urxvt::anyevent> Class
995 1009
996The 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
997C<AnyEvent> module - any module using it will work inside urxvt without 1011C<AnyEvent> module - any module using it will work inside urxvt without
998further programming. The only exception is that you cannot wait on 1012further programming. The only exception is that you cannot wait on
999condition variables, but non-blocking condvar use is ok. What this means 1013condition variables, but non-blocking condvar use is ok.
1000is that you cannot use blocking APIs, but the non-blocking variant should
1001work.
1002 1014
1003=cut 1015In practical terms this means is that you cannot use blocking APIs, but
1016the non-blocking variant should work.
1004 1017
1018=cut
1019
1005our $VERSION = 1; 1020our $VERSION = '5.23';
1006 1021
1007$INC{"urxvt/anyevent.pm"} = 1; # mark us as there 1022$INC{"urxvt/anyevent.pm"} = 1; # mark us as there
1008push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::]; 1023push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
1009 1024
1010sub timer { 1025sub timer {
1012 1027
1013 my $cb = $arg{cb}; 1028 my $cb = $arg{cb};
1014 1029
1015 urxvt::timer 1030 urxvt::timer
1016 ->new 1031 ->new
1017 ->start (urxvt::NOW + $arg{after}) 1032 ->after ($arg{after}, $arg{interval})
1018 ->cb (sub { 1033 ->cb ($arg{interval} ? $cb : sub {
1019 $_[0]->stop; # need to cancel manually 1034 $_[0]->stop; # need to cancel manually
1020 $cb->(); 1035 $cb->();
1021 }) 1036 })
1022} 1037}
1023 1038
1024sub io { 1039sub io {
1025 my ($class, %arg) = @_; 1040 my ($class, %arg) = @_;
1026 1041
1027 my $cb = $arg{cb}; 1042 my $cb = $arg{cb};
1043 my $fd = fileno $arg{fh};
1044 defined $fd or $fd = $arg{fh};
1028 1045
1029 bless [$arg{fh}, urxvt::iow 1046 bless [$arg{fh}, urxvt::iow
1030 ->new 1047 ->new
1031 ->fd (fileno $arg{fh}) 1048 ->fd ($fd)
1032 ->events (($arg{poll} =~ /r/ ? 1 : 0) 1049 ->events (($arg{poll} =~ /r/ ? 1 : 0)
1033 | ($arg{poll} =~ /w/ ? 2 : 0)) 1050 | ($arg{poll} =~ /w/ ? 2 : 0))
1034 ->start 1051 ->start
1035 ->cb (sub { 1052 ->cb ($cb)
1036 $cb->(($_[1] & 1 ? 'r' : '')
1037 . ($_[1] & 2 ? 'w' : ''));
1038 })],
1039 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 })
1040} 1079}
1041 1080
1042sub DESTROY { 1081sub DESTROY {
1043 $_[0][1]->stop; 1082 $_[0][1]->stop;
1044} 1083}
1045 1084
1046sub condvar { 1085# only needed for AnyEvent < 6 compatibility
1047 bless \my $flag, urxvt::anyevent::condvar:: 1086sub one_event {
1048}
1049
1050sub urxvt::anyevent::condvar::broadcast {
1051 ${$_[0]}++;
1052}
1053
1054sub urxvt::anyevent::condvar::wait {
1055 unless (${$_[0]}) {
1056 Carp::croak "AnyEvent->condvar 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";
1057 }
1058} 1088}
1059 1089
1060package urxvt::term; 1090package urxvt::term;
1061 1091
1062=head2 The C<urxvt::term> Class 1092=head2 The C<urxvt::term> Class
1075 urxvt::verbose 6, "register package $pkg to $self"; 1105 urxvt::verbose 6, "register package $pkg to $self";
1076 1106
1077 @{"$pkg\::ISA"} = urxvt::term::extension::; 1107 @{"$pkg\::ISA"} = urxvt::term::extension::;
1078 1108
1079 my $proxy = bless { 1109 my $proxy = bless {
1080 _pkg => $pkg, 1110 _pkg => $pkg,
1111 _name => ${"$pkg\::_NAME"}, # hackish
1081 argv => $argv, 1112 argv => $argv,
1082 }, $pkg; 1113 }, $pkg;
1083 Scalar::Util::weaken ($proxy->{term} = $self); 1114 Scalar::Util::weaken ($proxy->{term} = $self);
1084 1115
1085 $self->{_pkg}{$pkg} = $proxy; 1116 $self->{_pkg}{$pkg} = $proxy;
1086 1117
1089 $proxy->enable ($name => $ref); 1120 $proxy->enable ($name => $ref);
1090 } 1121 }
1091 } 1122 }
1092} 1123}
1093 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
1094=item $term = new urxvt::term $envhashref, $rxvtname, [arg...] 1184=item $term = new urxvt::term $envhashref, $rxvtname, [arg...]
1095 1185
1096Creates 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
1097C<$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
1098hash which defines the environment of the new terminal. 1188hash which defines the environment of the new terminal.
1115} 1205}
1116 1206
1117=item $term->destroy 1207=item $term->destroy
1118 1208
1119Destroy the terminal object (close the window, free resources 1209Destroy the terminal object (close the window, free resources
1120etc.). 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
1121watchers (timers, io watchers) are still active. 1211watchers (timers, io watchers) are still active.
1122 1212
1123=item $term->exec_async ($cmd[, @args]) 1213=item $term->exec_async ($cmd[, @args])
1124 1214
1125Works 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
1149 1239
1150Returns true if the option specified by C<$optval> is enabled, and 1240Returns true if the option specified by C<$optval> is enabled, and
1151optionally change it. All option values are stored by name in the hash 1241optionally change it. All option values are stored by name in the hash
1152C<%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.
1153 1243
1154Here is a a likely non-exhaustive list of option names, please see the 1244Here is a likely non-exhaustive list of option names, please see the
1155source file F</src/optinc.h> to see the actual list: 1245source file F</src/optinc.h> to see the actual list:
1156 1246
1157 borderLess console cursorBlink cursorUnderline hold iconic insecure 1247 borderLess buffered console cursorBlink cursorUnderline hold iconic
1158 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 1248 insecure intensityStyles iso14755 iso14755_52 jumpScroll loginShell
1159 override-redirect pastableTabs pointerBlank reverseVideo scrollBar 1249 mapAlert meta8 mouseWheelScrollPage override_redirect pastableTabs
1160 scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput 1250 pointerBlank reverseVideo scrollBar scrollBar_floating scrollBar_right
1161 scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs 1251 scrollTtyKeypress scrollTtyOutput scrollWithBuffer secondaryScreen
1162 transparent tripleclickwords utmpInhibit visualBell 1252 secondaryScroll skipBuiltinGlyphs skipScroll transparent tripleclickwords
1253 urgentOnBell utmpInhibit visualBell
1163 1254
1164=item $value = $term->resource ($name[, $newval]) 1255=item $value = $term->resource ($name[, $newval])
1165 1256
1166Returns the current resource value associated with a given name and 1257Returns the current resource value associated with a given name and
1167optionally 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>
1176likely change). 1267likely change).
1177 1268
1178Please note that resource strings will currently only be freed when the 1269Please note that resource strings will currently only be freed when the
1179terminal is destroyed, so changing options frequently will eat memory. 1270terminal is destroyed, so changing options frequently will eat memory.
1180 1271
1181Here is a 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
1182are 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>
1183to see the actual list: 1274to see the actual list:
1184 1275
1185 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1276 answerbackstring backgroundPixmap backspace_key blurradius
1186 borderLess color cursorBlink cursorUnderline cutchars delete_key 1277 boldFont boldItalicFont borderLess buffered chdir color cursorBlink
1187 display_name embed ext_bwidth fade font geometry hold iconName 1278 cursorUnderline cutchars delete_key depth display_name embed ext_bwidth
1188 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
1189 italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier 1281 jumpScroll letterSpace lineSpace loginShell mapAlert meta8 modifier
1190 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval 1282 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
1191 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay 1283 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
1192 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar 1284 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
1193 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness 1285 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
1194 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle 1286 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
1195 secondaryScreen secondaryScroll selectstyle shade term_name title 1287 secondaryScreen secondaryScroll shade skipBuiltinGlyphs skipScroll
1196 transient_for transparent transparent_all tripleclickwords utmpInhibit 1288 term_name title transient_for transparent tripleclickwords urgentOnBell
1197 visualBell 1289 utmpInhibit visualBell
1198 1290
1199=cut 1291=cut
1200 1292
1201sub resource($$;$) { 1293sub resource($$;$) {
1202 my ($self, $name) = (shift, shift); 1294 my ($self, $name) = (shift, shift);
1203 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 1295 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
1204 &urxvt::term::_resource 1296 goto &urxvt::term::_resource
1205} 1297}
1206 1298
1207=item $value = $term->x_resource ($pattern) 1299=item $value = $term->x_resource ($pattern)
1208 1300
1209Returns the X-Resource for the given pattern, excluding the program or 1301Returns the X-Resource for the given pattern, excluding the program or
1210class name, i.e. C<< $term->x_resource ("boldFont") >> should return the 1302class name, i.e. C<< $term->x_resource ("boldFont") >> should return the
1211same 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
1212resource with that pattern exists. 1304resource with that pattern exists.
1213 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
1214This 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
1215only one resource database per display, and later invocations might return 1317only one resource database per display, and later invocations might return
1216the wrong resources. 1318the wrong resources.
1217 1319
1218=item $success = $term->parse_keysym ($keysym_spec, $command_string) 1320=item $value = $term->x_resource_boolean ($pattern)
1219 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
1220Adds 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
1221C<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 }
1222 1355
1223=item $rend = $term->rstyle ([$new_rstyle]) 1356=item $rend = $term->rstyle ([$new_rstyle])
1224 1357
1225Return and optionally change the current rendition. Text that is output by 1358Return and optionally change the current rendition. Text that is output by
1226the terminal application will use this style. 1359the terminal application will use this style.
1234 1367
1235=item ($row, $col) = $term->selection_beg ([$row, $col]) 1368=item ($row, $col) = $term->selection_beg ([$row, $col])
1236 1369
1237=item ($row, $col) = $term->selection_end ([$row, $col]) 1370=item ($row, $col) = $term->selection_end ([$row, $col])
1238 1371
1239Return the current values of the selection mark, begin or end positions, 1372Return the current values of the selection mark, begin or end positions.
1240and 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.
1241 1381
1242=item $term->selection_make ($eventtime[, $rectangular]) 1382=item $term->selection_make ($eventtime[, $rectangular])
1243 1383
1244Tries to make a selection as set by C<selection_beg> and 1384Tries to make a selection as set by C<selection_beg> and
1245C<selection_end>. If C<$rectangular> is true (default: false), a 1385C<selection_end>. If C<$rectangular> is true (default: false), a
1246rectangular selection will be made. This is the prefered function to make 1386rectangular selection will be made. This is the preferred function to make
1247a selection. 1387a selection.
1248 1388
1249=item $success = $term->selection_grab ($eventtime) 1389=item $success = $term->selection_grab ($eventtime[, $clipboard])
1250 1390
1251Try 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
1252set by the next method). No visual feedback will be given. This function 1393with the next method. No visual feedback will be given. This function
1253is mostly useful from within C<on_sel_grab> hooks. 1394is mostly useful from within C<on_sel_grab> hooks.
1254 1395
1255=item $oldtext = $term->selection ([$newtext]) 1396=item $oldtext = $term->selection ([$newtext, $clipboard])
1256 1397
1257Return 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.
1258 1404
1259=item $term->overlay_simple ($x, $y, $text) 1405=item $term->overlay_simple ($x, $y, $text)
1260 1406
1261Create 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.
1262 1408
1292 1438
1293The methods currently supported on C<urxvt::overlay> objects are: 1439The methods currently supported on C<urxvt::overlay> objects are:
1294 1440
1295=over 4 1441=over 4
1296 1442
1297=item $overlay->set ($x, $y, $text, $rend) 1443=item $overlay->set ($x, $y, $text[, $rend])
1298 1444
1299Similar 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
1300text 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
1301at 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.
1302 1450
1303=item $overlay->hide 1451=item $overlay->hide
1304 1452
1305If visible, hide the overlay, but do not destroy it. 1453If visible, hide the overlay, but do not destroy it.
1306 1454
1369 1517
1370=item $term->scr_add_lines ($string) 1518=item $term->scr_add_lines ($string)
1371 1519
1372Write 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
1373running inside the terminal. It may not contain command sequences (escape 1521running inside the terminal. It may not contain command sequences (escape
1374codes), 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,
1375string 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.
1376 1525
1377Normally 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
1378confused by changes in cursor position or scrolling. Its useful inside a 1527confused by changes in cursor position or scrolling. Its useful inside a
1379C<on_add_lines> hook, though. 1528C<on_add_lines> hook, though.
1380 1529
1388locale-specific encoding of the terminal and can contain command sequences 1537locale-specific encoding of the terminal and can contain command sequences
1389(escape codes) that will be interpreted. 1538(escape codes) that will be interpreted.
1390 1539
1391=item $term->tt_write ($octets) 1540=item $term->tt_write ($octets)
1392 1541
1393Write 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
1394pass characters instead of octets, you should convert your strings first 1544characters instead of octets, you should convert your strings first to the
1395to 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.
1396 1560
1397=item $old_events = $term->pty_ev_events ([$new_events]) 1561=item $old_events = $term->pty_ev_events ([$new_events])
1398 1562
1399Replaces 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
1400be 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
1419Adds 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
1420to receive pointer events all the times: 1584to receive pointer events all the times:
1421 1585
1422 $term->vt_emask_add (urxvt::PointerMotionMask); 1586 $term->vt_emask_add (urxvt::PointerMotionMask);
1423 1587
1588=item $term->set_urgency ($set)
1589
1590Enable/disable the urgency hint on the toplevel window.
1591
1424=item $term->focus_in 1592=item $term->focus_in
1425 1593
1426=item $term->focus_out 1594=item $term->focus_out
1427 1595
1428=item $term->key_press ($state, $keycode[, $time]) 1596=item $term->key_press ($state, $keycode[, $time])
1468=item $env = $term->env 1636=item $env = $term->env
1469 1637
1470Returns a copy of the environment in effect for the terminal as a hashref 1638Returns a copy of the environment in effect for the terminal as a hashref
1471similar to C<\%ENV>. 1639similar to C<\%ENV>.
1472 1640
1641=item @envv = $term->envv
1642
1643Returns the environment as array of strings of the form C<VAR=VALUE>.
1644
1645=item @argv = $term->argv
1646
1647Return the argument vector as this terminal, similar to @ARGV, but
1648includes the program name as first element.
1649
1473=cut 1650=cut
1474 1651
1475sub env { 1652sub env {
1476 if (my $env = $_[0]->_env) {
1477 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env } 1653 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), $_[0]->envv }
1478 } else {
1479 +{ %ENV }
1480 }
1481} 1654}
1482 1655
1483=item $modifiermask = $term->ModLevel3Mask 1656=item $modifiermask = $term->ModLevel3Mask
1484 1657
1485=item $modifiermask = $term->ModMetaMask 1658=item $modifiermask = $term->ModMetaMask
1493 1666
1494Returns the currently displayed screen (0 primary, 1 secondary). 1667Returns the currently displayed screen (0 primary, 1 secondary).
1495 1668
1496=item $cursor_is_hidden = $term->hidden_cursor 1669=item $cursor_is_hidden = $term->hidden_cursor
1497 1670
1498Returns wether the cursor is currently hidden or not. 1671Returns whether the cursor is currently hidden or not.
1499 1672
1500=item $view_start = $term->view_start ([$newvalue]) 1673=item $view_start = $term->view_start ([$newvalue])
1501 1674
1502Returns the row number of the topmost displayed line. Maximum value is 1675Returns the row number of the topmost displayed line. Maximum value is
1503C<0>, which displays the normal terminal contents. Lower values scroll 1676C<0>, which displays the normal terminal contents. Lower values scroll
1511 1684
1512Used after changing terminal contents to display them. 1685Used after changing terminal contents to display them.
1513 1686
1514=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]]) 1687=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
1515 1688
1516Returns 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 >>
1517is 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
1518terminal line. The scrollback buffer starts at line C<-1> and extends to
1519line C<< -$term->nsaved >>. Nothing will be returned if a nonexistent line 1691terminal line. Nothing will be returned if a nonexistent line
1520is requested. 1692is requested.
1521 1693
1522If 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
1523line, 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
1524to 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
1525automatically be updated. 1697automatically be updated.
1526 1698
1527C<$text> is in a special encoding: tabs and wide characters that use more 1699C<$text> is in a special encoding: tabs and wide characters that use more
1528than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535) 1700than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535)
1529characters. Characters with combining characters and other characters that 1701characters. Characters with combining characters and other characters that
1530do not fit into the normal tetx encoding will be replaced with characters 1702do not fit into the normal text encoding will be replaced with characters
1531in the private use area. 1703in the private use area.
1532 1704
1533You have to obey this encoding when changing text. The advantage is 1705You have to obey this encoding when changing text. The advantage is
1534that C<substr> and similar functions work on screen cells and not on 1706that C<substr> and similar functions work on screen cells and not on
1535characters. 1707characters.
1620} 1792}
1621 1793
1622sub urxvt::line::t { 1794sub urxvt::line::t {
1623 my ($self) = @_; 1795 my ($self) = @_;
1624 1796
1625 if (@_ > 1) 1797 if (@_ > 1) {
1626 {
1627 $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})
1628 for $self->{beg} .. $self->{end}; 1799 for $self->{beg} .. $self->{end};
1629 } 1800 }
1630 1801
1631 defined wantarray && 1802 defined wantarray &&
1632 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}), 1803 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
1633 0, $self->{len} 1804 0, $self->{len}
1634} 1805}
1635 1806
1636sub urxvt::line::r { 1807sub urxvt::line::r {
1637 my ($self) = @_; 1808 my ($self) = @_;
1638 1809
1639 if (@_ > 1) 1810 if (@_ > 1) {
1640 {
1641 $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})
1642 for $self->{beg} .. $self->{end}; 1812 for $self->{beg} .. $self->{end};
1643 } 1813 }
1644 1814
1645 if (defined wantarray) { 1815 if (defined wantarray) {
1646 my $rend = [ 1816 my $rend = [
1647 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end} 1817 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
1648 ]; 1818 ];
1680where one character corresponds to one screen cell. See 1850where one character corresponds to one screen cell. See
1681C<< $term->ROW_t >> for details. 1851C<< $term->ROW_t >> for details.
1682 1852
1683=item $string = $term->special_decode $text 1853=item $string = $term->special_decode $text
1684 1854
1685Converts rxvt-unicodes text reprsentation into a perl string. See 1855Converts rxvt-unicodes text representation into a perl string. See
1686C<< $term->ROW_t >> for details. 1856C<< $term->ROW_t >> for details.
1687 1857
1688=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt]) 1858=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1689 1859
1690=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt]) 1860=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1693manpage. 1863manpage.
1694 1864
1695=item $success = $term->grab ($eventtime[, $sync]) 1865=item $success = $term->grab ($eventtime[, $sync])
1696 1866
1697Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1867Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1698synchronous (C<$sync> is true). Also remembers the grab timestampe. 1868synchronous (C<$sync> is true). Also remembers the grab timestamp.
1699 1869
1700=item $term->allow_events_async 1870=item $term->allow_events_async
1701 1871
1702Calls XAllowEvents with AsyncBoth for the most recent grab. 1872Calls XAllowEvents with AsyncBoth for the most recent grab.
1703 1873
1710Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most 1880Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most
1711recent grab. 1881recent grab.
1712 1882
1713=item $term->ungrab 1883=item $term->ungrab
1714 1884
1715Calls XUngrab for the most recent grab. Is called automatically on 1885Calls XUngrabPointer and XUngrabKeyboard for the most recent grab. Is called automatically on
1716evaluation 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
1717the session. 1887the session.
1718 1888
1719=item $atom = $term->XInternAtom ($atom_name[, $only_if_exists]) 1889=item $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
1720 1890
1722 1892
1723=item @atoms = $term->XListProperties ($window) 1893=item @atoms = $term->XListProperties ($window)
1724 1894
1725=item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property) 1895=item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
1726 1896
1727=item $term->XChangeWindowProperty ($window, $property, $type, $format, $octets) 1897=item $term->XChangeProperty ($window, $property, $type, $format, $octets)
1728 1898
1729=item $term->XDeleteProperty ($window, $property) 1899=item $term->XDeleteProperty ($window, $property)
1730 1900
1731=item $window = $term->DefaultRootWindow 1901=item $window = $term->DefaultRootWindow
1732 1902
1739=item $term->XMoveResizeWindow ($window, $x, $y, $width, $height) 1909=item $term->XMoveResizeWindow ($window, $x, $y, $width, $height)
1740 1910
1741=item ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x, $y) 1911=item ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x, $y)
1742 1912
1743=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)
1744 1918
1745Various 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
1746the source of the display, otherwise those functions map more-or-less 1920the source of the display, otherwise those functions map more-or-less
1747directory onto the X functions of the same name. 1921directly onto the X functions of the same name.
1748 1922
1749=back 1923=back
1750 1924
1751=cut 1925=cut
1752 1926
1854 my $env = $self->{term}->env; 2028 my $env = $self->{term}->env;
1855 # 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.
1856 delete $env->{LC_ALL}; 2030 delete $env->{LC_ALL};
1857 $env->{LC_CTYPE} = $self->{term}->locale; 2031 $env->{LC_CTYPE} = $self->{term}->locale;
1858 2032
1859 urxvt::term->new ($env, "popup", 2033 my $term = urxvt::term->new (
2034 $env, "popup",
1860 "--perl-lib" => "", "--perl-ext-common" => "", 2035 "--perl-lib" => "", "--perl-ext-common" => "",
1861 "-pty-fd" => -1, "-sl" => 0, 2036 "-pty-fd" => -1, "-sl" => 0,
1862 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect", 2037 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect",
1863 "--transient-for" => $self->{term}->parent, 2038 "--transient-for" => $self->{term}->parent,
1864 "-display" => $self->{term}->display_id, 2039 "-display" => $self->{term}->display_id,
1865 "-pe" => "urxvt-popup") 2040 "-pe" => "urxvt-popup",
1866 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 }
1867} 2048}
1868 2049
1869sub DESTROY { 2050sub DESTROY {
1870 my ($self) = @_; 2051 my ($self) = @_;
1871 2052
1876=back 2057=back
1877 2058
1878=cut 2059=cut
1879 2060
1880package urxvt::watcher; 2061package urxvt::watcher;
1881
1882@urxvt::timer::ISA = __PACKAGE__;
1883@urxvt::iow::ISA = __PACKAGE__;
1884@urxvt::pw::ISA = __PACKAGE__;
1885@urxvt::iw::ISA = __PACKAGE__;
1886 2062
1887=head2 The C<urxvt::timer> Class 2063=head2 The C<urxvt::timer> Class
1888 2064
1889This class implements timer watchers/events. Time is represented as a 2065This class implements timer watchers/events. Time is represented as a
1890fractional number of seconds since the epoch. Example: 2066fractional number of seconds since the epoch. Example:
1894 ->new 2070 ->new
1895 ->interval (1) 2071 ->interval (1)
1896 ->cb (sub { 2072 ->cb (sub {
1897 $term->{overlay}->set (0, 0, 2073 $term->{overlay}->set (0, 0,
1898 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]); 2074 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
1899 }); 2075 });
1900 2076
1901=over 4 2077=over 4
1902 2078
1903=item $timer = new urxvt::timer 2079=item $timer = new urxvt::timer
1904 2080
1907 2083
1908=item $timer = $timer->cb (sub { my ($timer) = @_; ... }) 2084=item $timer = $timer->cb (sub { my ($timer) = @_; ... })
1909 2085
1910Set the callback to be called when the timer triggers. 2086Set the callback to be called when the timer triggers.
1911 2087
1912=item $tstamp = $timer->at
1913
1914Return the time this watcher will fire next.
1915
1916=item $timer = $timer->set ($tstamp) 2088=item $timer = $timer->set ($tstamp[, $interval])
1917 2089
1918Set the time the event is generated to $tstamp. 2090Set the time the event is generated to $tstamp (and optionally specifies a
2091new $interval).
1919 2092
1920=item $timer = $timer->interval ($interval) 2093=item $timer = $timer->interval ($interval)
1921 2094
1922Normally (and when C<$interval> is C<0>), the timer will automatically 2095By default (and when C<$interval> is C<0>), the timer will automatically
1923stop 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
1924is automatically rescheduled at the given intervals. 2097is automatically rescheduled at the given intervals.
1925 2098
1926=item $timer = $timer->start 2099=item $timer = $timer->start
1927 2100
1928Start the timer. 2101Start the timer.
1929 2102
1930=item $timer = $timer->start ($tstamp) 2103=item $timer = $timer->start ($tstamp[, $interval])
1931 2104
1932Set 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.
1933 2107
1934=item $timer = $timer->after ($delay) 2108=item $timer = $timer->after ($delay[, $interval])
1935 2109
1936Like 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>.
1937 2111
1938=item $timer = $timer->stop 2112=item $timer = $timer->stop
1939 2113
1947 2121
1948 $term->{socket} = ... 2122 $term->{socket} = ...
1949 $term->{iow} = urxvt::iow 2123 $term->{iow} = urxvt::iow
1950 ->new 2124 ->new
1951 ->fd (fileno $term->{socket}) 2125 ->fd (fileno $term->{socket})
1952 ->events (urxvt::EVENT_READ) 2126 ->events (urxvt::EV_READ)
1953 ->start 2127 ->start
1954 ->cb (sub { 2128 ->cb (sub {
1955 my ($iow, $revents) = @_; 2129 my ($iow, $revents) = @_;
1956 # $revents must be 1 here, no need to check 2130 # $revents must be 1 here, no need to check
1957 sysread $term->{socket}, my $buf, 8192 2131 sysread $term->{socket}, my $buf, 8192
1970Set the callback to be called when io events are triggered. C<$reventmask> 2144Set the callback to be called when io events are triggered. C<$reventmask>
1971is a bitset as described in the C<events> method. 2145is a bitset as described in the C<events> method.
1972 2146
1973=item $iow = $iow->fd ($fd) 2147=item $iow = $iow->fd ($fd)
1974 2148
1975Set the filedescriptor (not handle) to watch. 2149Set the file descriptor (not handle) to watch.
1976 2150
1977=item $iow = $iow->events ($eventmask) 2151=item $iow = $iow->events ($eventmask)
1978 2152
1979Set the event mask to watch. The only allowed values are 2153Set the event mask to watch. The only allowed values are
1980C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed 2154C<urxvt::EV_READ> and C<urxvt::EV_WRITE>, which might be ORed
1981together, or C<urxvt::EVENT_NONE>. 2155together, or C<urxvt::EV_NONE>.
1982 2156
1983=item $iow = $iow->start 2157=item $iow = $iow->start
1984 2158
1985Start watching for requested events on the given handle. 2159Start watching for requested events on the given handle.
1986 2160
1987=item $iow = $iow->stop 2161=item $iow = $iow->stop
1988 2162
1989Stop watching for events on the given filehandle. 2163Stop watching for events on the given file handle.
1990 2164
1991=back 2165=back
1992 2166
1993=head2 The C<urxvt::iw> Class 2167=head2 The C<urxvt::iw> Class
1994 2168
2027 ->new 2201 ->new
2028 ->start ($pid) 2202 ->start ($pid)
2029 ->cb (sub { 2203 ->cb (sub {
2030 my ($pw, $exit_status) = @_; 2204 my ($pw, $exit_status) = @_;
2031 ... 2205 ...
2032 }); 2206 });
2033 2207
2034=over 4 2208=over 4
2035 2209
2036=item $pw = new urxvt::pw 2210=item $pw = new urxvt::pw
2037 2211
2041 2215
2042Set the callback to be called when the timer triggers. 2216Set the callback to be called when the timer triggers.
2043 2217
2044=item $pw = $timer->start ($pid) 2218=item $pw = $timer->start ($pid)
2045 2219
2046Tells the wqtcher to start watching for process C<$pid>. 2220Tells the watcher to start watching for process C<$pid>.
2047 2221
2048=item $pw = $pw->stop 2222=item $pw = $pw->stop
2049 2223
2050Stop the watcher. 2224Stop the watcher.
2051 2225
2064 2238
2065=item >= 3 - script loading and management 2239=item >= 3 - script loading and management
2066 2240
2067=item >=10 - all called hooks 2241=item >=10 - all called hooks
2068 2242
2069=item >=11 - hook reutrn values 2243=item >=11 - hook return values
2070 2244
2071=back 2245=back
2072 2246
2073=head1 AUTHOR 2247=head1 AUTHOR
2074 2248
2075 Marc Lehmann <pcg@goof.com> 2249 Marc Lehmann <schmorp@schmorp.de>
2076 http://software.schmorp.de/pkg/rxvt-unicode 2250 http://software.schmorp.de/pkg/rxvt-unicode
2077 2251
2078=cut 2252=cut
2079 2253
20801 22541
2255
2256# vim: sw=3:

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines