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

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines