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

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines