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.71 by root, Mon Jan 9 23:18:49 2006 UTC vs.
Revision 1.195 by sf-exg, Wed Jun 29 22:18:11 2011 UTC

17 17
18 @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test 18 @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test
19 19
20=head1 DESCRIPTION 20=head1 DESCRIPTION
21 21
22Everytime a terminal object gets created, extension scripts specified via 22Every time a terminal object gets created, extension scripts specified via
23the C<perl> resource are loaded and associated with it. 23the C<perl> resource are loaded and associated with it.
24 24
25Scripts are compiled in a 'use strict' and 'use utf8' environment, and 25Scripts are compiled in a 'use strict' and 'use utf8' environment, and
26thus must be encoded as UTF-8. 26thus must be encoded as UTF-8.
27 27
28Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where 28Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where
29scripts will be shared (but not enabled) for all terminals. 29scripts will be shared (but not enabled) for all terminals.
30 30
31=head2 Prepackaged Extensions 31You can disable the embedded perl interpreter by setting both "perl-ext"
32and "perl-ext-common" resources to the empty string.
32 33
34=head1 PREPACKAGED EXTENSIONS
35
33This section describes the extensiosn delivered with this version. You can 36This section describes the extensions delivered with this release. You can
34find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>. 37find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>.
35 38
36You can activate them like this: 39You can activate them like this:
37 40
38 @@RXVT_NAME@@ -pe <extensionname> 41 @@RXVT_NAME@@ -pe <extensionname>
39 42
43Or by adding them to the resource for extensions loaded by default:
44
45 URxvt.perl-ext-common: default,selection-autotransform
46
40=over 4 47=over 4
41 48
42=item selection (enabled by default) 49=item selection (enabled by default)
43 50
44Intelligent selection. This extension tries to be more intelligent when 51(More) intelligent selection. This extension tries to be more intelligent
45the user extends selections (double-click). Right now, it tries to select 52when the user extends selections (double-click and further clicks). Right
46urls and complete shell-quoted arguments, which is very convenient, too, 53now, it tries to select words, urls and complete shell-quoted
47if your F<ls> supports C<--quoting-style=shell>. 54arguments, which is very convenient, too, if your F<ls> supports
55C<--quoting-style=shell>.
48 56
49It also offers the following bindable event: 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:
50 86
51=over 4 87=over 4
52 88
53=item rot13 89=item rot13
54 90
61=item option-popup (enabled by default) 97=item option-popup (enabled by default)
62 98
63Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at 99Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at
64runtime. 100runtime.
65 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
66=item selection-popup (enabled by default) 119=item selection-popup (enabled by default)
67 120
68Binds a popup menu to Ctrl-Button3 that lets you convert the selection 121Binds a popup menu to Ctrl-Button3 that lets you convert the selection
69text into various other formats/action. 122text into various other formats/action (such as uri unescaping, perl
123evaluation, web-browser starting etc.), depending on content.
70 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
71=item searchable-scrollback (enabled by default) 144=item searchable-scrollback<hotkey> (enabled by default)
72 145
73Adds regex search functionality to the scrollback buffer, triggered by a 146Adds regex search functionality to the scrollback buffer, triggered
74hotkey (default: C<M-s>). When in search mode, terminal input/output is 147by a hotkey (default: C<M-s>). While in search mode, normal terminal
75suspended, C</> starts an incremental regex search, C<n> searches further, 148input/output is suspended and a regex is displayed at the bottom of the
76C<p> jumps to the previous match. C<enter> leaves search mode at the 149screen.
77current position and C<escape> returns to the original position.
78 150
79=item digital-clock 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.
80 158
81Displays a digital clock using the built-in overlay. 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.
82 162
83=item mark-urls 163See L<perlre> for more info about perl regular expression syntax.
84 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
85Uses per-line display filtering (C<on_line_update>) to underline urls. 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 overlay-osc
309
310This extension implements some OSC commands to display timed popups on the
311screen - useful for status displays from within scripts. You have to read
312the sources for more info.
86 313
87=item block-graphics-to-ascii 314=item block-graphics-to-ascii
88 315
89A not very useful example of filtering all text output to the terminal, 316A not very useful example of filtering all text output to the terminal
90by replacing all line-drawing characters (U+2500 .. U+259F) by a 317by replacing all line-drawing characters (U+2500 .. U+259F) by a
91similar-looking ascii character. 318similar-looking ascii character.
319
320=item digital-clock
321
322Displays a digital clock using the built-in overlay.
323
324=item remote-clipboard
325
326Somewhat of a misnomer, this extension adds two menu entries to the
327selection popup that allows one to run external commands to store the
328selection somewhere and fetch it again.
329
330We use it to implement a "distributed selection mechanism", which just
331means that one command uploads the file to a remote server, and another
332reads it.
333
334The commands can be set using the C<URxvt.remote-selection.store> and
335C<URxvt.remote-selection.fetch> resources. The first should read the
336selection to store from STDIN (always in UTF-8), the second should provide
337the selection data on STDOUT (also in UTF-8).
338
339The defaults (which are likely useless to you) use rsh and cat:
340
341 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
342 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
343
344=item selection-pastebin
345
346This is a little rarely useful extension that uploads the selection as
347textfile to a remote site (or does other things). (The implementation is
348not currently secure for use in a multiuser environment as it writes to
349F</tmp> directly.).
350
351It listens to the C<selection-pastebin:remote-pastebin> keyboard command,
352i.e.
353
354 URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin
355
356Pressing this combination runs a command with C<%> replaced by the name of
357the textfile. This command can be set via a resource:
358
359 URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
360
361And the default is likely not useful to anybody but the few people around
362here :)
363
364The name of the textfile is the hex encoded md5 sum of the selection, so
365the same content should lead to the same filename.
366
367After a successful upload the selection will be replaced by the text given
368in the C<selection-pastebin-url> resource (again, the % is the placeholder
369for the filename):
370
371 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
372
373I<Note to xrdb users:> xrdb uses the C preprocessor, which might interpret
374the double C</> characters as comment start. Use C<\057\057> instead,
375which works regardless of whether xrdb is used to parse the resource file
376or not.
377
378=item macosx-clipboard and macosx-clipboard-native
379
380These two modules implement an extended clipboard for Mac OS X. They are
381used like this:
382
383 URxvt.perl-ext-common: default,macosx-clipboard
384 URxvt.keysym.M-c: perl:macosx-clipboard:copy
385 URxvt.keysym.M-v: perl:macosx-clipboard:paste
386
387The difference between them is that the native variant requires a
388perl from apple's devkit or so, and C<macosx-clipboard> requires the
389C<Mac::Pasteboard> module, works with other perls, has fewer bugs, is
390simpler etc. etc.
92 391
93=item example-refresh-hooks 392=item example-refresh-hooks
94 393
95Displays a very simple digital clock in the upper right corner of the 394Displays a very simple digital clock in the upper right corner of the
96window. Illustrates overwriting the refresh callbacks to create your own 395window. Illustrates overwriting the refresh callbacks to create your own
97overlays or changes. 396overlays or changes.
98 397
398=item confirm-paste
399
400Displays a confirmation dialog when a paste containing at least a full
401line is detected.
402
99=back 403=back
404
405=head1 API DOCUMENTATION
100 406
101=head2 General API Considerations 407=head2 General API Considerations
102 408
103All objects (such as terminals, time watchers etc.) are typical 409All objects (such as terminals, time watchers etc.) are typical
104reference-to-hash objects. The hash can be used to store anything you 410reference-to-hash objects. The hash can be used to store anything you
116 422
117=over 4 423=over 4
118 424
119=item $text 425=item $text
120 426
121Rxvt-unicodes special way of encoding text, where one "unicode" character 427Rxvt-unicode's special way of encoding text, where one "unicode" character
122always represents one screen cell. See L<row_t> for a discussion of this format. 428always represents one screen cell. See L<ROW_t> for a discussion of this format.
123 429
124=item $string 430=item $string
125 431
126A perl text string, with an emphasis on I<text>. It can store all unicode 432A perl text string, with an emphasis on I<text>. It can store all unicode
127characters and is to be distinguished with text encoded in a specific 433characters and is to be distinguished with text encoded in a specific
134 440
135=back 441=back
136 442
137=head2 Extension Objects 443=head2 Extension Objects
138 444
139Very perl extension is a perl class. A separate perl object is created 445Every perl extension is a perl class. A separate perl object is created
140for each terminal and each extension and passed as the first parameter to 446for each terminal, and each terminal has its own set of extension objects,
141hooks. So extensions can use their C<$self> object without having to think 447which are passed as the first parameter to hooks. So extensions can use
142about other extensions, with the exception of methods and members that 448their C<$self> object without having to think about clashes with other
449extensions or other terminals, with the exception of methods and members
143begin with an underscore character C<_>: these are reserved for internal 450that begin with an underscore character C<_>: these are reserved for
144use. 451internal use.
145 452
146Although it isn't a C<urxvt::term> object, you can call all methods of the 453Although it isn't a C<urxvt::term> object, you can call all methods of the
147C<urxvt::term> class on this object. 454C<urxvt::term> class on this object.
148 455
149It has the following methods and data members: 456It has the following methods and data members:
170=head2 Hooks 477=head2 Hooks
171 478
172The following subroutines can be declared in extension files, and will be 479The following subroutines can be declared in extension files, and will be
173called whenever the relevant event happens. 480called whenever the relevant event happens.
174 481
175The first argument passed to them is an extension oject as described in 482The first argument passed to them is an extension object as described in
176the in the C<Extension Objects> section. 483the in the C<Extension Objects> section.
177 484
178B<All> of these hooks must return a boolean value. If it is true, then the 485B<All> of these hooks must return a boolean value. If any of the called
179event counts as being I<consumed>, and the invocation of other hooks is 486hooks returns true, then the event counts as being I<consumed>, and the
180skipped, and the relevant action might not be carried out by the C++ code. 487relevant action might not be carried out by the C++ code.
181 488
182I<< When in doubt, return a false value (preferably C<()>). >> 489I<< When in doubt, return a false value (preferably C<()>). >>
183 490
184=over 4 491=over 4
185 492
186=item on_init $term 493=item on_init $term
187 494
188Called after a new terminal object has been initialized, but before 495Called after a new terminal object has been initialized, but before
189windows are created or the command gets run. Most methods are unsafe to 496windows are created or the command gets run. Most methods are unsafe to
190call or deliver senseless data, as terminal size and other characteristics 497call or deliver senseless data, as terminal size and other characteristics
191have not yet been determined. You can safely query and change resources, 498have not yet been determined. You can safely query and change resources
192though. 499and options, though. For many purposes the C<on_start> hook is a better
500place.
501
502=item on_start $term
503
504Called at the very end of initialisation of a new terminal, just before
505trying to map (display) the toplevel and returning to the main loop.
506
507=item on_destroy $term
508
509Called whenever something tries to destroy terminal, when the terminal is
510still fully functional (not for long, though).
193 511
194=item on_reset $term 512=item on_reset $term
195 513
196Called after the screen is "reset" for any reason, such as resizing or 514Called after the screen is "reset" for any reason, such as resizing or
197control sequences. Here is where you can react on changes to size-related 515control sequences. Here is where you can react on changes to size-related
198variables. 516variables.
199 517
200=item on_start $term 518=item on_child_start $term, $pid
201 519
202Called at the very end of initialisation of a new terminal, just before 520Called just after the child process has been C<fork>ed.
203returning to the mainloop. 521
522=item on_child_exit $term, $status
523
524Called just after the child process has exited. C<$status> is the status
525from C<waitpid>.
204 526
205=item on_sel_make $term, $eventtime 527=item on_sel_make $term, $eventtime
206 528
207Called whenever a selection has been made by the user, but before the 529Called whenever a selection has been made by the user, but before the
208selection text is copied, so changes to the beginning, end or type of the 530selection text is copied, so changes to the beginning, end or type of the
215 537
216Called whenever a selection has been copied, but before the selection is 538Called whenever a selection has been copied, but before the selection is
217requested from the server. The selection text can be queried and changed 539requested from the server. The selection text can be queried and changed
218by calling C<< $term->selection >>. 540by calling C<< $term->selection >>.
219 541
220Returning a true value aborts selection grabbing. It will still be hilighted. 542Returning a true value aborts selection grabbing. It will still be highlighted.
221 543
222=item on_sel_extend $term 544=item on_sel_extend $term
223 545
224Called whenever the user tries to extend the selection (e.g. with a double 546Called whenever the user tries to extend the selection (e.g. with a double
225click) and is either supposed to return false (normal operation), or 547click) and is either supposed to return false (normal operation), or
226should extend the selection itelf and return true to suppress the built-in 548should extend the selection itself and return true to suppress the built-in
227processing. 549processing. This can happen multiple times, as long as the callback
550returns true, it will be called on every further click by the user and is
551supposed to enlarge the selection more and more, if possible.
228 552
229See the F<selection> example extension. 553See the F<selection> example extension.
230 554
231=item on_view_change $term, $offset 555=item on_view_change $term, $offset
232 556
233Called whenever the view offset changes, i..e the user or program 557Called whenever the view offset changes, i.e. the user or program
234scrolls. Offset C<0> means display the normal terminal, positive values 558scrolls. Offset C<0> means display the normal terminal, positive values
235show this many lines of scrollback. 559show this many lines of scrollback.
236 560
237=item on_scroll_back $term, $lines, $saved 561=item on_scroll_back $term, $lines, $saved
238 562
242 566
243It is called before lines are scrolled out (so rows 0 .. min ($lines - 1, 567It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
244$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total 568$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
245number of lines that will be in the scrollback buffer. 569number of lines that will be in the scrollback buffer.
246 570
247=item on_osc_seq $term, $string 571=item on_osc_seq $term, $op, $args, $resp
572
573Called on every OSC sequence and can be used to suppress it or modify its
574behaviour. The default should be to return an empty list. A true value
575suppresses execution of the request completely. Make sure you don't get
576confused by recursive invocations when you output an OSC sequence within
577this callback.
578
579C<on_osc_seq_perl> should be used for new behaviour.
580
581=item on_osc_seq_perl $term, $args, $resp
248 582
249Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 583Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
250operating system command) is processed. Cursor position and other state 584operating system command) is processed. Cursor position and other state
251information is up-to-date when this happens. For interoperability, the 585information is up-to-date when this happens. For interoperability, the
252string should start with the extension name and a colon, to distinguish 586string should start with the extension name (sans -osc) and a semicolon,
253it from commands for other extensions, and this might be enforced in the 587to distinguish it from commands for other extensions, and this might be
254future. 588enforced in the future.
589
590For example, C<overlay-osc> uses this:
591
592 sub on_osc_seq_perl {
593 my ($self, $osc, $resp) = @_;
594
595 return unless $osc =~ s/^overlay;//;
596
597 ... process remaining $osc string
598 }
255 599
256Be careful not ever to trust (in a security sense) the data you receive, 600Be careful not ever to trust (in a security sense) the data you receive,
257as its source can not easily be controleld (e-mail content, messages from 601as its source can not easily be controlled (e-mail content, messages from
258other users on the same system etc.). 602other users on the same system etc.).
603
604For responses, C<$resp> contains the end-of-args separator used by the
605sender.
259 606
260=item on_add_lines $term, $string 607=item on_add_lines $term, $string
261 608
262Called whenever text is about to be output, with the text as argument. You 609Called whenever text is about to be output, with the text as argument. You
263can filter/change and output the text yourself by returning a true value 610can filter/change and output the text yourself by returning a true value
264and calling C<< $term->scr_add_lines >> yourself. Please note that this 611and calling C<< $term->scr_add_lines >> yourself. Please note that this
265might be very slow, however, as your hook is called for B<all> text being 612might be very slow, however, as your hook is called for B<all> text being
266output. 613output.
267 614
615=item on_tt_write $term, $octets
616
617Called whenever some data is written to the tty/pty and can be used to
618suppress or filter tty input.
619
620=item on_tt_paste $term, $octets
621
622Called whenever text is about to be pasted, with the text as argument. You
623can filter/change and paste the text yourself by returning a true value
624and calling C<< $term->tt_paste >> yourself. C<$octets> is
625locale-encoded.
626
268=item on_line_update $term, $row 627=item on_line_update $term, $row
269 628
270Called whenever a line was updated or changed. Can be used to filter 629Called whenever a line was updated or changed. Can be used to filter
271screen output (e.g. underline urls or other useless stuff). Only lines 630screen output (e.g. underline urls or other useless stuff). Only lines
272that are being shown will be filtered, and, due to performance reasons, 631that are being shown will be filtered, and, due to performance reasons,
279later with the already-modified line (e.g. if unrelated parts change), so 638later with the already-modified line (e.g. if unrelated parts change), so
280you cannot just toggle rendition bits, but only set them. 639you cannot just toggle rendition bits, but only set them.
281 640
282=item on_refresh_begin $term 641=item on_refresh_begin $term
283 642
284Called just before the screen gets redrawn. Can be used for overlay 643Called just before the screen gets redrawn. Can be used for overlay or
285or similar effects by modify terminal contents in refresh_begin, and 644similar effects by modifying the terminal contents in refresh_begin, and
286restoring them in refresh_end. The built-in overlay and selection display 645restoring them in refresh_end. The built-in overlay and selection display
287code is run after this hook, and takes precedence. 646code is run after this hook, and takes precedence.
288 647
289=item on_refresh_end $term 648=item on_refresh_end $term
290 649
291Called just after the screen gets redrawn. See C<on_refresh_begin>. 650Called just after the screen gets redrawn. See C<on_refresh_begin>.
292 651
293=item on_keyboard_command $term, $string 652=item on_user_command $term, $string
294 653
295Called whenever the user presses a key combination that has a 654Called whenever a user-configured event is being activated (e.g. via
296C<perl:string> action bound to it (see description of the B<keysym> 655a C<perl:string> action bound to a key, see description of the B<keysym>
297resource in the @@RXVT_NAME@@(1) manpage). 656resource in the @@RXVT_NAME@@(1) manpage).
657
658The event is simply the action string. This interface is assumed to change
659slightly in the future.
660
661=item on_resize_all_windows $term, $new_width, $new_height
662
663Called just after the new window size has been calculated, but before
664windows are actually being resized or hints are being set. If this hook
665returns TRUE, setting of the window hints is being skipped.
666
667=item on_x_event $term, $event
668
669Called on every X event received on the vt window (and possibly other
670windows). Should only be used as a last resort. Most event structure
671members are not passed.
672
673=item on_root_event $term, $event
674
675Like C<on_x_event>, but is called for events on the root window.
298 676
299=item on_focus_in $term 677=item on_focus_in $term
300 678
301Called whenever the window gets the keyboard focus, before rxvt-unicode 679Called whenever the window gets the keyboard focus, before rxvt-unicode
302does focus in processing. 680does focus in processing.
303 681
304=item on_focus_out $term 682=item on_focus_out $term
305 683
306Called wheneever the window loses keyboard focus, before rxvt-unicode does 684Called whenever the window loses keyboard focus, before rxvt-unicode does
307focus out processing. 685focus out processing.
308 686
687=item on_configure_notify $term, $event
688
689=item on_property_notify $term, $event
690
309=item on_key_press $term, $event, $keysym, $octets 691=item on_key_press $term, $event, $keysym, $octets
310 692
311=item on_key_release $term, $event, $keysym 693=item on_key_release $term, $event, $keysym
312 694
313=item on_button_press $term, $event 695=item on_button_press $term, $event
318 700
319=item on_map_notify $term, $event 701=item on_map_notify $term, $event
320 702
321=item on_unmap_notify $term, $event 703=item on_unmap_notify $term, $event
322 704
323Called whenever the corresponding X event is received for the terminal If 705Called whenever the corresponding X event is received for the terminal. If
324the hook returns true, then the even will be ignored by rxvt-unicode. 706the hook returns true, then the event will be ignored by rxvt-unicode.
325 707
326The event is a hash with most values as named by Xlib (see the XEvent 708The event is a hash with most values as named by Xlib (see the XEvent
327manpage), with the additional members C<row> and C<col>, which are the row 709manpage), with the additional members C<row> and C<col>, which are the
328and column under the mouse cursor. 710(real, not screen-based) row and column under the mouse cursor.
329 711
330C<on_key_press> additionally receives the string rxvt-unicode would 712C<on_key_press> additionally receives the string rxvt-unicode would
331output, if any, in locale-specific encoding. 713output, if any, in locale-specific encoding.
332 714
333subwindow. 715subwindow.
334 716
335=back 717=item on_client_message $term, $event
336 718
337=head2 Variables in the C<urxvt> Package 719=item on_wm_protocols $term, $event
338 720
339=over 4 721=item on_wm_delete_window $term, $event
340 722
341=item $urxvt::TERM 723Called when various types of ClientMessage events are received (all with
724format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
342 725
343The current terminal. This variable stores the current C<urxvt::term> 726=item on_bell $term
344object, whenever a callback/hook is executing.
345 727
346=back 728Called on receipt of a bell character.
347
348=head2 Functions in the C<urxvt> Package
349
350=over 4
351
352=item $term = new urxvt [arg...]
353
354Creates a new terminal, very similar as if you had started it with
355C<system $binfile, arg...>. Croaks (and probably outputs an error message)
356if the new instance couldn't be created. Returns C<undef> if the new
357instance didn't initialise perl, and the terminal object otherwise. The
358C<init> and C<start> hooks will be called during the call.
359
360=item urxvt::fatal $errormessage
361
362Fatally aborts execution with the given error message. Avoid at all
363costs! The only time this is acceptable is when the terminal process
364starts up.
365
366=item urxvt::warn $string
367
368Calls C<rxvt_warn> with the given string which should not include a
369newline. The module also overwrites the C<warn> builtin with a function
370that calls this function.
371
372Using this function has the advantage that its output ends up in the
373correct place, e.g. on stderr of the connecting urxvtc client.
374
375=item $is_safe = urxvt::safe
376
377Returns true when it is safe to do potentially unsafe things, such as
378evaluating perl code specified by the user. This is true when urxvt was
379started setuid or setgid.
380
381=item $time = urxvt::NOW
382
383Returns the "current time" (as per the event loop).
384
385=item urxvt::CurrentTime
386
387=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
388Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
389Button4Mask, Button5Mask, AnyModifier
390
391Various constants for use in X calls and event processing.
392
393=back
394
395=head2 RENDITION
396
397Rendition bitsets contain information about colour, font, font styles and
398similar information for each screen cell.
399
400The following "macros" deal with changes in rendition sets. You should
401never just create a bitset, you should always modify an existing one,
402as they contain important information required for correct operation of
403rxvt-unicode.
404
405=over 4
406
407=item $rend = urxvt::DEFAULT_RSTYLE
408
409Returns the default rendition, as used when the terminal is starting up or
410being reset. Useful as a base to start when creating renditions.
411
412=item $rend = urxvt::OVERLAY_RSTYLE
413
414Return the rendition mask used for overlays by default.
415
416=item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
417
418Return the bit that enabled bold, italic, blink, reverse-video and
419underline, respectively. To enable such a style, just logically OR it into
420the bitset.
421
422=item $foreground = urxvt::GET_BASEFG $rend
423
424=item $background = urxvt::GET_BASEBG $rend
425
426Return the foreground/background colour index, respectively.
427
428=item $rend = urxvt::SET_FGCOLOR ($rend, $new_colour)
429
430=item $rend = urxvt::SET_BGCOLOR ($rend, $new_colour)
431
432Replace the foreground/background colour in the rendition mask with the
433specified one.
434
435=item $value = urxvt::GET_CUSTOM ($rend)
436
437Return the "custom" value: Every rendition has 5 bits for use by
438extensions. They can be set and changed as you like and are initially
439zero.
440
441=item $rend = urxvt::SET_CUSTOM ($rend, $new_value)
442
443Change the custom value.
444 729
445=back 730=back
446 731
447=cut 732=cut
448 733
454use Scalar::Util (); 739use Scalar::Util ();
455use List::Util (); 740use List::Util ();
456 741
457our $VERSION = 1; 742our $VERSION = 1;
458our $TERM; 743our $TERM;
744our @TERM_INIT;
745our @TERM_EXT;
459our @HOOKNAME; 746our @HOOKNAME;
460our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME; 747our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
461our %OPTION; 748our %OPTION;
749
462our $LIBDIR; 750our $LIBDIR;
751our $RESNAME;
752our $RESCLASS;
753our $RXVTNAME;
754
755our $NOCHAR = chr 0xffff;
756
757=head2 Variables in the C<urxvt> Package
758
759=over 4
760
761=item $urxvt::LIBDIR
762
763The rxvt-unicode library directory, where, among other things, the perl
764modules and scripts are stored.
765
766=item $urxvt::RESCLASS, $urxvt::RESCLASS
767
768The resource class and name rxvt-unicode uses to look up X resources.
769
770=item $urxvt::RXVTNAME
771
772The basename of the installed binaries, usually C<urxvt>.
773
774=item $urxvt::TERM
775
776The current terminal. This variable stores the current C<urxvt::term>
777object, whenever a callback/hook is executing.
778
779=item @urxvt::TERM_INIT
780
781All code references in this array will be called as methods of the next newly
782created C<urxvt::term> object (during the C<on_init> phase). The array
783gets cleared before the code references that were in it are being executed,
784so references can push themselves onto it again if they so desire.
785
786This complements to the perl-eval command line option, but gets executed
787first.
788
789=item @urxvt::TERM_EXT
790
791Works similar to C<@TERM_INIT>, but contains perl package/class names, which
792get registered as normal extensions after calling the hooks in C<@TERM_INIT>
793but before other extensions. Gets cleared just like C<@TERM_INIT>.
794
795=back
796
797=head2 Functions in the C<urxvt> Package
798
799=over 4
800
801=item urxvt::fatal $errormessage
802
803Fatally aborts execution with the given error message (which should
804include a trailing newline). Avoid at all costs! The only time this
805is acceptable (and useful) is in the init hook, where it prevents the
806terminal from starting up.
807
808=item urxvt::warn $string
809
810Calls C<rxvt_warn> with the given string which should include a trailing
811newline. The module also overwrites the C<warn> builtin with a function
812that calls this function.
813
814Using this function has the advantage that its output ends up in the
815correct place, e.g. on stderr of the connecting urxvtc client.
816
817Messages have a size limit of 1023 bytes currently.
818
819=item @terms = urxvt::termlist
820
821Returns all urxvt::term objects that exist in this process, regardless of
822whether they are started, being destroyed etc., so be careful. Only term
823objects that have perl extensions attached will be returned (because there
824is no urxvt::term object associated with others).
825
826=item $time = urxvt::NOW
827
828Returns the "current time" (as per the event loop).
829
830=item urxvt::CurrentTime
831
832=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
833Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
834Button4Mask, Button5Mask, AnyModifier
835
836=item urxvt::NoEventMask, KeyPressMask, KeyReleaseMask,
837ButtonPressMask, ButtonReleaseMask, EnterWindowMask, LeaveWindowMask,
838PointerMotionMask, PointerMotionHintMask, Button1MotionMask, Button2MotionMask,
839Button3MotionMask, Button4MotionMask, Button5MotionMask, ButtonMotionMask,
840KeymapStateMask, ExposureMask, VisibilityChangeMask, StructureNotifyMask,
841ResizeRedirectMask, SubstructureNotifyMask, SubstructureRedirectMask,
842FocusChangeMask, PropertyChangeMask, ColormapChangeMask, OwnerGrabButtonMask
843
844=item urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify,
845EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose,
846GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify, DestroyNotify,
847UnmapNotify, MapNotify, MapRequest, ReparentNotify, ConfigureNotify,
848ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify,
849CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest,
850SelectionNotify, ColormapNotify, ClientMessage, MappingNotify
851
852Various constants for use in X calls and event processing.
853
854=back
855
856=head2 RENDITION
857
858Rendition bitsets contain information about colour, font, font styles and
859similar information for each screen cell.
860
861The following "macros" deal with changes in rendition sets. You should
862never just create a bitset, you should always modify an existing one,
863as they contain important information required for correct operation of
864rxvt-unicode.
865
866=over 4
867
868=item $rend = urxvt::DEFAULT_RSTYLE
869
870Returns the default rendition, as used when the terminal is starting up or
871being reset. Useful as a base to start when creating renditions.
872
873=item $rend = urxvt::OVERLAY_RSTYLE
874
875Return the rendition mask used for overlays by default.
876
877=item $rendbit = urxvt::RS_Bold, urxvt::RS_Italic, urxvt::RS_Blink,
878urxvt::RS_RVid, urxvt::RS_Uline
879
880Return the bit that enabled bold, italic, blink, reverse-video and
881underline, respectively. To enable such a style, just logically OR it into
882the bitset.
883
884=item $foreground = urxvt::GET_BASEFG $rend
885
886=item $background = urxvt::GET_BASEBG $rend
887
888Return the foreground/background colour index, respectively.
889
890=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
891
892=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
893
894=item $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
895
896Replace the foreground/background colour in the rendition mask with the
897specified one.
898
899=item $value = urxvt::GET_CUSTOM $rend
900
901Return the "custom" value: Every rendition has 5 bits for use by
902extensions. They can be set and changed as you like and are initially
903zero.
904
905=item $rend = urxvt::SET_CUSTOM $rend, $new_value
906
907Change the custom value.
908
909=back
910
911=cut
463 912
464BEGIN { 913BEGIN {
465 urxvt->bootstrap;
466
467 # overwrite perl's warn 914 # overwrite perl's warn
468 *CORE::GLOBAL::warn = sub { 915 *CORE::GLOBAL::warn = sub {
469 my $msg = join "", @_; 916 my $msg = join "", @_;
470 $msg .= "\n" 917 $msg .= "\n"
471 unless $msg =~ /\n$/; 918 unless $msg =~ /\n$/;
472 urxvt::warn ($msg); 919 urxvt::warn ($msg);
473 }; 920 };
474
475 delete $ENV{IFS};
476 delete $ENV{CDPATH};
477 delete $ENV{BASH_ENV};
478 $ENV{PATH} = "/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/opt/bin:/opt/sbin";
479} 921}
480 922
481my @hook_count; 923no warnings 'utf8';
924
482my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 925my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
483 926
484sub verbose { 927sub verbose {
485 my ($level, $msg) = @_; 928 my ($level, $msg) = @_;
486 warn "$msg\n" if $level <= $verbosity; 929 warn "$msg\n" if $level <= $verbosity;
487} 930}
488 931
489my $extension_pkg = "extension0000";
490my %extension_pkg; 932my %extension_pkg;
491 933
492# load a single script into its own package, once only 934# load a single script into its own package, once only
493sub extension_package($) { 935sub extension_package($) {
494 my ($path) = @_; 936 my ($path) = @_;
495 937
496 $extension_pkg{$path} ||= do { 938 $extension_pkg{$path} ||= do {
497 my $pkg = "urxvt::" . ($extension_pkg++); 939 $path =~ /([^\/\\]+)$/;
940 my $pkg = $1;
941 $pkg =~ s/[^[:word:]]/_/g;
942 $pkg = "urxvt::ext::$pkg";
498 943
499 verbose 3, "loading extension '$path' into package '$pkg'"; 944 verbose 3, "loading extension '$path' into package '$pkg'";
500 945
501 open my $fh, "<:raw", $path 946 open my $fh, "<:raw", $path
502 or die "$path: $!"; 947 or die "$path: $!";
503 948
504 my $source = untaint 949 my $source =
505 "package $pkg; use strict; use utf8;\n" 950 "package $pkg; use strict; use utf8; no warnings 'utf8';\n"
506 . "use base urxvt::term::extension::;\n"
507 . "#line 1 \"$path\"\n{\n" 951 . "#line 1 \"$path\"\n{\n"
508 . (do { local $/; <$fh> }) 952 . (do { local $/; <$fh> })
509 . "\n};\n1"; 953 . "\n};\n1";
510 954
511 eval $source 955 eval $source
522 local $TERM = shift; 966 local $TERM = shift;
523 my $htype = shift; 967 my $htype = shift;
524 968
525 if ($htype == 0) { # INIT 969 if ($htype == 0) { # INIT
526 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 970 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
527 971
528 my %ext_arg; 972 my %ext_arg;
529 973
974 {
975 my @init = @TERM_INIT;
976 @TERM_INIT = ();
977 $_->($TERM) for @init;
978 my @pkg = @TERM_EXT;
979 @TERM_EXT = ();
980 $TERM->register_package ($_) for @pkg;
981 }
982
530 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) { 983 for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
531 if ($_ eq "default") { 984 if ($_ eq "default") {
532 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback); 985 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback readline);
533 } elsif (/^-(.*)$/) { 986 } elsif (/^-(.*)$/) {
534 delete $ext_arg{$1}; 987 delete $ext_arg{$1};
535 } elsif (/^([^<]+)<(.*)>$/) { 988 } elsif (/^([^<]+)<(.*)>$/) {
536 push @{ $ext_arg{$1} }, $2; 989 push @{ $ext_arg{$1} }, $2;
537 } else { 990 } else {
538 $ext_arg{$_} ||= []; 991 $ext_arg{$_} ||= [];
539 } 992 }
540 } 993 }
541 994
542 while (my ($ext, $argv) = each %ext_arg) { 995 for my $ext (sort keys %ext_arg) {
543 my @files = grep -f $_, map "$_/$ext", @dirs; 996 my @files = grep -f $_, map "$_/$ext", @dirs;
544 997
545 if (@files) { 998 if (@files) {
546 $TERM->register_package (extension_package $files[0], $argv); 999 $TERM->register_package (extension_package $files[0], $ext_arg{$ext});
547 } else { 1000 } else {
548 warn "perl extension '$ext' not found in perl library search path\n"; 1001 warn "perl extension '$ext' not found in perl library search path\n";
549 } 1002 }
550 } 1003 }
551 1004
557 1010
558 if (my $cb = $TERM->{_hook}[$htype]) { 1011 if (my $cb = $TERM->{_hook}[$htype]) {
559 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")" 1012 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
560 if $verbosity >= 10; 1013 if $verbosity >= 10;
561 1014
562 keys %$cb; 1015 for my $pkg (keys %$cb) {
563
564 while (my ($pkg, $cb) = each %$cb) {
565 $retval = eval { $cb->($TERM->{_pkg}{$pkg}, @_) } 1016 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg}, @_) };
566 and last; 1017 $retval ||= $retval_;
567 1018
568 if ($@) { 1019 if ($@) {
569 $TERM->ungrab; # better to lose the grab than the session 1020 $TERM->ungrab; # better to lose the grab than the session
570 warn $@; 1021 warn $@;
571 } 1022 }
572 } 1023 }
1024
1025 verbose 11, "$HOOKNAME[$htype] returning <$retval>"
1026 if $verbosity >= 11;
573 } 1027 }
574 1028
575 if ($htype == 1) { # DESTROY 1029 if ($htype == 1) { # DESTROY
576 if (my $hook = delete $TERM->{_hook}) {
577 for my $htype (0..$#$hook) {
578 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
579 or set_should_invoke $htype, 0;
580 }
581 }
582
583 # clear package objects 1030 # clear package objects
584 %$_ = () for values %{ $TERM->{_pkg} }; 1031 %$_ = () for values %{ $TERM->{_pkg} };
585 1032
586 # clear package 1033 # clear package
587 %$TERM = (); 1034 %$TERM = ();
588 } 1035 }
589 1036
590 $retval 1037 $retval
1038}
1039
1040sub SET_COLOR($$$) {
1041 SET_BGCOLOR (SET_FGCOLOR ($_[0], $_[1]), $_[2])
1042}
1043
1044sub rend2mask {
1045 no strict 'refs';
1046 my ($str, $mask) = (@_, 0);
1047 my %color = ( fg => undef, bg => undef );
1048 my @failed;
1049 for my $spec ( split /\s+/, $str ) {
1050 if ( $spec =~ /^([fb]g)[_:-]?(\d+)/i ) {
1051 $color{lc($1)} = $2;
1052 } else {
1053 my $neg = $spec =~ s/^[-^]//;
1054 unless ( exists &{"RS_$spec"} ) {
1055 push @failed, $spec;
1056 next;
1057 }
1058 my $cur = &{"RS_$spec"};
1059 if ( $neg ) {
1060 $mask &= ~$cur;
1061 } else {
1062 $mask |= $cur;
1063 }
1064 }
1065 }
1066 ($mask, @color{qw(fg bg)}, \@failed)
591} 1067}
592 1068
593# urxvt::term::extension 1069# urxvt::term::extension
594 1070
595package urxvt::term::extension; 1071package urxvt::term::extension;
601 while (my ($name, $cb) = each %hook) { 1077 while (my ($name, $cb) = each %hook) {
602 my $htype = $HOOKTYPE{uc $name}; 1078 my $htype = $HOOKTYPE{uc $name};
603 defined $htype 1079 defined $htype
604 or Carp::croak "unsupported hook type '$name'"; 1080 or Carp::croak "unsupported hook type '$name'";
605 1081
1082 $self->set_should_invoke ($htype, +1)
606 unless (exists $self->{term}{_hook}[$htype]{$pkg}) { 1083 unless exists $self->{term}{_hook}[$htype]{$pkg};
607 $hook_count[$htype]++
608 or urxvt::set_should_invoke $htype, 1;
609 }
610 1084
611 $self->{term}{_hook}[$htype]{$pkg} = $cb; 1085 $self->{term}{_hook}[$htype]{$pkg} = $cb;
612 } 1086 }
613} 1087}
614 1088
619 for my $name (@hook) { 1093 for my $name (@hook) {
620 my $htype = $HOOKTYPE{uc $name}; 1094 my $htype = $HOOKTYPE{uc $name};
621 defined $htype 1095 defined $htype
622 or Carp::croak "unsupported hook type '$name'"; 1096 or Carp::croak "unsupported hook type '$name'";
623 1097
1098 $self->set_should_invoke ($htype, -1)
624 if (delete $self->{term}{_hook}[$htype]{$pkg}) { 1099 if delete $self->{term}{_hook}[$htype]{$pkg};
625 --$hook_count[$htype]
626 or urxvt::set_should_invoke $htype, 0;
627 }
628 } 1100 }
629} 1101}
630 1102
631our $AUTOLOAD; 1103our $AUTOLOAD;
632 1104
663 1135
664=head2 The C<urxvt::anyevent> Class 1136=head2 The C<urxvt::anyevent> Class
665 1137
666The sole purpose of this class is to deliver an interface to the 1138The sole purpose of this class is to deliver an interface to the
667C<AnyEvent> module - any module using it will work inside urxvt without 1139C<AnyEvent> module - any module using it will work inside urxvt without
668further work. The only exception is that you cannot wait on condition 1140further programming. The only exception is that you cannot wait on
669variables, but non-blocking condvar use is ok. What this means is that you 1141condition variables, but non-blocking condvar use is ok. What this means
670cannot use blocking APIs, but the non-blocking variant should work. 1142is that you cannot use blocking APIs, but the non-blocking variant should
1143work.
671 1144
672=cut 1145=cut
673 1146
674our $VERSION = 1; 1147our $VERSION = '5.23';
675 1148
676$INC{"urxvt/anyevent.pm"} = 1; # mark us as there 1149$INC{"urxvt/anyevent.pm"} = 1; # mark us as there
677push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::]; 1150push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
678 1151
679sub timer { 1152sub timer {
681 1154
682 my $cb = $arg{cb}; 1155 my $cb = $arg{cb};
683 1156
684 urxvt::timer 1157 urxvt::timer
685 ->new 1158 ->new
686 ->start (urxvt::NOW + $arg{after}) 1159 ->after ($arg{after}, $arg{interval})
687 ->cb (sub { 1160 ->cb ($arg{interval} ? $cb : sub {
688 $_[0]->stop; # need to cancel manually 1161 $_[0]->stop; # need to cancel manually
689 $cb->(); 1162 $cb->();
690 }) 1163 })
691} 1164}
692 1165
693sub io { 1166sub io {
694 my ($class, %arg) = @_; 1167 my ($class, %arg) = @_;
695 1168
696 my $cb = $arg{cb}; 1169 my $cb = $arg{cb};
1170 my $fd = fileno $arg{fh};
1171 defined $fd or $fd = $arg{fh};
697 1172
698 bless [$arg{fh}, urxvt::iow 1173 bless [$arg{fh}, urxvt::iow
699 ->new 1174 ->new
700 ->fd (fileno $arg{fh}) 1175 ->fd ($fd)
701 ->events (($arg{poll} =~ /r/ ? 1 : 0) 1176 ->events (($arg{poll} =~ /r/ ? 1 : 0)
702 | ($arg{poll} =~ /w/ ? 2 : 0)) 1177 | ($arg{poll} =~ /w/ ? 2 : 0))
703 ->start 1178 ->start
704 ->cb (sub { 1179 ->cb ($cb)
705 $cb->(($_[1] & 1 ? 'r' : '')
706 . ($_[1] & 2 ? 'w' : ''));
707 })],
708 urxvt::anyevent:: 1180 ], urxvt::anyevent::
1181}
1182
1183sub idle {
1184 my ($class, %arg) = @_;
1185
1186 my $cb = $arg{cb};
1187
1188 urxvt::iw
1189 ->new
1190 ->start
1191 ->cb ($cb)
1192}
1193
1194sub child {
1195 my ($class, %arg) = @_;
1196
1197 my $cb = $arg{cb};
1198
1199 urxvt::pw
1200 ->new
1201 ->start ($arg{pid})
1202 ->cb (sub {
1203 $_[0]->stop; # need to cancel manually
1204 $cb->($_[0]->rpid, $_[0]->rstatus);
1205 })
709} 1206}
710 1207
711sub DESTROY { 1208sub DESTROY {
712 $_[0][1]->stop; 1209 $_[0][1]->stop;
713} 1210}
714 1211
715sub condvar { 1212sub one_event {
716 bless \my $flag, urxvt::anyevent::condvar::
717}
718
719sub urxvt::anyevent::condvar::broadcast {
720 ${$_[0]}++;
721}
722
723sub urxvt::anyevent::condvar::wait {
724 unless (${$_[0]}) {
725 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API"; 1213 Carp::croak "AnyEvent->one_event blocking wait unsupported in urxvt, use a non-blocking API";
726 }
727} 1214}
728 1215
729package urxvt::term; 1216package urxvt::term;
730 1217
731=head2 The C<urxvt::term> Class 1218=head2 The C<urxvt::term> Class
736 1223
737# find on_xxx subs in the package and register them 1224# find on_xxx subs in the package and register them
738# as hooks 1225# as hooks
739sub register_package { 1226sub register_package {
740 my ($self, $pkg, $argv) = @_; 1227 my ($self, $pkg, $argv) = @_;
1228
1229 no strict 'refs';
1230
1231 urxvt::verbose 6, "register package $pkg to $self";
1232
1233 @{"$pkg\::ISA"} = urxvt::term::extension::;
741 1234
742 my $proxy = bless { 1235 my $proxy = bless {
743 _pkg => $pkg, 1236 _pkg => $pkg,
744 argv => $argv, 1237 argv => $argv,
745 }, $pkg; 1238 }, $pkg;
752 $proxy->enable ($name => $ref); 1245 $proxy->enable ($name => $ref);
753 } 1246 }
754 } 1247 }
755} 1248}
756 1249
1250=item $term = new urxvt::term $envhashref, $rxvtname, [arg...]
1251
1252Creates a new terminal, very similar as if you had started it with system
1253C<$rxvtname, arg...>. C<$envhashref> must be a reference to a C<%ENV>-like
1254hash which defines the environment of the new terminal.
1255
1256Croaks (and probably outputs an error message) if the new instance
1257couldn't be created. Returns C<undef> if the new instance didn't
1258initialise perl, and the terminal object otherwise. The C<init> and
1259C<start> hooks will be called before this call returns, and are free to
1260refer to global data (which is race free).
1261
1262=cut
1263
1264sub new {
1265 my ($class, $env, @args) = @_;
1266
1267 $env or Carp::croak "environment hash missing in call to urxvt::term->new";
1268 @args or Carp::croak "name argument missing in call to urxvt::term->new";
1269
1270 _new ([ map "$_=$env->{$_}", keys %$env ], \@args);
1271}
1272
757=item $term->destroy 1273=item $term->destroy
758 1274
759Destroy the terminal object (close the window, free resources etc.). 1275Destroy the terminal object (close the window, free resources
1276etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event
1277watchers (timers, io watchers) are still active.
1278
1279=item $term->exec_async ($cmd[, @args])
1280
1281Works like the combination of the C<fork>/C<exec> builtins, which executes
1282("starts") programs in the background. This function takes care of setting
1283the user environment before exec'ing the command (e.g. C<PATH>) and should
1284be preferred over explicit calls to C<exec> or C<system>.
1285
1286Returns the pid of the subprocess or C<undef> on error.
1287
1288=cut
1289
1290sub exec_async {
1291 my $self = shift;
1292
1293 my $pid = fork;
1294
1295 return $pid
1296 if !defined $pid or $pid;
1297
1298 %ENV = %{ $self->env };
1299
1300 exec @_;
1301 urxvt::_exit 255;
1302}
760 1303
761=item $isset = $term->option ($optval[, $set]) 1304=item $isset = $term->option ($optval[, $set])
762 1305
763Returns true if the option specified by C<$optval> is enabled, and 1306Returns true if the option specified by C<$optval> is enabled, and
764optionally change it. All option values are stored by name in the hash 1307optionally change it. All option values are stored by name in the hash
765C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash. 1308C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
766 1309
767Here is a a likely non-exhaustive list of option names, please see the 1310Here is a likely non-exhaustive list of option names, please see the
768source file F</src/optinc.h> to see the actual list: 1311source file F</src/optinc.h> to see the actual list:
769 1312
770 borderLess console cursorBlink cursorUnderline hold iconic insecure 1313 borderLess buffered console cursorBlink cursorUnderline hold iconic
771 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 1314 insecure intensityStyles iso14755 iso14755_52 jumpScroll loginShell
1315 mapAlert meta8 mouseWheelScrollPage override-redirect pastableTabs
772 pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating 1316 pointerBlank reverseVideo scrollBar scrollBar_floating scrollBar_right
773 scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer 1317 scrollTtyKeypress scrollTtyOutput scrollWithBuffer secondaryScreen
774 secondaryScreen secondaryScroll skipBuiltinGlyphs transparent 1318 secondaryScroll skipBuiltinGlyphs skipScroll transparent tripleclickwords
775 tripleclickwords utmpInhibit visualBell 1319 urgentOnBell utmpInhibit visualBell
776 1320
777=item $value = $term->resource ($name[, $newval]) 1321=item $value = $term->resource ($name[, $newval])
778 1322
779Returns the current resource value associated with a given name and 1323Returns the current resource value associated with a given name and
780optionally sets a new value. Setting values is most useful in the C<init> 1324optionally sets a new value. Setting values is most useful in the C<init>
789likely change). 1333likely change).
790 1334
791Please note that resource strings will currently only be freed when the 1335Please note that resource strings will currently only be freed when the
792terminal is destroyed, so changing options frequently will eat memory. 1336terminal is destroyed, so changing options frequently will eat memory.
793 1337
794Here is a a likely non-exhaustive list of resource names, not all of which 1338Here is a likely non-exhaustive list of resource names, not all of which
795are supported in every build, please see the source file F</src/rsinc.h> 1339are supported in every build, please see the source file F</src/rsinc.h>
796to see the actual list: 1340to see the actual list:
797 1341
798 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1342 answerbackstring backgroundPixmap backspace_key blendtype blurradius
799 borderLess color cursorBlink cursorUnderline cutchars delete_key 1343 boldFont boldItalicFont borderLess buffered chdir color cursorBlink
800 display_name embed ext_bwidth fade font geometry hold iconName 1344 cursorUnderline cutchars delete_key depth display_name embed ext_bwidth
801 imFont imLocale inputMethod insecure int_bwidth intensityStyles 1345 fade font geometry hold iconName iconfile imFont imLocale inputMethod
1346 insecure int_bwidth intensityStyles iso14755 iso14755_52 italicFont
802 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier 1347 jumpScroll letterSpace lineSpace loginShell mapAlert meta8 modifier
803 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2 1348 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
804 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 1349 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
805 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 1350 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
806 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 1351 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
807 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 1352 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
808 shade term_name title transparent transparent_all tripleclickwords 1353 secondaryScreen secondaryScroll shade skipBuiltinGlyphs skipScroll
1354 term_name title transient_for transparent tripleclickwords urgentOnBell
809 utmpInhibit visualBell 1355 utmpInhibit visualBell
810 1356
811=cut 1357=cut
812 1358
813sub resource($$;$) { 1359sub resource($$;$) {
814 my ($self, $name) = (shift, shift); 1360 my ($self, $name) = (shift, shift);
815 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 1361 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
816 &urxvt::term::_resource 1362 goto &urxvt::term::_resource
817} 1363}
1364
1365=item $value = $term->x_resource ($pattern)
1366
1367Returns the X-Resource for the given pattern, excluding the program or
1368class name, i.e. C<< $term->x_resource ("boldFont") >> should return the
1369same value as used by this instance of rxvt-unicode. Returns C<undef> if no
1370resource with that pattern exists.
1371
1372This method should only be called during the C<on_start> hook, as there is
1373only one resource database per display, and later invocations might return
1374the wrong resources.
818 1375
819=item $success = $term->parse_keysym ($keysym_spec, $command_string) 1376=item $success = $term->parse_keysym ($keysym_spec, $command_string)
820 1377
821Adds a keymap translation exactly as specified via a resource. See the 1378Adds a keymap translation exactly as specified via a resource. See the
822C<keysym> resource in the @@RXVT_NAME@@(1) manpage. 1379C<keysym> resource in the @@RXVT_NAME@@(1) manpage.
835 1392
836=item ($row, $col) = $term->selection_beg ([$row, $col]) 1393=item ($row, $col) = $term->selection_beg ([$row, $col])
837 1394
838=item ($row, $col) = $term->selection_end ([$row, $col]) 1395=item ($row, $col) = $term->selection_end ([$row, $col])
839 1396
840Return the current values of the selection mark, begin or end positions, 1397Return the current values of the selection mark, begin or end positions.
841and optionally set them to new values.
842 1398
1399When arguments are given, then the selection coordinates are set to
1400C<$row> and C<$col>, and the selection screen is set to the current
1401screen.
1402
1403=item $screen = $term->selection_screen ([$screen])
1404
1405Returns the current selection screen, and then optionally sets it.
1406
1407=item $term->selection_make ($eventtime[, $rectangular])
1408
1409Tries to make a selection as set by C<selection_beg> and
1410C<selection_end>. If C<$rectangular> is true (default: false), a
1411rectangular selection will be made. This is the preferred function to make
1412a selection.
1413
843=item $success = $term->selection_grab ($eventtime) 1414=item $success = $term->selection_grab ($eventtime[, $clipboard])
844 1415
845Try to request the primary selection from the server (for example, as set 1416Try to acquire ownership of the primary (clipboard if C<$clipboard> is
846by the next method). 1417true) selection from the server. The corresponding text can be set
1418with the next method. No visual feedback will be given. This function
1419is mostly useful from within C<on_sel_grab> hooks.
847 1420
848=item $oldtext = $term->selection ([$newtext]) 1421=item $oldtext = $term->selection ([$newtext, $clipboard])
849 1422
850Return the current selection text and optionally replace it by C<$newtext>. 1423Return the current selection (clipboard if C<$clipboard> is true) text
1424and optionally replace it by C<$newtext>.
1425
1426=item $term->selection_clear ([$clipboard])
1427
1428Revoke ownership of the primary (clipboard if C<$clipboard> is true) selection.
851 1429
852=item $term->overlay_simple ($x, $y, $text) 1430=item $term->overlay_simple ($x, $y, $text)
853 1431
854Create a simple multi-line overlay box. See the next method for details. 1432Create a simple multi-line overlay box. See the next method for details.
855 1433
885 1463
886The methods currently supported on C<urxvt::overlay> objects are: 1464The methods currently supported on C<urxvt::overlay> objects are:
887 1465
888=over 4 1466=over 4
889 1467
890=item $overlay->set ($x, $y, $text, $rend) 1468=item $overlay->set ($x, $y, $text[, $rend])
891 1469
892Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts 1470Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts
893text in rxvt-unicode's special encoding and an array of rendition values 1471text in rxvt-unicode's special encoding and an array of rendition values
894at a specific position inside the overlay. 1472at a specific position inside the overlay.
1473
1474If C<$rend> is missing, then the rendition will not be changed.
895 1475
896=item $overlay->hide 1476=item $overlay->hide
897 1477
898If visible, hide the overlay, but do not destroy it. 1478If visible, hide the overlay, but do not destroy it.
899 1479
944Convert the given locale-encoded octets into a perl string. 1524Convert the given locale-encoded octets into a perl string.
945 1525
946=item $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle]) 1526=item $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
947 1527
948XORs the rendition values in the given span with the provided value 1528XORs the rendition values in the given span with the provided value
949(default: C<RS_RVid>). Useful in refresh hooks to provide effects similar 1529(default: C<RS_RVid>), which I<MUST NOT> contain font styles. Useful in
950to the selection. 1530refresh hooks to provide effects similar to the selection.
951 1531
952=item $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, $rstyle2]]) 1532=item $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, $rstyle2]])
953 1533
954Similar to C<scr_xor_span>, but xors a rectangle instead. Trailing 1534Similar to C<scr_xor_span>, but xors a rectangle instead. Trailing
955whitespace will additionally be xored with the C<$rstyle2>, which defaults 1535whitespace will additionally be xored with the C<$rstyle2>, which defaults
956to C<RS_RVid | RS_Uline>, which removes reverse video again and underlines 1536to C<RS_RVid | RS_Uline>, which removes reverse video again and underlines
957it instead. 1537it instead. Both styles I<MUST NOT> contain font styles.
958 1538
959=item $term->scr_bell 1539=item $term->scr_bell
960 1540
961Ring the bell! 1541Ring the bell!
962 1542
969 1549
970Normally its not a good idea to use this function, as programs might be 1550Normally its not a good idea to use this function, as programs might be
971confused by changes in cursor position or scrolling. Its useful inside a 1551confused by changes in cursor position or scrolling. Its useful inside a
972C<on_add_lines> hook, though. 1552C<on_add_lines> hook, though.
973 1553
1554=item $term->scr_change_screen ($screen)
1555
1556Switch to given screen - 0 primary, 1 secondary.
1557
974=item $term->cmd_parse ($octets) 1558=item $term->cmd_parse ($octets)
975 1559
976Similar to C<scr_add_lines>, but the argument must be in the 1560Similar to C<scr_add_lines>, but the argument must be in the
977locale-specific encoding of the terminal and can contain command sequences 1561locale-specific encoding of the terminal and can contain command sequences
978(escape codes) that will be interpreted. 1562(escape codes) that will be interpreted.
979 1563
980=item $term->tt_write ($octets) 1564=item $term->tt_write ($octets)
981 1565
982Write the octets given in C<$data> to the tty (i.e. as program input). To 1566Write the octets given in C<$octets> to the tty (i.e. as program input). To
983pass characters instead of octets, you should convert your strings first 1567pass characters instead of octets, you should convert your strings first
984to the locale-specific encoding using C<< $term->locale_encode >>. 1568to the locale-specific encoding using C<< $term->locale_encode >>.
1569
1570=item $term->tt_paste ($octets)
1571
1572Write the octets given in C<$octets> to the tty as a paste, converting NL to
1573CR and bracketing the data with control sequences if bracketed paste mode
1574is set.
985 1575
986=item $old_events = $term->pty_ev_events ([$new_events]) 1576=item $old_events = $term->pty_ev_events ([$new_events])
987 1577
988Replaces the event mask of the pty watcher by the given event mask. Can 1578Replaces the event mask of the pty watcher by the given event mask. Can
989be used to suppress input and output handling to the pty/tty. See the 1579be used to suppress input and output handling to the pty/tty. See the
990description of C<< urxvt::timer->events >>. Make sure to always restore 1580description of C<< urxvt::timer->events >>. Make sure to always restore
991the previous value. 1581the previous value.
992 1582
1583=item $fd = $term->pty_fd
1584
1585Returns the master file descriptor for the pty in use, or C<-1> if no pty
1586is used.
1587
993=item $windowid = $term->parent 1588=item $windowid = $term->parent
994 1589
995Return the window id of the toplevel window. 1590Return the window id of the toplevel window.
996 1591
997=item $windowid = $term->vt 1592=item $windowid = $term->vt
998 1593
999Return the window id of the terminal window. 1594Return the window id of the terminal window.
1000 1595
1596=item $term->vt_emask_add ($x_event_mask)
1597
1598Adds the specified events to the vt event mask. Useful e.g. when you want
1599to receive pointer events all the times:
1600
1601 $term->vt_emask_add (urxvt::PointerMotionMask);
1602
1603=item $term->focus_in
1604
1605=item $term->focus_out
1606
1607=item $term->key_press ($state, $keycode[, $time])
1608
1609=item $term->key_release ($state, $keycode[, $time])
1610
1611Deliver various fake events to to terminal.
1612
1001=item $window_width = $term->width 1613=item $window_width = $term->width
1002 1614
1003=item $window_height = $term->height 1615=item $window_height = $term->height
1004 1616
1005=item $font_width = $term->fwidth 1617=item $font_width = $term->fwidth
1018 1630
1019=item $max_scrollback = $term->saveLines 1631=item $max_scrollback = $term->saveLines
1020 1632
1021=item $nrow_plus_saveLines = $term->total_rows 1633=item $nrow_plus_saveLines = $term->total_rows
1022 1634
1023=item $lines_in_scrollback = $term->nsaved 1635=item $topmost_scrollback_row = $term->top_row
1024 1636
1025Return various integers describing terminal characteristics. 1637Return various integers describing terminal characteristics.
1026 1638
1639=item $x_display = $term->display_id
1640
1641Return the DISPLAY used by rxvt-unicode.
1642
1027=item $lc_ctype = $term->locale 1643=item $lc_ctype = $term->locale
1028 1644
1029Returns the LC_CTYPE category string used by this rxvt-unicode. 1645Returns the LC_CTYPE category string used by this rxvt-unicode.
1030 1646
1031=item $x_display = $term->display_id 1647=item $env = $term->env
1032 1648
1033Return the DISPLAY used by rxvt-unicode. 1649Returns a copy of the environment in effect for the terminal as a hashref
1650similar to C<\%ENV>.
1651
1652=item @envv = $term->envv
1653
1654Returns the environment as array of strings of the form C<VAR=VALUE>.
1655
1656=item @argv = $term->argv
1657
1658Return the argument vector as this terminal, similar to @ARGV, but
1659includes the program name as first element.
1660
1661=cut
1662
1663sub env {
1664 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), $_[0]->envv }
1665}
1034 1666
1035=item $modifiermask = $term->ModLevel3Mask 1667=item $modifiermask = $term->ModLevel3Mask
1036 1668
1037=item $modifiermask = $term->ModMetaMask 1669=item $modifiermask = $term->ModMetaMask
1038 1670
1039=item $modifiermask = $term->ModNumLockMask 1671=item $modifiermask = $term->ModNumLockMask
1040 1672
1041Return the modifier masks corresponding to the "ISO Level 3 Shift" (often 1673Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
1042AltGr), the meta key (often Alt) and the num lock key, if applicable. 1674AltGr), the meta key (often Alt) and the num lock key, if applicable.
1043 1675
1676=item $screen = $term->current_screen
1677
1678Returns the currently displayed screen (0 primary, 1 secondary).
1679
1680=item $cursor_is_hidden = $term->hidden_cursor
1681
1682Returns whether the cursor is currently hidden or not.
1683
1044=item $view_start = $term->view_start ([$newvalue]) 1684=item $view_start = $term->view_start ([$newvalue])
1045 1685
1046Returns the negative row number of the topmost line. Minimum value is 1686Returns the row number of the topmost displayed line. Maximum value is
1047C<0>, which displays the normal terminal contents. Larger values scroll 1687C<0>, which displays the normal terminal contents. Lower values scroll
1048this many lines into the scrollback buffer. 1688this many lines into the scrollback buffer.
1049 1689
1050=item $term->want_refresh 1690=item $term->want_refresh
1051 1691
1052Requests a screen refresh. At the next opportunity, rxvt-unicode will 1692Requests a screen refresh. At the next opportunity, rxvt-unicode will
1055 1695
1056Used after changing terminal contents to display them. 1696Used after changing terminal contents to display them.
1057 1697
1058=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]]) 1698=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
1059 1699
1060Returns the text of the entire row with number C<$row_number>. Row C<0> 1700Returns the text of the entire row with number C<$row_number>. Row C<< $term->top_row >>
1061is the topmost terminal line, row C<< $term->$ncol-1 >> is the bottommost 1701is the topmost terminal line, row C<< $term->nrow-1 >> is the bottommost
1062terminal line. The scrollback buffer starts at line C<-1> and extends to
1063line C<< -$term->nsaved >>. Nothing will be returned if a nonexistent line 1702terminal line. Nothing will be returned if a nonexistent line
1064is requested. 1703is requested.
1065 1704
1066If C<$new_text> is specified, it will replace characters in the current 1705If C<$new_text> is specified, it will replace characters in the current
1067line, starting at column C<$start_col> (default C<0>), which is useful 1706line, starting at column C<$start_col> (default C<0>), which is useful
1068to replace only parts of a line. The font index in the rendition will 1707to replace only parts of a line. The font index in the rendition will
1069automatically be updated. 1708automatically be updated.
1070 1709
1071C<$text> is in a special encoding: tabs and wide characters that use more 1710C<$text> is in a special encoding: tabs and wide characters that use more
1072than one cell when displayed are padded with urxvt::NOCHAR characters 1711than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535)
1073(C<chr 65535>). Characters with combining characters and other characters 1712characters. Characters with combining characters and other characters that
1074that do not fit into the normal tetx encoding will be replaced with 1713do not fit into the normal text encoding will be replaced with characters
1075characters in the private use area. 1714in the private use area.
1076 1715
1077You have to obey this encoding when changing text. The advantage is 1716You have to obey this encoding when changing text. The advantage is
1078that C<substr> and similar functions work on screen cells and not on 1717that C<substr> and similar functions work on screen cells and not on
1079characters. 1718characters.
1080 1719
1131Return the row number of the first/last row of the line, respectively. 1770Return the row number of the first/last row of the line, respectively.
1132 1771
1133=item $offset = $line->offset_of ($row, $col) 1772=item $offset = $line->offset_of ($row, $col)
1134 1773
1135Returns the character offset of the given row|col pair within the logical 1774Returns the character offset of the given row|col pair within the logical
1136line. 1775line. Works for rows outside the line, too, and returns corresponding
1776offsets outside the string.
1137 1777
1138=item ($row, $col) = $line->coord_of ($offset) 1778=item ($row, $col) = $line->coord_of ($offset)
1139 1779
1140Translates a string offset into terminal coordinates again. 1780Translates a string offset into terminal coordinates again.
1141 1781
1223where one character corresponds to one screen cell. See 1863where one character corresponds to one screen cell. See
1224C<< $term->ROW_t >> for details. 1864C<< $term->ROW_t >> for details.
1225 1865
1226=item $string = $term->special_decode $text 1866=item $string = $term->special_decode $text
1227 1867
1228Converts rxvt-unicodes text reprsentation into a perl string. See 1868Converts rxvt-unicodes text representation into a perl string. See
1229C<< $term->ROW_t >> for details. 1869C<< $term->ROW_t >> for details.
1230 1870
1231=item $success = $term->grab_button ($button, $modifiermask) 1871=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1232 1872
1873=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1874
1233Registers a synchronous button grab. See the XGrabButton manpage. 1875Register/unregister a synchronous button grab. See the XGrabButton
1876manpage.
1234 1877
1235=item $success = $term->grab ($eventtime[, $sync]) 1878=item $success = $term->grab ($eventtime[, $sync])
1236 1879
1237Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1880Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1238synchronous (C<$sync> is true). Also remembers the grab timestampe. 1881synchronous (C<$sync> is true). Also remembers the grab timestamp.
1239 1882
1240=item $term->allow_events_async 1883=item $term->allow_events_async
1241 1884
1242Calls XAllowEvents with AsyncBoth for the most recent grab. 1885Calls XAllowEvents with AsyncBoth for the most recent grab.
1243 1886
1250Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most 1893Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most
1251recent grab. 1894recent grab.
1252 1895
1253=item $term->ungrab 1896=item $term->ungrab
1254 1897
1255Calls XUngrab for the most recent grab. Is called automatically on 1898Calls XUngrabPointer and XUngrabKeyboard for the most recent grab. Is called automatically on
1256evaluation errors, as it is better to lose the grab in the error case as 1899evaluation errors, as it is better to lose the grab in the error case as
1257the session. 1900the session.
1901
1902=item $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
1903
1904=item $atom_name = $term->XGetAtomName ($atom)
1905
1906=item @atoms = $term->XListProperties ($window)
1907
1908=item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
1909
1910=item $term->XChangeProperty ($window, $property, $type, $format, $octets)
1911
1912=item $term->XDeleteProperty ($window, $property)
1913
1914=item $window = $term->DefaultRootWindow
1915
1916=item $term->XReparentWindow ($window, $parent, [$x, $y])
1917
1918=item $term->XMapWindow ($window)
1919
1920=item $term->XUnmapWindow ($window)
1921
1922=item $term->XMoveResizeWindow ($window, $x, $y, $width, $height)
1923
1924=item ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x, $y)
1925
1926=item $term->XChangeInput ($window, $add_events[, $del_events])
1927
1928Various X or X-related functions. The C<$term> object only serves as
1929the source of the display, otherwise those functions map more-or-less
1930directly onto the X functions of the same name.
1258 1931
1259=back 1932=back
1260 1933
1261=cut 1934=cut
1262 1935
1277 1950
1278 $item->{render} ||= sub { $_[0]{text} }; 1951 $item->{render} ||= sub { $_[0]{text} };
1279 1952
1280 push @{ $self->{item} }, $item; 1953 push @{ $self->{item} }, $item;
1281} 1954}
1955
1956=item $popup->add_title ($title)
1957
1958Adds a non-clickable title to the popup.
1959
1960=cut
1961
1962sub add_title {
1963 my ($self, $title) = @_;
1964
1965 $self->add_item ({
1966 rend => { normal => "\x1b[38;5;11;44m", hover => "\x1b[38;5;11;44m", active => "\x1b[38;5;11;44m" },
1967 text => $title,
1968 activate => sub { },
1969 });
1970}
1971
1972=item $popup->add_separator ([$sepchr])
1973
1974Creates a separator, optionally using the character given as C<$sepchr>.
1975
1976=cut
1282 1977
1283sub add_separator { 1978sub add_separator {
1284 my ($self, $sep) = @_; 1979 my ($self, $sep) = @_;
1285 1980
1286 $sep ||= "="; 1981 $sep ||= "=";
1291 render => sub { $sep x $self->{term}->ncol }, 1986 render => sub { $sep x $self->{term}->ncol },
1292 activate => sub { }, 1987 activate => sub { },
1293 }); 1988 });
1294} 1989}
1295 1990
1296sub add_title { 1991=item $popup->add_button ($text, $cb)
1297 my ($self, $title) = @_;
1298 1992
1299 $self->add_item ({ 1993Adds a clickable button to the popup. C<$cb> is called whenever it is
1300 rend => { normal => "\x1b[38;5;11;44m", hover => "\x1b[38;5;11;44m", active => "\x1b[38;5;11;44m" }, 1994selected.
1301 text => $title, 1995
1302 activate => sub { }, 1996=cut
1303 });
1304}
1305 1997
1306sub add_button { 1998sub add_button {
1307 my ($self, $text, $cb) = @_; 1999 my ($self, $text, $cb) = @_;
1308 2000
1309 $self->add_item ({ type => "button", text => $text, activate => $cb}); 2001 $self->add_item ({ type => "button", text => $text, activate => $cb});
1310} 2002}
1311 2003
2004=item $popup->add_toggle ($text, $initial_value, $cb)
2005
2006Adds a toggle/checkbox item to the popup. The callback gets called
2007whenever it gets toggled, with a boolean indicating its new value as its
2008first argument.
2009
2010=cut
2011
1312sub add_toggle { 2012sub add_toggle {
1313 my ($self, $text, $cb, $value) = @_; 2013 my ($self, $text, $value, $cb) = @_;
1314 2014
1315 my $item; $item = { 2015 my $item; $item = {
1316 type => "button", 2016 type => "button",
1317 text => " $text", 2017 text => " $text",
1318 value => $value, 2018 value => $value,
1319 render => sub { ($_[0]{value} ? "* " : " ") . $text }, 2019 render => sub { ($_[0]{value} ? "* " : " ") . $text },
1320 activate => sub { $cb->($_[0]{value} = !$_[0]{value}); }, 2020 activate => sub { $cb->($_[1]{value} = !$_[1]{value}); },
1321 }; 2021 };
1322 2022
1323 $self->add_item ($item); 2023 $self->add_item ($item);
1324} 2024}
2025
2026=item $popup->show
2027
2028Displays the popup (which is initially hidden).
2029
2030=cut
1325 2031
1326sub show { 2032sub show {
1327 my ($self) = @_; 2033 my ($self) = @_;
1328 2034
1329 local $urxvt::popup::self = $self; 2035 local $urxvt::popup::self = $self;
1330 2036
2037 my $env = $self->{term}->env;
2038 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
2039 delete $env->{LC_ALL};
1331 local $ENV{LC_ALL} = $self->{term}->locale; 2040 $env->{LC_CTYPE} = $self->{term}->locale;
1332 2041
1333 urxvt->new ("--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0, 2042 my $term = urxvt::term->new (
2043 $env, "popup",
2044 "--perl-lib" => "", "--perl-ext-common" => "",
2045 "-pty-fd" => -1, "-sl" => 0,
2046 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect",
1334 "--transient-for" => $self->{term}->parent, 2047 "--transient-for" => $self->{term}->parent,
1335 "-display" => $self->{term}->display_id, 2048 "-display" => $self->{term}->display_id,
1336 "-pe" => "urxvt-popup") 2049 "-pe" => "urxvt-popup",
1337 or die "unable to create popup window\n"; 2050 ) or die "unable to create popup window\n";
2051
2052 unless (delete $term->{urxvt_popup_init_done}) {
2053 $term->ungrab;
2054 $term->destroy;
2055 die "unable to initialise popup window\n";
2056 }
1338} 2057}
1339 2058
1340sub DESTROY { 2059sub DESTROY {
1341 my ($self) = @_; 2060 my ($self) = @_;
1342 2061
1343 delete $self->{term}{_destroy}{$self}; 2062 delete $self->{term}{_destroy}{$self};
1344 $self->{term}->ungrab; 2063 $self->{term}->ungrab;
1345} 2064}
2065
2066=back
2067
2068=cut
2069
2070package urxvt::watcher;
1346 2071
1347=head2 The C<urxvt::timer> Class 2072=head2 The C<urxvt::timer> Class
1348 2073
1349This class implements timer watchers/events. Time is represented as a 2074This class implements timer watchers/events. Time is represented as a
1350fractional number of seconds since the epoch. Example: 2075fractional number of seconds since the epoch. Example:
1354 ->new 2079 ->new
1355 ->interval (1) 2080 ->interval (1)
1356 ->cb (sub { 2081 ->cb (sub {
1357 $term->{overlay}->set (0, 0, 2082 $term->{overlay}->set (0, 0,
1358 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]); 2083 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
1359 }); 2084 });
1360 2085
1361=over 4 2086=over 4
1362 2087
1363=item $timer = new urxvt::timer 2088=item $timer = new urxvt::timer
1364 2089
1367 2092
1368=item $timer = $timer->cb (sub { my ($timer) = @_; ... }) 2093=item $timer = $timer->cb (sub { my ($timer) = @_; ... })
1369 2094
1370Set the callback to be called when the timer triggers. 2095Set the callback to be called when the timer triggers.
1371 2096
1372=item $tstamp = $timer->at
1373
1374Return the time this watcher will fire next.
1375
1376=item $timer = $timer->set ($tstamp) 2097=item $timer = $timer->set ($tstamp[, $interval])
1377 2098
1378Set the time the event is generated to $tstamp. 2099Set the time the event is generated to $tstamp (and optionally specifies a
2100new $interval).
1379 2101
1380=item $timer = $timer->interval ($interval) 2102=item $timer = $timer->interval ($interval)
1381 2103
1382Normally (and when C<$interval> is C<0>), the timer will automatically 2104By default (and when C<$interval> is C<0>), the timer will automatically
1383stop after it has fired once. If C<$interval> is non-zero, then the timer 2105stop after it has fired once. If C<$interval> is non-zero, then the timer
1384is automatically rescheduled at the given intervals. 2106is automatically rescheduled at the given intervals.
1385 2107
1386=item $timer = $timer->start 2108=item $timer = $timer->start
1387 2109
1388Start the timer. 2110Start the timer.
1389 2111
1390=item $timer = $timer->start ($tstamp) 2112=item $timer = $timer->start ($tstamp[, $interval])
1391 2113
1392Set the event trigger time to C<$tstamp> and start the timer. 2114Set the event trigger time to C<$tstamp> and start the timer. Optionally
2115also replaces the interval.
2116
2117=item $timer = $timer->after ($delay[, $interval])
2118
2119Like C<start>, but sets the expiry timer to c<urxvt::NOW + $delay>.
1393 2120
1394=item $timer = $timer->stop 2121=item $timer = $timer->stop
1395 2122
1396Stop the timer. 2123Stop the timer.
1397 2124
1403 2130
1404 $term->{socket} = ... 2131 $term->{socket} = ...
1405 $term->{iow} = urxvt::iow 2132 $term->{iow} = urxvt::iow
1406 ->new 2133 ->new
1407 ->fd (fileno $term->{socket}) 2134 ->fd (fileno $term->{socket})
1408 ->events (urxvt::EVENT_READ) 2135 ->events (urxvt::EV_READ)
1409 ->start 2136 ->start
1410 ->cb (sub { 2137 ->cb (sub {
1411 my ($iow, $revents) = @_; 2138 my ($iow, $revents) = @_;
1412 # $revents must be 1 here, no need to check 2139 # $revents must be 1 here, no need to check
1413 sysread $term->{socket}, my $buf, 8192 2140 sysread $term->{socket}, my $buf, 8192
1426Set the callback to be called when io events are triggered. C<$reventmask> 2153Set the callback to be called when io events are triggered. C<$reventmask>
1427is a bitset as described in the C<events> method. 2154is a bitset as described in the C<events> method.
1428 2155
1429=item $iow = $iow->fd ($fd) 2156=item $iow = $iow->fd ($fd)
1430 2157
1431Set the filedescriptor (not handle) to watch. 2158Set the file descriptor (not handle) to watch.
1432 2159
1433=item $iow = $iow->events ($eventmask) 2160=item $iow = $iow->events ($eventmask)
1434 2161
1435Set the event mask to watch. The only allowed values are 2162Set the event mask to watch. The only allowed values are
1436C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed 2163C<urxvt::EV_READ> and C<urxvt::EV_WRITE>, which might be ORed
1437together, or C<urxvt::EVENT_NONE>. 2164together, or C<urxvt::EV_NONE>.
1438 2165
1439=item $iow = $iow->start 2166=item $iow = $iow->start
1440 2167
1441Start watching for requested events on the given handle. 2168Start watching for requested events on the given handle.
1442 2169
1443=item $iow = $iow->stop 2170=item $iow = $iow->stop
1444 2171
1445Stop watching for events on the given filehandle. 2172Stop watching for events on the given file handle.
2173
2174=back
2175
2176=head2 The C<urxvt::iw> Class
2177
2178This class implements idle watchers, that get called automatically when
2179the process is idle. They should return as fast as possible, after doing
2180some useful work.
2181
2182=over 4
2183
2184=item $iw = new urxvt::iw
2185
2186Create a new idle watcher object in stopped state.
2187
2188=item $iw = $iw->cb (sub { my ($iw) = @_; ... })
2189
2190Set the callback to be called when the watcher triggers.
2191
2192=item $timer = $timer->start
2193
2194Start the watcher.
2195
2196=item $timer = $timer->stop
2197
2198Stop the watcher.
2199
2200=back
2201
2202=head2 The C<urxvt::pw> Class
2203
2204This class implements process watchers. They create an event whenever a
2205process exits, after which they stop automatically.
2206
2207 my $pid = fork;
2208 ...
2209 $term->{pw} = urxvt::pw
2210 ->new
2211 ->start ($pid)
2212 ->cb (sub {
2213 my ($pw, $exit_status) = @_;
2214 ...
2215 });
2216
2217=over 4
2218
2219=item $pw = new urxvt::pw
2220
2221Create a new process watcher in stopped state.
2222
2223=item $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
2224
2225Set the callback to be called when the timer triggers.
2226
2227=item $pw = $timer->start ($pid)
2228
2229Tells the watcher to start watching for process C<$pid>.
2230
2231=item $pw = $pw->stop
2232
2233Stop the watcher.
1446 2234
1447=back 2235=back
1448 2236
1449=head1 ENVIRONMENT 2237=head1 ENVIRONMENT
1450 2238
1457 2245
1458=item == 0 - fatal messages 2246=item == 0 - fatal messages
1459 2247
1460=item >= 3 - script loading and management 2248=item >= 3 - script loading and management
1461 2249
1462=item >=10 - all events received 2250=item >=10 - all called hooks
2251
2252=item >=11 - hook return values
1463 2253
1464=back 2254=back
1465 2255
1466=head1 AUTHOR 2256=head1 AUTHOR
1467 2257
1468 Marc Lehmann <pcg@goof.com> 2258 Marc Lehmann <schmorp@schmorp.de>
1469 http://software.schmorp.de/pkg/rxvt-unicode 2259 http://software.schmorp.de/pkg/rxvt-unicode
1470 2260
1471=cut 2261=cut
1472 2262
14731 22631
2264
2265# vim: sw=3:

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines