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.39 by root, Fri Jan 6 05:28:55 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, 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 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.
315
316=item block-graphics-to-ascii
317
318A not very useful example of filtering all text output to the terminal
319by replacing all line-drawing characters (U+2500 .. U+259F) by a
320similar-looking ascii character.
321
61=item digital-clock 322=item digital-clock
62 323
63Displays a digital clock using the built-in overlay. 324Displays a digital clock using the built-in overlay.
64 325
65=item mark-urls 326=item remote-clipboard
66 327
67Uses per-line filtering (C<on_line_update>) to underline urls. 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.
68 393
69=item example-refresh-hooks 394=item example-refresh-hooks
70 395
71Displays 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
72window. Illustrates overwriting the refresh callbacks to create your own 397window. Illustrates overwriting the refresh callbacks to create your own
73overlays or changes. 398overlays or changes.
74 399
75=item example-filter-input 400=item confirm-paste
76 401
77A not very useful example of filtering all text output to the terminal, by 402Displays a confirmation dialog when a paste containing at least a full
78underlining all urls that matches a certain regex (i.e. some urls :). It 403line is detected.
79is not very useful because urls that are output in multiple steps (e.g.
80when typing them) do not get marked.
81 404
82=back 405=back
406
407=head1 API DOCUMENTATION
83 408
84=head2 General API Considerations 409=head2 General API Considerations
85 410
86All objects (such as terminals, time watchers etc.) are typical 411All objects (such as terminals, time watchers etc.) are typical
87reference-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
99 424
100=over 4 425=over 4
101 426
102=item $text 427=item $text
103 428
104Rxvt-unicodes special way of encoding text, where one "unicode" character 429Rxvt-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. 430always represents one screen cell. See L<ROW_t> for a discussion of this format.
106 431
107=item $string 432=item $string
108 433
109A 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
110characters and is to be distinguished with text encoded in a specific 435characters and is to be distinguished with text encoded in a specific
115Either binary data or - more common - a text string encoded in a 440Either binary data or - more common - a text string encoded in a
116locale-specific way. 441locale-specific way.
117 442
118=back 443=back
119 444
445=head2 Extension Objects
446
447Every perl extension is a perl class. A separate perl object is created
448for each terminal, and each terminal has its own set of extension objects,
449which are passed as the first parameter to hooks. So extensions can use
450their C<$self> object without having to think about clashes with other
451extensions or other terminals, with the exception of methods and members
452that begin with an underscore character C<_>: these are reserved for
453internal use.
454
455Although it isn't a C<urxvt::term> object, you can call all methods of the
456C<urxvt::term> class on this object.
457
458It has the following methods and data members:
459
460=over 4
461
462=item $urxvt_term = $self->{term}
463
464Returns the C<urxvt::term> object associated with this instance of the
465extension. This member I<must not> be changed in any way.
466
467=item $self->enable ($hook_name => $cb, [$hook_name => $cb..])
468
469Dynamically enable the given hooks (named without the C<on_> prefix) for
470this extension, replacing any previous hook. This is useful when you want
471to overwrite time-critical hooks only temporarily.
472
473=item $self->disable ($hook_name[, $hook_name..])
474
475Dynamically disable the given hooks.
476
477=back
478
120=head2 Hooks 479=head2 Hooks
121 480
122The following subroutines can be declared in loaded scripts, and will be 481The following subroutines can be declared in extension files, and will be
123called whenever the relevant event happens. 482called whenever the relevant event happens.
124 483
125The first argument passed to them is an object private to each terminal 484The 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 485the 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 486
131All of them must return a boolean value. If it is true, then the event 487B<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, 488hooks 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. 489relevant action might not be carried out by the C++ code.
134 490
135When in doubt, return a false value (preferably C<()>). 491I<< When in doubt, return a false value (preferably C<()>). >>
136 492
137=over 4 493=over 4
138 494
139=item on_init $term 495=item on_init $term
140 496
141Called after a new terminal object has been initialized, but before 497Called after a new terminal object has been initialized, but before
142windows 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
143call or deliver senseless data, as terminal size and other characteristics 499call or deliver senseless data, as terminal size and other characteristics
144have not yet been determined. You can safely query and change resources, 500have not yet been determined. You can safely query and change resources
145though. 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).
146 513
147=item on_reset $term 514=item on_reset $term
148 515
149Called 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
150control 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
151variables. 518variables.
152 519
153=item on_start $term 520=item on_child_start $term, $pid
154 521
155Called at the very end of initialisation of a new terminal, just before 522Called just after the child process has been C<fork>ed.
156returning 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>.
157 528
158=item on_sel_make $term, $eventtime 529=item on_sel_make $term, $eventtime
159 530
160Called 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
161selection 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
168 539
169Called whenever a selection has been copied, but before the selection is 540Called whenever a selection has been copied, but before the selection is
170requested from the server. The selection text can be queried and changed 541requested from the server. The selection text can be queried and changed
171by calling C<< $term->selection >>. 542by calling C<< $term->selection >>.
172 543
173Returning a true value aborts selection grabbing. It will still be hilighted. 544Returning a true value aborts selection grabbing. It will still be highlighted.
174 545
175=item on_sel_extend $term 546=item on_sel_extend $term
176 547
177Called 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
178click) and is either supposed to return false (normal operation), or 549click) and is either supposed to return false (normal operation), or
179should 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
180processing. 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.
181 554
182See the F<selection> example extension. 555See the F<selection> example extension.
183 556
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 557=item on_view_change $term, $offset
195 558
196Called whenever the view offset changes, i..e the user or program 559Called whenever the view offset changes, i.e. the user or program
197scrolls. Offset C<0> means display the normal terminal, positive values 560scrolls. Offset C<0> means display the normal terminal, positive values
198show this many lines of scrollback. 561show this many lines of scrollback.
199 562
200=item on_scroll_back $term, $lines, $saved 563=item on_scroll_back $term, $lines, $saved
201 564
205 568
206It 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,
207$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
208number of lines that will be in the scrollback buffer. 571number of lines that will be in the scrollback buffer.
209 572
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 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
215 584
216Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 585Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
217operating system command) is processed. Cursor position and other state 586operating system command) is processed. Cursor position and other state
218information is up-to-date when this happens. For interoperability, the 587information is up-to-date when this happens. For interoperability, the
219string should start with the extension name and a colon, to distinguish 588string should start with the extension name (sans -osc) and a semicolon,
220it from commands for other extensions, and this might be enforced in the 589to distinguish it from commands for other extensions, and this might be
221future. 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 }
222 601
223Be 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,
224as 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
225other 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.
226 608
227=item on_add_lines $term, $string 609=item on_add_lines $term, $string
228 610
229Called 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
230can 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
231and calling C<< $term->scr_add_lines >> yourself. Please note that this 613and 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 614might be very slow, however, as your hook is called for B<all> text being
233output. 615output.
234 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
235=item on_line_update $term, $row 629=item on_line_update $term, $row
236 630
237Called 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
238screen output (e.g. underline urls or other useless stuff). Only lines 632screen output (e.g. underline urls or other useless stuff). Only lines
239that are being shown will be filtered, and, due to performance reasons, 633that are being shown will be filtered, and, due to performance reasons,
246later 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
247you cannot just toggle rendition bits, but only set them. 641you cannot just toggle rendition bits, but only set them.
248 642
249=item on_refresh_begin $term 643=item on_refresh_begin $term
250 644
251Called just before the screen gets redrawn. Can be used for overlay 645Called just before the screen gets redrawn. Can be used for overlay or
252or similar effects by modify terminal contents in refresh_begin, and 646similar effects by modifying the terminal contents in refresh_begin, and
253restoring them in refresh_end. The built-in overlay and selection display 647restoring them in refresh_end. The built-in overlay and selection display
254code is run after this hook, and takes precedence. 648code is run after this hook, and takes precedence.
255 649
256=item on_refresh_end $term 650=item on_refresh_end $term
257 651
258Called just after the screen gets redrawn. See C<on_refresh_begin>. 652Called just after the screen gets redrawn. See C<on_refresh_begin>.
259 653
260=item on_keyboard_command $term, $string 654=item on_user_command $term, $string
261 655
262Called whenever the user presses a key combination that has a 656Called whenever a user-configured event is being activated (e.g. via
263C<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>
264resource in the @@RXVT_NAME@@(1) manpage). 658resource in the @@RXVT_NAME@@(1) manpage).
265 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.
678
679=item on_focus_in $term
680
681Called whenever the window gets the keyboard focus, before rxvt-unicode
682does focus in processing.
683
684=item on_focus_out $term
685
686Called whenever the window loses keyboard focus, before rxvt-unicode does
687focus out processing.
688
689=item on_configure_notify $term, $event
690
691=item on_property_notify $term, $event
692
266=item on_key_press $term, $event, $octets 693=item on_key_press $term, $event, $keysym, $octets
267 694
268=item on_key_release $term, $event 695=item on_key_release $term, $event, $keysym
269 696
270=item on_button_press $term, $event 697=item on_button_press $term, $event
271 698
272=item on_button_release $term, $event 699=item on_button_release $term, $event
273 700
274=item on_motion_notify $term, $event 701=item on_motion_notify $term, $event
275 702
703=item on_map_notify $term, $event
704
705=item on_unmap_notify $term, $event
706
276Called whenever the corresponding X event is received for the terminal If 707Called whenever the corresponding X event is received for the terminal. If
277the 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.
278 709
279The 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
280manpage), 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
281and column under the mouse cursor. 712(real, not screen-based) row and column under the mouse cursor.
282 713
283C<on_key_press> additionally receives the string rxvt-unicode would 714C<on_key_press> additionally receives the string rxvt-unicode would
284output, if any, in locale-specific encoding. 715output, if any, in locale-specific encoding.
285 716
286subwindow. 717subwindow.
287 718
719=item on_client_message $term, $event
720
721=item on_wm_protocols $term, $event
722
723=item on_wm_delete_window $term, $event
724
725Called when various types of ClientMessage events are received (all with
726format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
727
728=item on_bell $term
729
730Called on receipt of a bell character.
731
288=back 732=back
289 733
734=cut
735
736package urxvt;
737
738use utf8;
739use strict;
740use Carp ();
741use Scalar::Util ();
742use List::Util ();
743
744our $VERSION = 1;
745our $TERM;
746our @TERM_INIT;
747our @TERM_EXT;
748our @HOOKNAME;
749our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
750our %OPTION;
751
752our $LIBDIR;
753our $RESNAME;
754our $RESCLASS;
755our $RXVTNAME;
756
757our $NOCHAR = chr 0xffff;
758
290=head2 Variables in the C<urxvt> Package 759=head2 Variables in the C<urxvt> Package
291 760
292=over 4 761=over 4
293 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
294=item $urxvt::TERM 776=item $urxvt::TERM
295 777
296The current terminal. Whenever a callback/Hook is bein executed, this 778The current terminal. This variable stores the current C<urxvt::term>
297variable stores the current C<urxvt::term> object. 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>.
298 796
299=back 797=back
300 798
301=head2 Functions in the C<urxvt> Package 799=head2 Functions in the C<urxvt> Package
302 800
303=over 4 801=over 4
304 802
305=item $term = new urxvt [arg...]
306
307Creates a new terminal, very similar as if you had started it with
308C<system $binfile, arg...>. Croaks (and probably outputs an error message)
309if the new instance couldn't be created. Returns C<undef> if the new
310instance didn't initialise perl, and the terminal object otherwise. The
311C<init> and C<start> hooks will be called during the call.
312
313=item urxvt::fatal $errormessage 803=item urxvt::fatal $errormessage
314 804
315Fatally aborts execution with the given error message. Avoid at all 805Fatally aborts execution with the given error message (which should
316costs! The only time this is acceptable is when the terminal process 806include a trailing newline). Avoid at all costs! The only time this
317starts up. 807is acceptable (and useful) is in the init hook, where it prevents the
808terminal from starting up.
318 809
319=item urxvt::warn $string 810=item urxvt::warn $string
320 811
321Calls C<rxvt_warn> with the given string which should not include a 812Calls C<rxvt_warn> with the given string which should include a trailing
322newline. The module also overwrites the C<warn> builtin with a function 813newline. The module also overwrites the C<warn> builtin with a function
323that calls this function. 814that calls this function.
324 815
325Using this function has the advantage that its output ends up in the 816Using this function has the advantage that its output ends up in the
326correct place, e.g. on stderr of the connecting urxvtc client. 817correct place, e.g. on stderr of the connecting urxvtc client.
327 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
328=item $time = urxvt::NOW 828=item $time = urxvt::NOW
329 829
330Returns the "current time" (as per the event loop). 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.
331 855
332=back 856=back
333 857
334=head2 RENDITION 858=head2 RENDITION
335 859
350 874
351=item $rend = urxvt::OVERLAY_RSTYLE 875=item $rend = urxvt::OVERLAY_RSTYLE
352 876
353Return the rendition mask used for overlays by default. 877Return the rendition mask used for overlays by default.
354 878
355=item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline 879=item $rendbit = urxvt::RS_Bold, urxvt::RS_Italic, urxvt::RS_Blink,
880urxvt::RS_RVid, urxvt::RS_Uline
356 881
357Return the bit that enabled bold, italic, blink, reverse-video and 882Return the bit that enabled bold, italic, blink, reverse-video and
358underline, respectively. To enable such a style, just logically OR it into 883underline, respectively. To enable such a style, just logically OR it into
359the bitset. 884the bitset.
360 885
362 887
363=item $background = urxvt::GET_BASEBG $rend 888=item $background = urxvt::GET_BASEBG $rend
364 889
365Return the foreground/background colour index, respectively. 890Return the foreground/background colour index, respectively.
366 891
367=item $rend = urxvt::SET_FGCOLOR ($rend, $new_colour) 892=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
368 893
369=item $rend = urxvt::SET_BGCOLOR ($rend, $new_colour) 894=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
895
896=item $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
370 897
371Replace the foreground/background colour in the rendition mask with the 898Replace the foreground/background colour in the rendition mask with the
372specified one. 899specified one.
373 900
374=item $value = urxvt::GET_CUSTOM ($rend) 901=item $value = urxvt::GET_CUSTOM $rend
375 902
376Return the "custom" value: Every rendition has 5 bits for use by 903Return the "custom" value: Every rendition has 5 bits for use by
377extensions. They can be set and changed as you like and are initially 904extensions. They can be set and changed as you like and are initially
378zero. 905zero.
379 906
380=item $rend = urxvt::SET_CUSTOM ($rend, $new_value) 907=item $rend = urxvt::SET_CUSTOM $rend, $new_value
381 908
382Change the custom value. 909Change the custom value.
383 910
384=back 911=back
385 912
386=cut 913=cut
387 914
388package urxvt;
389
390use strict;
391use Scalar::Util ();
392
393our $TERM;
394our @HOOKNAME;
395our $LIBDIR;
396
397BEGIN { 915BEGIN {
398 urxvt->bootstrap;
399
400 # overwrite perl's warn 916 # overwrite perl's warn
401 *CORE::GLOBAL::warn = sub { 917 *CORE::GLOBAL::warn = sub {
402 my $msg = join "", @_; 918 my $msg = join "", @_;
403 $msg .= "\n" 919 $msg .= "\n"
404 unless $msg =~ /\n$/; 920 unless $msg =~ /\n$/;
405 urxvt::warn ($msg); 921 urxvt::warn ($msg);
406 }; 922 };
407} 923}
408 924
409my @hook_count; 925no warnings 'utf8';
926
410my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 927my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
411 928
412sub verbose { 929sub verbose {
413 my ($level, $msg) = @_; 930 my ($level, $msg) = @_;
414 warn "$msg\n" if $level <= $verbosity; 931 warn "$msg\n" if $level <= $verbosity;
415} 932}
416 933
417# find on_xxx subs in the package and register them 934my %extension_pkg;
418# as hooks
419sub register_package($) {
420 my ($pkg) = @_;
421
422 for my $htype (0.. $#HOOKNAME) {
423 my $name = $HOOKNAME[$htype];
424
425 my $ref = $pkg->can ("on_" . lc $name)
426 or next;
427
428 $TERM->{_hook}[$htype]{$pkg} = $ref;
429 $hook_count[$htype]++
430 or set_should_invoke $htype, 1;
431 }
432}
433
434my $script_pkg = "script0000";
435my %script_pkg;
436 935
437# load a single script into its own package, once only 936# load a single script into its own package, once only
438sub script_package($) { 937sub extension_package($) {
439 my ($path) = @_; 938 my ($path) = @_;
440 939
441 $script_pkg{$path} ||= do { 940 $extension_pkg{$path} ||= do {
442 my $pkg = "urxvt::" . ($script_pkg++); 941 $path =~ /([^\/\\]+)$/;
942 my $pkg = $1;
943 $pkg =~ s/[^[:word:]]/_/g;
944 $pkg = "urxvt::ext::$pkg";
443 945
444 verbose 3, "loading script '$path' into package '$pkg'"; 946 verbose 3, "loading extension '$path' into package '$pkg'";
445 947
446 open my $fh, "<:raw", $path 948 open my $fh, "<:raw", $path
447 or die "$path: $!"; 949 or die "$path: $!";
448 950
449 my $source = "package $pkg; use strict; use utf8;\n" 951 my $source =
952 "package $pkg; use strict; use utf8; no warnings 'utf8';\n"
450 . "#line 1 \"$path\"\n{\n" 953 . "#line 1 \"$path\"\n{\n"
451 . (do { local $/; <$fh> }) 954 . (do { local $/; <$fh> })
452 . "\n};\n1"; 955 . "\n};\n1";
453 956
957 eval $source
454 eval $source or die "$path: $@"; 958 or die "$path: $@";
455 959
456 $pkg 960 $pkg
457 } 961 }
458} 962}
459 963
465 my $htype = shift; 969 my $htype = shift;
466 970
467 if ($htype == 0) { # INIT 971 if ($htype == 0) { # INIT
468 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 972 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
469 973
974 my %ext_arg;
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
470 for my $ext (map { split /:/, $TERM->resource ("perl_ext_$_") } 1, 2) { 985 for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
986 if ($_ eq "default") {
987 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback readline);
988 } elsif (/^-(.*)$/) {
989 delete $ext_arg{$1};
990 } elsif (/^([^<]+)<(.*)>$/) {
991 push @{ $ext_arg{$1} }, $2;
992 } else {
993 $ext_arg{$_} ||= [];
994 }
995 }
996
997 for my $ext (sort keys %ext_arg) {
471 my @files = grep -f $_, map "$_/$ext", @dirs; 998 my @files = grep -f $_, map "$_/$ext", @dirs;
472 999
473 if (@files) { 1000 if (@files) {
474 register_package script_package $files[0]; 1001 $TERM->register_package (extension_package $files[0], $ext_arg{$ext});
475 } else { 1002 } else {
476 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";
477 } 1004 }
478 } 1005 }
1006
1007 eval "#line 1 \"--perl-eval resource/argument\"\n" . $TERM->resource ("perl_eval");
1008 warn $@ if $@;
479 } 1009 }
480 1010
481 $retval = undef; 1011 $retval = undef;
482 1012
483 if (my $cb = $TERM->{_hook}[$htype]) { 1013 if (my $cb = $TERM->{_hook}[$htype]) {
484 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")" 1014 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
485 if $verbosity >= 10; 1015 if $verbosity >= 10;
486 1016
487 keys %$cb; 1017 for my $pkg (keys %$cb) {
1018 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg}, @_) };
1019 $retval ||= $retval_;
488 1020
489 while (my ($pkg, $cb) = each %$cb) { 1021 if ($@) {
490 $retval = $cb->( 1022 $TERM->ungrab; # better to lose the grab than the session
491 $TERM->{_pkg}{$pkg} ||= do { 1023 warn $@;
492 my $proxy = bless { }, urxvt::term::proxy::;
493 Scalar::Util::weaken ($proxy->{term} = $TERM);
494 $proxy
495 },
496 @_,
497 ) and last;
498 }
499 }
500
501 if ($htype == 1) { # DESTROY
502 # remove hooks if unused
503 if (my $hook = $TERM->{_hook}) {
504 for my $htype (0..$#$hook) {
505 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
506 or set_should_invoke $htype, 0;
507 } 1024 }
508 } 1025 }
509 1026
1027 verbose 11, "$HOOKNAME[$htype] returning <$retval>"
1028 if $verbosity >= 11;
1029 }
1030
1031 if ($htype == 1) { # DESTROY
510 # clear package objects 1032 # clear package objects
511 %$_ = () for values %{ $TERM->{_pkg} }; 1033 %$_ = () for values %{ $TERM->{_pkg} };
512 1034
513 # clear package 1035 # clear package
514 %$TERM = (); 1036 %$TERM = ();
515 } 1037 }
516 1038
517 $retval 1039 $retval
518} 1040}
519 1041
520sub urxvt::term::proxy::AUTOLOAD { 1042sub SET_COLOR($$$) {
521 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/ 1043 SET_BGCOLOR (SET_FGCOLOR ($_[0], $_[1]), $_[2])
1044}
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
1073package urxvt::term::extension;
1074
1075sub enable {
1076 my ($self, %hook) = @_;
1077 my $pkg = $self->{_pkg};
1078
1079 while (my ($name, $cb) = each %hook) {
1080 my $htype = $HOOKTYPE{uc $name};
1081 defined $htype
1082 or Carp::croak "unsupported hook type '$name'";
1083
1084 $self->set_should_invoke ($htype, +1)
1085 unless exists $self->{term}{_hook}[$htype]{$pkg};
1086
1087 $self->{term}{_hook}[$htype]{$pkg} = $cb;
1088 }
1089}
1090
1091sub disable {
1092 my ($self, @hook) = @_;
1093 my $pkg = $self->{_pkg};
1094
1095 for my $name (@hook) {
1096 my $htype = $HOOKTYPE{uc $name};
1097 defined $htype
1098 or Carp::croak "unsupported hook type '$name'";
1099
1100 $self->set_should_invoke ($htype, -1)
1101 if delete $self->{term}{_hook}[$htype]{$pkg};
1102 }
1103}
1104
1105our $AUTOLOAD;
1106
1107sub AUTOLOAD {
1108 $AUTOLOAD =~ /:([^:]+)$/
522 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable"; 1109 or die "FATAL: \$AUTOLOAD '$AUTOLOAD' unparsable";
523 1110
524 eval qq{ 1111 eval qq{
525 sub $urxvt::term::proxy::AUTOLOAD { 1112 sub $AUTOLOAD {
526 my \$proxy = shift; 1113 my \$proxy = shift;
527 \$proxy->{term}->$1 (\@_) 1114 \$proxy->{term}->$1 (\@_)
528 } 1115 }
529 1 1116 1
530 } or die "FATAL: unable to compile method forwarder: $@"; 1117 } or die "FATAL: unable to compile method forwarder: $@";
531 1118
532 goto &$urxvt::term::proxy::AUTOLOAD; 1119 goto &$AUTOLOAD;
533} 1120}
1121
1122sub DESTROY {
1123 # nop
1124}
1125
1126# urxvt::destroy_hook
1127
1128sub urxvt::destroy_hook::DESTROY {
1129 ${$_[0]}->();
1130}
1131
1132sub urxvt::destroy_hook(&) {
1133 bless \shift, urxvt::destroy_hook::
1134}
1135
1136package urxvt::anyevent;
1137
1138=head2 The C<urxvt::anyevent> Class
1139
1140The sole purpose of this class is to deliver an interface to the
1141C<AnyEvent> module - any module using it will work inside urxvt without
1142further programming. The only exception is that you cannot wait on
1143condition variables, but non-blocking condvar use is ok. What this means
1144is that you cannot use blocking APIs, but the non-blocking variant should
1145work.
1146
1147=cut
1148
1149our $VERSION = '5.23';
1150
1151$INC{"urxvt/anyevent.pm"} = 1; # mark us as there
1152push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
1153
1154sub timer {
1155 my ($class, %arg) = @_;
1156
1157 my $cb = $arg{cb};
1158
1159 urxvt::timer
1160 ->new
1161 ->after ($arg{after}, $arg{interval})
1162 ->cb ($arg{interval} ? $cb : sub {
1163 $_[0]->stop; # need to cancel manually
1164 $cb->();
1165 })
1166}
1167
1168sub io {
1169 my ($class, %arg) = @_;
1170
1171 my $cb = $arg{cb};
1172 my $fd = fileno $arg{fh};
1173 defined $fd or $fd = $arg{fh};
1174
1175 bless [$arg{fh}, urxvt::iow
1176 ->new
1177 ->fd ($fd)
1178 ->events (($arg{poll} =~ /r/ ? 1 : 0)
1179 | ($arg{poll} =~ /w/ ? 2 : 0))
1180 ->start
1181 ->cb ($cb)
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 })
1208}
1209
1210sub DESTROY {
1211 $_[0][1]->stop;
1212}
1213
1214sub one_event {
1215 Carp::croak "AnyEvent->one_event blocking wait unsupported in urxvt, use a non-blocking API";
1216}
1217
1218package urxvt::term;
534 1219
535=head2 The C<urxvt::term> Class 1220=head2 The C<urxvt::term> Class
536 1221
537=over 4 1222=over 4
538 1223
1224=cut
1225
1226# find on_xxx subs in the package and register them
1227# as hooks
1228sub register_package {
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::;
1236
1237 my $proxy = bless {
1238 _pkg => $pkg,
1239 argv => $argv,
1240 }, $pkg;
1241 Scalar::Util::weaken ($proxy->{term} = $self);
1242
1243 $self->{_pkg}{$pkg} = $proxy;
1244
1245 for my $name (@HOOKNAME) {
1246 if (my $ref = $pkg->can ("on_" . lc $name)) {
1247 $proxy->enable ($name => $ref);
1248 }
1249 }
1250}
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
539=item $term->destroy 1275=item $term->destroy
540 1276
541Destroy 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}
1305
1306=item $isset = $term->option ($optval[, $set])
1307
1308Returns true if the option specified by C<$optval> is enabled, and
1309optionally change it. All option values are stored by name in the hash
1310C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
1311
1312Here is a likely non-exhaustive list of option names, please see the
1313source file F</src/optinc.h> to see the actual list:
1314
1315 borderLess buffered console cursorBlink cursorUnderline hold iconic
1316 insecure intensityStyles iso14755 iso14755_52 jumpScroll loginShell
1317 mapAlert meta8 mouseWheelScrollPage override_redirect pastableTabs
1318 pointerBlank reverseVideo scrollBar scrollBar_floating scrollBar_right
1319 scrollTtyKeypress scrollTtyOutput scrollWithBuffer secondaryScreen
1320 secondaryScroll skipBuiltinGlyphs skipScroll transparent tripleclickwords
1321 urgentOnBell utmpInhibit visualBell
542 1322
543=item $value = $term->resource ($name[, $newval]) 1323=item $value = $term->resource ($name[, $newval])
544 1324
545Returns the current resource value associated with a given name and 1325Returns the current resource value associated with a given name and
546optionally 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>
555likely change). 1335likely change).
556 1336
557Please note that resource strings will currently only be freed when the 1337Please note that resource strings will currently only be freed when the
558terminal is destroyed, so changing options frequently will eat memory. 1338terminal is destroyed, so changing options frequently will eat memory.
559 1339
560Here 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
561are supported in every build, please see the source to see the actual 1341are supported in every build, please see the source file F</src/rsinc.h>
562list: 1342to see the actual list:
563 1343
564 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1344 answerbackstring backgroundPixmap backspace_key blendtype blurradius
565 borderLess color cursorBlink cursorUnderline cutchars delete_key 1345 boldFont boldItalicFont borderLess buffered chdir color cursorBlink
566 display_name embed ext_bwidth fade font geometry hold iconName 1346 cursorUnderline cutchars delete_key depth display_name embed ext_bwidth
567 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
568 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier 1349 jumpScroll letterSpace lineSpace loginShell mapAlert meta8 modifier
569 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2 1350 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
570 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 1351 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
571 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 1352 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
572 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 1353 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
573 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 1354 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
574 shade term_name title transparent transparent_all tripleclickwords 1355 secondaryScreen secondaryScroll shade skipBuiltinGlyphs skipScroll
1356 term_name title transient_for transparent tripleclickwords urgentOnBell
575 utmpInhibit visualBell 1357 utmpInhibit visualBell
576 1358
577=cut 1359=cut
578 1360
579sub urxvt::term::resource($$;$) { 1361sub resource($$;$) {
580 my ($self, $name) = (shift, shift); 1362 my ($self, $name) = (shift, shift);
581 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 1363 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
582 goto &urxvt::term::_resource; 1364 goto &urxvt::term::_resource
583} 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.
1377
1378=item $success = $term->parse_keysym ($keysym_spec, $command_string)
1379
1380Adds a keymap translation exactly as specified via a resource. See the
1381C<keysym> resource in the @@RXVT_NAME@@(1) manpage.
584 1382
585=item $rend = $term->rstyle ([$new_rstyle]) 1383=item $rend = $term->rstyle ([$new_rstyle])
586 1384
587Return and optionally change the current rendition. Text that is output by 1385Return and optionally change the current rendition. Text that is output by
588the terminal application will use this style. 1386the terminal application will use this style.
596 1394
597=item ($row, $col) = $term->selection_beg ([$row, $col]) 1395=item ($row, $col) = $term->selection_beg ([$row, $col])
598 1396
599=item ($row, $col) = $term->selection_end ([$row, $col]) 1397=item ($row, $col) = $term->selection_end ([$row, $col])
600 1398
601Return the current values of the selection mark, begin or end positions, 1399Return the current values of the selection mark, begin or end positions.
602and optionally set them to new values.
603 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
604=item $success = $term->selection_grab ($eventtime) 1416=item $success = $term->selection_grab ($eventtime[, $clipboard])
605 1417
606Try to request the primary selection from the server (for example, as set 1418Try to acquire ownership of the primary (clipboard if C<$clipboard> is
607by 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.
608 1422
609=item $oldtext = $term->selection ([$newtext]) 1423=item $oldtext = $term->selection ([$newtext, $clipboard])
610 1424
611Return 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>.
612 1427
1428=item $term->selection_clear ([$clipboard])
1429
1430Revoke ownership of the primary (clipboard if C<$clipboard> is true) selection.
1431
613#=item $term->overlay ($x, $y, $text) 1432=item $term->overlay_simple ($x, $y, $text)
614# 1433
615#Create 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.
616# 1435
617#=cut 1436=cut
618# 1437
619#sub urxvt::term::scr_overlay { 1438sub overlay_simple {
620# my ($self, $x, $y, $text) = @_; 1439 my ($self, $x, $y, $text) = @_;
621# 1440
622# my @lines = split /\n/, $text; 1441 my @lines = split /\n/, $text;
623# 1442
624# my $w = 0; 1443 my $w = List::Util::max map $self->strwidth ($_), @lines;
625# for (map $self->strwidth ($_), @lines) { 1444
626# $w = $_ if $w < $_;
627# }
628#
629# $self->scr_overlay_new ($x, $y, $w, scalar @lines); 1445 my $overlay = $self->overlay ($x, $y, $w, scalar @lines);
630# $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 1446 $overlay->set (0, $_, $lines[$_]) for 0.. $#lines;
631#} 1447
1448 $overlay
1449}
632 1450
633=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 1451=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
634 1452
635Create a new (empty) overlay at the given position with the given 1453Create a new (empty) overlay at the given position with the given
636width/height. C<$rstyle> defines the initial rendition style 1454width/height. C<$rstyle> defines the initial rendition style
647 1465
648The methods currently supported on C<urxvt::overlay> objects are: 1466The methods currently supported on C<urxvt::overlay> objects are:
649 1467
650=over 4 1468=over 4
651 1469
652=item $overlay->set ($x, $y, $text, $rend) 1470=item $overlay->set ($x, $y, $text[, $rend])
653 1471
654Similar 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
655text 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
656at a specific position inside the overlay. 1474at a specific position inside the overlay.
657 1475
1476If C<$rend> is missing, then the rendition will not be changed.
1477
658=item $overlay->hide 1478=item $overlay->hide
659 1479
660If visible, hide the overlay, but do not destroy it. 1480If visible, hide the overlay, but do not destroy it.
661 1481
662=item $overlay->show 1482=item $overlay->show
663 1483
664If hidden, display the overlay again. 1484If hidden, display the overlay again.
665 1485
666=back 1486=back
667 1487
1488=item $popup = $term->popup ($event)
1489
1490Creates a new C<urxvt::popup> object that implements a popup menu. The
1491C<$event> I<must> be the event causing the menu to pop up (a button event,
1492currently).
1493
1494=cut
1495
1496sub popup {
1497 my ($self, $event) = @_;
1498
1499 $self->grab ($event->{time}, 1)
1500 or return;
1501
1502 my $popup = bless {
1503 term => $self,
1504 event => $event,
1505 }, urxvt::popup::;
1506
1507 Scalar::Util::weaken $popup->{term};
1508
1509 $self->{_destroy}{$popup} = urxvt::destroy_hook { $popup->{popup}->destroy };
1510 Scalar::Util::weaken $self->{_destroy}{$popup};
1511
1512 $popup
1513}
1514
668=item $cellwidth = $term->strwidth $string 1515=item $cellwidth = $term->strwidth ($string)
669 1516
670Returns the number of screen-cells this string would need. Correctly 1517Returns the number of screen-cells this string would need. Correctly
671accounts for wide and combining characters. 1518accounts for wide and combining characters.
672 1519
673=item $octets = $term->locale_encode $string 1520=item $octets = $term->locale_encode ($string)
674 1521
675Convert the given text string into the corresponding locale encoding. 1522Convert the given text string into the corresponding locale encoding.
676 1523
677=item $string = $term->locale_decode $octets 1524=item $string = $term->locale_decode ($octets)
678 1525
679Convert the given locale-encoded octets into a perl string. 1526Convert the given locale-encoded octets into a perl string.
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
1541=item $term->scr_bell
1542
1543Ring the bell!
680 1544
681=item $term->scr_add_lines ($string) 1545=item $term->scr_add_lines ($string)
682 1546
683Write the given text string to the screen, as if output by the application 1547Write the given text string to the screen, as if output by the application
684running inside the terminal. It may not contain command sequences (escape 1548running inside the terminal. It may not contain command sequences (escape
687 1551
688Normally 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
689confused by changes in cursor position or scrolling. Its useful inside a 1553confused by changes in cursor position or scrolling. Its useful inside a
690C<on_add_lines> hook, though. 1554C<on_add_lines> hook, though.
691 1555
1556=item $term->scr_change_screen ($screen)
1557
1558Switch to given screen - 0 primary, 1 secondary.
1559
692=item $term->cmd_parse ($octets) 1560=item $term->cmd_parse ($octets)
693 1561
694Similar 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
695locale-specific encoding of the terminal and can contain command sequences 1563locale-specific encoding of the terminal and can contain command sequences
696(escape codes) that will be interpreted. 1564(escape codes) that will be interpreted.
697 1565
698=item $term->tt_write ($octets) 1566=item $term->tt_write ($octets)
699 1567
700Write 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
701pass characters instead of octets, you should convert your strings first 1569pass characters instead of octets, you should convert your strings first
702to the locale-specific encoding using C<< $term->locale_encode >>. 1570to the locale-specific encoding using C<< $term->locale_encode >>.
703 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.
1577
1578=item $old_events = $term->pty_ev_events ([$new_events])
1579
1580Replaces the event mask of the pty watcher by the given event mask. Can
1581be used to suppress input and output handling to the pty/tty. See the
1582description of C<< urxvt::timer->events >>. Make sure to always restore
1583the previous value.
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
1590=item $windowid = $term->parent
1591
1592Return the window id of the toplevel window.
1593
1594=item $windowid = $term->vt
1595
1596Return the window id of the terminal window.
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
704=item $window_width = $term->width 1615=item $window_width = $term->width
705 1616
706=item $window_height = $term->height 1617=item $window_height = $term->height
707 1618
708=item $font_width = $term->fwidth 1619=item $font_width = $term->fwidth
721 1632
722=item $max_scrollback = $term->saveLines 1633=item $max_scrollback = $term->saveLines
723 1634
724=item $nrow_plus_saveLines = $term->total_rows 1635=item $nrow_plus_saveLines = $term->total_rows
725 1636
726=item $lines_in_scrollback = $term->nsaved 1637=item $topmost_scrollback_row = $term->top_row
727 1638
728Return various integers describing terminal characteristics. 1639Return various integers describing terminal characteristics.
729 1640
1641=item $x_display = $term->display_id
1642
1643Return the DISPLAY used by rxvt-unicode.
1644
1645=item $lc_ctype = $term->locale
1646
1647Returns the LC_CTYPE category string used by this rxvt-unicode.
1648
1649=item $env = $term->env
1650
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}
1668
1669=item $modifiermask = $term->ModLevel3Mask
1670
1671=item $modifiermask = $term->ModMetaMask
1672
1673=item $modifiermask = $term->ModNumLockMask
1674
1675Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
1676AltGr), the meta key (often Alt) and the num lock key, if applicable.
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
730=item $view_start = $term->view_start ([$newvalue]) 1686=item $view_start = $term->view_start ([$newvalue])
731 1687
732Returns the negative row number of the topmost line. Minimum value is 1688Returns the row number of the topmost displayed line. Maximum value is
733C<0>, which displays the normal terminal contents. Larger values scroll 1689C<0>, which displays the normal terminal contents. Lower values scroll
734this many lines into the scrollback buffer. 1690this many lines into the scrollback buffer.
735 1691
736=item $term->want_refresh 1692=item $term->want_refresh
737 1693
738Requests a screen refresh. At the next opportunity, rxvt-unicode will 1694Requests a screen refresh. At the next opportunity, rxvt-unicode will
741 1697
742Used after changing terminal contents to display them. 1698Used after changing terminal contents to display them.
743 1699
744=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]]) 1700=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
745 1701
746Returns 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 >>
747is 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
748terminal line. The scrollback buffer starts at line C<-1> and extends to
749line C<< -$term->nsaved >>. Nothing will be returned if a nonexistent line 1704terminal line. Nothing will be returned if a nonexistent line
750is requested. 1705is requested.
751 1706
752If 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
753line, 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
754to 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
755automatically be updated. 1710automatically be updated.
756 1711
757C<$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
758than one cell when displayed are padded with urxvt::NOCHAR characters 1713than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535)
759(C<chr 65535>). Characters with combining characters and other characters 1714characters. Characters with combining characters and other characters that
760that 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
761characters in the private use area. 1716in the private use area.
762 1717
763You have to obey this encoding when changing text. The advantage is 1718You have to obey this encoding when changing text. The advantage is
764that 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
765characters. 1720characters.
766 1721
817Return 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.
818 1773
819=item $offset = $line->offset_of ($row, $col) 1774=item $offset = $line->offset_of ($row, $col)
820 1775
821Returns 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
822line. 1777line. Works for rows outside the line, too, and returns corresponding
1778offsets outside the string.
823 1779
824=item ($row, $col) = $line->coord_of ($offset) 1780=item ($row, $col) = $line->coord_of ($offset)
825 1781
826Translates a string offset into terminal coordinates again. 1782Translates a string offset into terminal coordinates again.
827 1783
828=back 1784=back
829 1785
830=cut 1786=cut
831 1787
832sub urxvt::term::line { 1788sub line {
833 my ($self, $row) = @_; 1789 my ($self, $row) = @_;
834 1790
835 my $maxrow = $self->nrow - 1; 1791 my $maxrow = $self->nrow - 1;
836 1792
837 my ($beg, $end) = ($row, $row); 1793 my ($beg, $end) = ($row, $row);
901 $offset / $self->{ncol} + $self->{beg}, 1857 $offset / $self->{ncol} + $self->{beg},
902 $offset % $self->{ncol} 1858 $offset % $self->{ncol}
903 ) 1859 )
904} 1860}
905 1861
906=item ($row, $col) = $line->coord_of ($offset)
907=item $text = $term->special_encode $string 1862=item $text = $term->special_encode $string
908 1863
909Converts a perl string into the special encoding used by rxvt-unicode, 1864Converts a perl string into the special encoding used by rxvt-unicode,
910where one character corresponds to one screen cell. See 1865where one character corresponds to one screen cell. See
911C<< $term->ROW_t >> for details. 1866C<< $term->ROW_t >> for details.
912 1867
913=item $string = $term->special_decode $text 1868=item $string = $term->special_decode $text
914 1869
915Converts rxvt-unicodes text reprsentation into a perl string. See 1870Converts rxvt-unicodes text representation into a perl string. See
916C<< $term->ROW_t >> for details. 1871C<< $term->ROW_t >> for details.
917 1872
1873=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1874
1875=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1876
1877Register/unregister a synchronous button grab. See the XGrabButton
1878manpage.
1879
1880=item $success = $term->grab ($eventtime[, $sync])
1881
1882Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1883synchronous (C<$sync> is true). Also remembers the grab timestamp.
1884
1885=item $term->allow_events_async
1886
1887Calls XAllowEvents with AsyncBoth for the most recent grab.
1888
1889=item $term->allow_events_sync
1890
1891Calls XAllowEvents with SyncBoth for the most recent grab.
1892
1893=item $term->allow_events_replay
1894
1895Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most
1896recent grab.
1897
1898=item $term->ungrab
1899
1900Calls XUngrabPointer and XUngrabKeyboard for the most recent grab. Is called automatically on
1901evaluation errors, as it is better to lose the grab in the error case as
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.
1933
918=back 1934=back
1935
1936=cut
1937
1938package urxvt::popup;
1939
1940=head2 The C<urxvt::popup> Class
1941
1942=over 4
1943
1944=cut
1945
1946sub add_item {
1947 my ($self, $item) = @_;
1948
1949 $item->{rend}{normal} = "\x1b[0;30;47m" unless exists $item->{rend}{normal};
1950 $item->{rend}{hover} = "\x1b[0;30;46m" unless exists $item->{rend}{hover};
1951 $item->{rend}{active} = "\x1b[m" unless exists $item->{rend}{active};
1952
1953 $item->{render} ||= sub { $_[0]{text} };
1954
1955 push @{ $self->{item} }, $item;
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
1979
1980sub add_separator {
1981 my ($self, $sep) = @_;
1982
1983 $sep ||= "=";
1984
1985 $self->add_item ({
1986 rend => { normal => "\x1b[0;30;47m", hover => "\x1b[0;30;47m", active => "\x1b[0;30;47m" },
1987 text => "",
1988 render => sub { $sep x $self->{term}->ncol },
1989 activate => sub { },
1990 });
1991}
1992
1993=item $popup->add_button ($text, $cb)
1994
1995Adds a clickable button to the popup. C<$cb> is called whenever it is
1996selected.
1997
1998=cut
1999
2000sub add_button {
2001 my ($self, $text, $cb) = @_;
2002
2003 $self->add_item ({ type => "button", text => $text, activate => $cb});
2004}
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
2014sub add_toggle {
2015 my ($self, $text, $value, $cb) = @_;
2016
2017 my $item; $item = {
2018 type => "button",
2019 text => " $text",
2020 value => $value,
2021 render => sub { ($_[0]{value} ? "* " : " ") . $text },
2022 activate => sub { $cb->($_[1]{value} = !$_[1]{value}); },
2023 };
2024
2025 $self->add_item ($item);
2026}
2027
2028=item $popup->show
2029
2030Displays the popup (which is initially hidden).
2031
2032=cut
2033
2034sub show {
2035 my ($self) = @_;
2036
2037 local $urxvt::popup::self = $self;
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};
2042 $env->{LC_CTYPE} = $self->{term}->locale;
2043
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",
2049 "--transient-for" => $self->{term}->parent,
2050 "-display" => $self->{term}->display_id,
2051 "-pe" => "urxvt-popup",
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 }
2059}
2060
2061sub DESTROY {
2062 my ($self) = @_;
2063
2064 delete $self->{term}{_destroy}{$self};
2065 $self->{term}->ungrab;
2066}
2067
2068=back
2069
2070=cut
2071
2072package urxvt::watcher;
919 2073
920=head2 The C<urxvt::timer> Class 2074=head2 The C<urxvt::timer> Class
921 2075
922This class implements timer watchers/events. Time is represented as a 2076This class implements timer watchers/events. Time is represented as a
923fractional number of seconds since the epoch. Example: 2077fractional number of seconds since the epoch. Example:
927 ->new 2081 ->new
928 ->interval (1) 2082 ->interval (1)
929 ->cb (sub { 2083 ->cb (sub {
930 $term->{overlay}->set (0, 0, 2084 $term->{overlay}->set (0, 0,
931 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]); 2085 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
932 }); 2086 });
933 2087
934=over 4 2088=over 4
935 2089
936=item $timer = new urxvt::timer 2090=item $timer = new urxvt::timer
937 2091
940 2094
941=item $timer = $timer->cb (sub { my ($timer) = @_; ... }) 2095=item $timer = $timer->cb (sub { my ($timer) = @_; ... })
942 2096
943Set the callback to be called when the timer triggers. 2097Set the callback to be called when the timer triggers.
944 2098
945=item $tstamp = $timer->at
946
947Return the time this watcher will fire next.
948
949=item $timer = $timer->set ($tstamp) 2099=item $timer = $timer->set ($tstamp[, $interval])
950 2100
951Set the time the event is generated to $tstamp. 2101Set the time the event is generated to $tstamp (and optionally specifies a
2102new $interval).
952 2103
953=item $timer = $timer->interval ($interval) 2104=item $timer = $timer->interval ($interval)
954 2105
955Normally (and when C<$interval> is C<0>), the timer will automatically 2106By default (and when C<$interval> is C<0>), the timer will automatically
956stop 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
957is automatically rescheduled at the given intervals. 2108is automatically rescheduled at the given intervals.
958 2109
959=item $timer = $timer->start 2110=item $timer = $timer->start
960 2111
961Start the timer. 2112Start the timer.
962 2113
963=item $timer = $timer->start ($tstamp) 2114=item $timer = $timer->start ($tstamp[, $interval])
964 2115
965Set 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>.
966 2122
967=item $timer = $timer->stop 2123=item $timer = $timer->stop
968 2124
969Stop the timer. 2125Stop the timer.
970 2126
976 2132
977 $term->{socket} = ... 2133 $term->{socket} = ...
978 $term->{iow} = urxvt::iow 2134 $term->{iow} = urxvt::iow
979 ->new 2135 ->new
980 ->fd (fileno $term->{socket}) 2136 ->fd (fileno $term->{socket})
981 ->events (1) # wait for read data 2137 ->events (urxvt::EV_READ)
982 ->start 2138 ->start
983 ->cb (sub { 2139 ->cb (sub {
984 my ($iow, $revents) = @_; 2140 my ($iow, $revents) = @_;
985 # $revents must be 1 here, no need to check 2141 # $revents must be 1 here, no need to check
986 sysread $term->{socket}, my $buf, 8192 2142 sysread $term->{socket}, my $buf, 8192
999Set 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>
1000is a bitset as described in the C<events> method. 2156is a bitset as described in the C<events> method.
1001 2157
1002=item $iow = $iow->fd ($fd) 2158=item $iow = $iow->fd ($fd)
1003 2159
1004Set the filedescriptor (not handle) to watch. 2160Set the file descriptor (not handle) to watch.
1005 2161
1006=item $iow = $iow->events ($eventmask) 2162=item $iow = $iow->events ($eventmask)
1007 2163
1008Set the event mask to watch. Bit #0 (value C<1>) enables watching for read 2164Set the event mask to watch. The only allowed values are
1009data, Bit #1 (value C<2>) enables watching for write data. 2165C<urxvt::EV_READ> and C<urxvt::EV_WRITE>, which might be ORed
2166together, or C<urxvt::EV_NONE>.
1010 2167
1011=item $iow = $iow->start 2168=item $iow = $iow->start
1012 2169
1013Start watching for requested events on the given handle. 2170Start watching for requested events on the given handle.
1014 2171
1015=item $iow = $iow->stop 2172=item $iow = $iow->stop
1016 2173
1017Stop 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.
1018 2236
1019=back 2237=back
1020 2238
1021=head1 ENVIRONMENT 2239=head1 ENVIRONMENT
1022 2240
1025This variable controls the verbosity level of the perl extension. Higher 2243This variable controls the verbosity level of the perl extension. Higher
1026numbers indicate more verbose output. 2244numbers indicate more verbose output.
1027 2245
1028=over 4 2246=over 4
1029 2247
1030=item =0 - only fatal messages 2248=item == 0 - fatal messages
1031 2249
1032=item =3 - script loading and management 2250=item >= 3 - script loading and management
1033 2251
1034=item =10 - all events received 2252=item >=10 - all called hooks
2253
2254=item >=11 - hook return values
1035 2255
1036=back 2256=back
1037 2257
1038=head1 AUTHOR 2258=head1 AUTHOR
1039 2259
1040 Marc Lehmann <pcg@goof.com> 2260 Marc Lehmann <schmorp@schmorp.de>
1041 http://software.schmorp.de/pkg/rxvt-unicode 2261 http://software.schmorp.de/pkg/rxvt-unicode
1042 2262
1043=cut 2263=cut
1044 2264
10451 22651
2266
2267# vim: sw=3:

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines