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.54 by root, Sun Jan 8 01:59:29 2006 UTC vs.
Revision 1.132 by root, Mon Feb 6 05:40:15 2006 UTC

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 31=head1 PREPACKAGED EXTENSIONS
32 32
33This section describes the extensiosn delivered with this version. You can 33This section describes the extensions delivered with this release. You can
34find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>. 34find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>.
35 35
36You can activate them like this: 36You can activate them like this:
37 37
38 @@RXVT_NAME@@ -pe <extensionname> 38 @@RXVT_NAME@@ -pe <extensionname>
39 39
40Or by adding them to the resource for extensions loaded by default:
41
42 URxvt.perl-ext-common: default,automove-background,selection-autotransform
43
40=over 4 44=over 4
41 45
42=item selection (enabled by default) 46=item selection (enabled by default)
43 47
44Intelligent selection. This extension tries to be more intelligent when 48(More) intelligent selection. This extension tries to be more intelligent
45the user extends selections (double-click). Right now, it tries to select 49when the user extends selections (double-click and further clicks). Right
46urls and complete shell-quoted arguments, which is very convenient, too, 50now, it tries to select words, urls and complete shell-quoted
47if your F<ls> supports C<--quoting-style=shell>. 51arguments, which is very convenient, too, if your F<ls> supports
52C<--quoting-style=shell>.
48 53
49It also offers the following bindable event: 54A double-click usually selects the word under the cursor, further clicks
55will enlarge the selection.
56
57The selection works by trying to match a number of regexes and displaying
58them in increasing order of length. You can add your own regexes by
59specifying resources of the form:
60
61 URxvt.selection.pattern-0: perl-regex
62 URxvt.selection.pattern-1: perl-regex
63 ...
64
65The index number (0, 1...) must not have any holes, and each regex must
66contain at least one pair of capturing parentheses, which will be used for
67the match. For example, the followign adds a regex that matches everything
68between two vertical bars:
69
70 URxvt.selection.pattern-0: \\|([^|]+)\\|
71
72Another example: Programs I use often output "absolute path: " at the
73beginning of a line when they process multiple files. The following
74pattern matches the filename (note, there is a single space at the very
75end):
76
77 URxvt.selection.pattern-0: ^(/[^:]+):\
78
79You can look at the source of the selection extension to see more
80interesting uses, such as parsing a line from beginning to end.
81
82This extension also offers following bindable keyboard commands:
50 83
51=over 4 84=over 4
52 85
53=item rot13 86=item rot13
54 87
58 91
59=back 92=back
60 93
61=item option-popup (enabled by default) 94=item option-popup (enabled by default)
62 95
63Binds a popup menu to Ctrl-Button3 that lets you toggle (some) options at 96Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at
64runtime. 97runtime.
65 98
66=item digital-clock 99=item selection-popup (enabled by default)
67 100
68Displays a digital clock using the built-in overlay. 101Binds a popup menu to Ctrl-Button3 that lets you convert the selection
102text into various other formats/action (such as uri unescaping, perl
103evaluation, web-browser starting etc.), depending on content.
104
105Other extensions can extend this popup menu by pushing a code reference
106onto C<@{ $term->{selection_popup_hook} }>, that is called whenever the
107popup is displayed.
108
109It's sole argument is the popup menu, which can be modified. The selection
110is in C<$_>, which can be used to decide wether to add something or not.
111It should either return nothing or a string and a code reference. The
112string will be used as button text and the code reference will be called
113when the button gets activated and should transform C<$_>.
114
115The following will add an entry C<a to b> that transforms all C<a>s in
116the selection to C<b>s, but only if the selection currently contains any
117C<a>s:
118
119 push @{ $self->{term}{selection_popup_hook} }, sub {
120 /a/ ? ("a to be" => sub { s/a/b/g }
121 : ()
122 };
123
124=item searchable-scrollback<hotkey> (enabled by default)
125
126Adds regex search functionality to the scrollback buffer, triggered
127by a hotkey (default: C<M-s>). While in search mode, normal terminal
128input/output is suspended and a regex is displayed at the bottom of the
129screen.
130
131Inputting characters appends them to the regex and continues incremental
132search. C<BackSpace> removes a character from the regex, C<Up> and C<Down>
133search upwards/downwards in the scrollback buffer, C<End> jumps to the
134bottom. C<Escape> leaves search mode and returns to the point where search
135was started, while C<Enter> or C<Return> stay at the current position and
136additionally stores the first match in the current line into the primary
137selection.
138
139=item readline (enabled by default)
140
141A support package that tries to make editing with readline easier. At the
142moment, it reacts to clicking with the left mouse button by trying to
143move the text cursor to this position. It does so by generating as many
144cursor-left or cursor-right keypresses as required (the this only works
145for programs that correctly support wide characters).
146
147To avoid too many false positives, this is only done when:
148
149=over 4
150
151=item - the tty is in ICANON state.
152
153=item - the text cursor is visible.
154
155=item - the primary screen is currently being displayed.
156
157=item - the mouse is on the same (multi-row-) line as the text cursor.
158
159=back
160
161The normal selection mechanism isn't disabled, so quick successive clicks
162might interfere with selection creation in harmless ways.
163
164=item selection-autotransform
165
166This selection allows you to do automatic transforms on a selection
167whenever a selection is made.
168
169It works by specifying perl snippets (most useful is a single C<s///>
170operator) that modify C<$_> as resources:
171
172 URxvt.selection-autotransform.0: transform
173 URxvt.selection-autotransform.1: transform
174 ...
175
176For example, the following will transform selections of the form
177C<filename:number>, often seen in compiler messages, into C<vi +$filename
178$word>:
179
180 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
181
182And this example matches the same,but replaces it with vi-commands you can
183paste directly into your (vi :) editor:
184
185 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/
186
187Of course, this can be modified to suit your needs and your editor :)
188
189To expand the example above to typical perl error messages ("XXX at
190FILENAME line YYY."), you need a slightly more elaborate solution:
191
192 URxvt.selection.pattern-0: ( at .*? line \\d+[,.])
193 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/
194
195The first line tells the selection code to treat the unchanging part of
196every error message as a selection pattern, and the second line transforms
197the message into vi commands to load the file.
198
199=item tabbed
200
201This transforms the terminal into a tabbar with additional terminals, that
202is, it implements what is commonly refered to as "tabbed terminal". The topmost line
203displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one
204button per tab.
205
206Clicking a button will activate that tab. Pressing B<Shift-Left> and
207B<Shift-Right> will switch to the tab left or right of the current one,
208while B<Shift-Down> creates a new tab.
209
210The tabbar itself can be configured similarly to a normal terminal, but
211with a resource class of C<URxvt.tabbed>. In addition, it supports the
212following four resources (shown with defaults):
213
214 URxvt.tabbed.tabbar-fg: <colour-index, default 3>
215 URxvt.tabbed.tabbar-bg: <colour-index, default 0>
216 URxvt.tabbed.tab-fg: <colour-index, default 0>
217 URxvt.tabbed.tab-bg: <colour-index, default 1>
218
219See I<COLOR AND GRAPHICS> in the @@RXVT_NAME@@(1) manpage for valid
220indices.
69 221
70=item mark-urls 222=item mark-urls
71 223
72Uses per-line display filtering (C<on_line_update>) to underline urls. 224Uses per-line display filtering (C<on_line_update>) to underline urls and
225make them clickable. When middle-clicked, the program specified in the
226resource C<urlLauncher> (default C<x-www-browser>) will be started with
227the URL as first argument.
228
229=item xim-onthespot
230
231This (experimental) perl extension implements OnTheSpot editing. It does
232not work perfectly, and some input methods don't seem to work well with
233OnTheSpot editing in general, but it seems to work at leats for SCIM and
234kinput2.
235
236You enable it by specifying this extension and a preedit style of
237C<OnTheSpot>, i.e.:
238
239 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot
240
241=item automove-background
242
243This is basically a one-line extension that dynamically changes the background pixmap offset
244to the window position, in effect creating the same effect as pseudo transparency with
245a custom pixmap. No scaling is supported in this mode. Exmaple:
246
247 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background
73 248
74=item block-graphics-to-ascii 249=item block-graphics-to-ascii
75 250
76A not very useful example of filtering all text output to the terminal, 251A not very useful example of filtering all text output to the terminal,
77by replacing all line-drawing characters (U+2500 .. U+259F) by a 252by replacing all line-drawing characters (U+2500 .. U+259F) by a
78similar-looking ascii character. 253similar-looking ascii character.
79 254
255=item digital-clock
256
257Displays a digital clock using the built-in overlay.
258
259=item remote-clipboard
260
261Somewhat of a misnomer, this extension adds two menu entries to the
262selection popup that allows one ti run external commands to store the
263selection somewhere and fetch it again.
264
265We use it to implement a "distributed selection mechanism", which just
266means that one command uploads the file to a remote server, and another
267reads it.
268
269The commands can be set using the C<URxvt.remote-selection.store> and
270C<URxvt.remote-selection.fetch> resources. The first should read the
271selection to store from STDIN (always in UTF-8), the second should provide
272the selection data on STDOUT (also in UTF-8).
273
274The defaults (which are likely useless to you) use rsh and cat:
275
276 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
277 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
278
279=item selection-pastebin
280
281This is a little rarely useful extension that Uploads the selection as
282textfile to a remote site (or does other things). (The implementation is
283not currently secure for use in a multiuser environment as it writes to
284F</tmp> directly.).
285
286It listens to the C<selection-pastebin:remote-pastebin> keyboard command,
287i.e.
288
289 URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin
290
291Pressing this combination runs a command with C<%> replaced by the name of
292the textfile. This command can be set via a resource:
293
294 URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
295
296And the default is likely not useful to anybody but the few people around
297here :)
298
299The name of the textfile is the hex encoded md5 sum of the selection, so
300the same content should lead to the same filename.
301
302After a successful upload the selection will be replaced by the text given
303in the C<selection-pastebin-url> resource (again, the % is the placeholder
304for the filename):
305
306 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
307
80=item example-refresh-hooks 308=item example-refresh-hooks
81 309
82Displays a very simple digital clock in the upper right corner of the 310Displays a very simple digital clock in the upper right corner of the
83window. Illustrates overwriting the refresh callbacks to create your own 311window. Illustrates overwriting the refresh callbacks to create your own
84overlays or changes. 312overlays or changes.
85 313
86=back 314=back
315
316=head1 API DOCUMENTATION
87 317
88=head2 General API Considerations 318=head2 General API Considerations
89 319
90All objects (such as terminals, time watchers etc.) are typical 320All objects (such as terminals, time watchers etc.) are typical
91reference-to-hash objects. The hash can be used to store anything you 321reference-to-hash objects. The hash can be used to store anything you
104=over 4 334=over 4
105 335
106=item $text 336=item $text
107 337
108Rxvt-unicodes special way of encoding text, where one "unicode" character 338Rxvt-unicodes special way of encoding text, where one "unicode" character
109always represents one screen cell. See L<row_t> for a discussion of this format. 339always represents one screen cell. See L<ROW_t> for a discussion of this format.
110 340
111=item $string 341=item $string
112 342
113A perl text string, with an emphasis on I<text>. It can store all unicode 343A perl text string, with an emphasis on I<text>. It can store all unicode
114characters and is to be distinguished with text encoded in a specific 344characters and is to be distinguished with text encoded in a specific
119Either binary data or - more common - a text string encoded in a 349Either binary data or - more common - a text string encoded in a
120locale-specific way. 350locale-specific way.
121 351
122=back 352=back
123 353
354=head2 Extension Objects
355
356Very perl extension is a perl class. A separate perl object is created
357for each terminal and each extension and passed as the first parameter to
358hooks. So extensions can use their C<$self> object without having to think
359about other extensions, with the exception of methods and members that
360begin with an underscore character C<_>: these are reserved for internal
361use.
362
363Although it isn't a C<urxvt::term> object, you can call all methods of the
364C<urxvt::term> class on this object.
365
366It has the following methods and data members:
367
368=over 4
369
370=item $urxvt_term = $self->{term}
371
372Returns the C<urxvt::term> object associated with this instance of the
373extension. This member I<must not> be changed in any way.
374
375=item $self->enable ($hook_name => $cb, [$hook_name => $cb..])
376
377Dynamically enable the given hooks (named without the C<on_> prefix) for
378this extension, replacing any previous hook. This is useful when you want
379to overwrite time-critical hooks only temporarily.
380
381=item $self->disable ($hook_name[, $hook_name..])
382
383Dynamically disable the given hooks.
384
385=back
386
124=head2 Hooks 387=head2 Hooks
125 388
126The following subroutines can be declared in extension files, and will be 389The following subroutines can be declared in extension files, and will be
127called whenever the relevant event happens. 390called whenever the relevant event happens.
128 391
129The first argument passed to them is an object private to each terminal 392The first argument passed to them is an extension oject as described in
130and extension package. You can call all C<urxvt::term> methods on it, but 393the in the C<Extension Objects> section.
131its not a real C<urxvt::term> object. Instead, the real C<urxvt::term>
132object that is shared between all packages is stored in the C<term>
133member. It is, however, blessed intot he package of the extension script,
134so for all practical purposes you can treat an extension script as a class.
135 394
136All of them must return a boolean value. If it is true, then the event 395B<All> of these hooks must return a boolean value. If any of the called
137counts as being I<consumed>, and the invocation of other hooks is skipped, 396hooks returns true, then the event counts as being I<consumed>, and the
138and the relevant action might not be carried out by the C++ code. 397relevant action might not be carried out by the C++ code.
139 398
140When in doubt, return a false value (preferably C<()>). 399I<< When in doubt, return a false value (preferably C<()>). >>
141 400
142=over 4 401=over 4
143 402
144=item on_init $term 403=item on_init $term
145 404
146Called after a new terminal object has been initialized, but before 405Called after a new terminal object has been initialized, but before
147windows are created or the command gets run. Most methods are unsafe to 406windows are created or the command gets run. Most methods are unsafe to
148call or deliver senseless data, as terminal size and other characteristics 407call or deliver senseless data, as terminal size and other characteristics
149have not yet been determined. You can safely query and change resources, 408have not yet been determined. You can safely query and change resources
150though. 409and options, though. For many purposes the C<on_start> hook is a better
410place.
411
412=item on_start $term
413
414Called at the very end of initialisation of a new terminal, just before
415trying to map (display) the toplevel and returning to the mainloop.
416
417=item on_destroy $term
418
419Called whenever something tries to destroy terminal, when the terminal is
420still fully functional (not for long, though).
151 421
152=item on_reset $term 422=item on_reset $term
153 423
154Called after the screen is "reset" for any reason, such as resizing or 424Called after the screen is "reset" for any reason, such as resizing or
155control sequences. Here is where you can react on changes to size-related 425control sequences. Here is where you can react on changes to size-related
156variables. 426variables.
157 427
158=item on_start $term 428=item on_child_start $term, $pid
159 429
160Called at the very end of initialisation of a new terminal, just before 430Called just after the child process has been C<fork>ed.
161returning to the mainloop. 431
432=item on_child_exit $term, $status
433
434Called just after the child process has exited. C<$status> is the status
435from C<waitpid>.
162 436
163=item on_sel_make $term, $eventtime 437=item on_sel_make $term, $eventtime
164 438
165Called whenever a selection has been made by the user, but before the 439Called whenever a selection has been made by the user, but before the
166selection text is copied, so changes to the beginning, end or type of the 440selection text is copied, so changes to the beginning, end or type of the
180=item on_sel_extend $term 454=item on_sel_extend $term
181 455
182Called whenever the user tries to extend the selection (e.g. with a double 456Called whenever the user tries to extend the selection (e.g. with a double
183click) and is either supposed to return false (normal operation), or 457click) and is either supposed to return false (normal operation), or
184should extend the selection itelf and return true to suppress the built-in 458should extend the selection itelf and return true to suppress the built-in
185processing. 459processing. This can happen multiple times, as long as the callback
460returns true, it will be called on every further click by the user and is
461supposed to enlarge the selection more and more, if possible.
186 462
187See the F<selection> example extension. 463See the F<selection> example extension.
188 464
189=item on_view_change $term, $offset 465=item on_view_change $term, $offset
190 466
199than the scroll back buffer or the terminal. 475than the scroll back buffer or the terminal.
200 476
201It is called before lines are scrolled out (so rows 0 .. min ($lines - 1, 477It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
202$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total 478$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
203number of lines that will be in the scrollback buffer. 479number of lines that will be in the scrollback buffer.
204
205=item on_tty_activity $term *NYI*
206
207Called whenever the program(s) running in the urxvt window send output.
208 480
209=item on_osc_seq $term, $string 481=item on_osc_seq $term, $string
210 482
211Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 483Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
212operating system command) is processed. Cursor position and other state 484operating system command) is processed. Cursor position and other state
225can filter/change and output the text yourself by returning a true value 497can filter/change and output the text yourself by returning a true value
226and calling C<< $term->scr_add_lines >> yourself. Please note that this 498and calling C<< $term->scr_add_lines >> yourself. Please note that this
227might be very slow, however, as your hook is called for B<all> text being 499might be very slow, however, as your hook is called for B<all> text being
228output. 500output.
229 501
502=item on_tt_write $term, $octets
503
504Called whenever some data is written to the tty/pty and can be used to
505suppress or filter tty input.
506
230=item on_line_update $term, $row 507=item on_line_update $term, $row
231 508
232Called whenever a line was updated or changed. Can be used to filter 509Called whenever a line was updated or changed. Can be used to filter
233screen output (e.g. underline urls or other useless stuff). Only lines 510screen output (e.g. underline urls or other useless stuff). Only lines
234that are being shown will be filtered, and, due to performance reasons, 511that are being shown will be filtered, and, due to performance reasons,
250 527
251=item on_refresh_end $term 528=item on_refresh_end $term
252 529
253Called just after the screen gets redrawn. See C<on_refresh_begin>. 530Called just after the screen gets redrawn. See C<on_refresh_begin>.
254 531
255=item on_keyboard_command $term, $string 532=item on_user_command $term, $string
256 533
257Called whenever the user presses a key combination that has a 534Called whenever the a user-configured event is being activated (e.g. via
258C<perl:string> action bound to it (see description of the B<keysym> 535a C<perl:string> action bound to a key, see description of the B<keysym>
259resource in the @@RXVT_NAME@@(1) manpage). 536resource in the @@RXVT_NAME@@(1) manpage).
537
538The event is simply the action string. This interface is assumed to change
539slightly in the future.
540
541=item on_x_event $term, $event
542
543Called on every X event received on the vt window (and possibly other
544windows). Should only be used as a last resort. Most event structure
545members are not passed.
260 546
261=item on_focus_in $term 547=item on_focus_in $term
262 548
263Called whenever the window gets the keyboard focus, before rxvt-unicode 549Called whenever the window gets the keyboard focus, before rxvt-unicode
264does focus in processing. 550does focus in processing.
266=item on_focus_out $term 552=item on_focus_out $term
267 553
268Called wheneever the window loses keyboard focus, before rxvt-unicode does 554Called wheneever the window loses keyboard focus, before rxvt-unicode does
269focus out processing. 555focus out processing.
270 556
557=item on_configure_notify $term, $event
558
559=item on_property_notify $term, $event
560
271=item on_key_press $term, $event, $octets 561=item on_key_press $term, $event, $keysym, $octets
272 562
273=item on_key_release $term, $event 563=item on_key_release $term, $event, $keysym
274 564
275=item on_button_press $term, $event 565=item on_button_press $term, $event
276 566
277=item on_button_release $term, $event 567=item on_button_release $term, $event
278 568
284 574
285Called whenever the corresponding X event is received for the terminal If 575Called whenever the corresponding X event is received for the terminal If
286the hook returns true, then the even will be ignored by rxvt-unicode. 576the hook returns true, then the even will be ignored by rxvt-unicode.
287 577
288The event is a hash with most values as named by Xlib (see the XEvent 578The event is a hash with most values as named by Xlib (see the XEvent
289manpage), with the additional members C<row> and C<col>, which are the row 579manpage), with the additional members C<row> and C<col>, which are the
290and column under the mouse cursor. 580(real, not screen-based) row and column under the mouse cursor.
291 581
292C<on_key_press> additionally receives the string rxvt-unicode would 582C<on_key_press> additionally receives the string rxvt-unicode would
293output, if any, in locale-specific encoding. 583output, if any, in locale-specific encoding.
294 584
295subwindow. 585subwindow.
296 586
587=item on_client_message $term, $event
588
589=item on_wm_protocols $term, $event
590
591=item on_wm_delete_window $term, $event
592
593Called when various types of ClientMessage events are received (all with
594format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
595
297=back 596=back
298 597
598=cut
599
600package urxvt;
601
602use utf8;
603use strict;
604use Carp ();
605use Scalar::Util ();
606use List::Util ();
607
608our $VERSION = 1;
609our $TERM;
610our @TERM_INIT;
611our @TERM_EXT;
612our @HOOKNAME;
613our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
614our %OPTION;
615
616our $LIBDIR;
617our $RESNAME;
618our $RESCLASS;
619our $RXVTNAME;
620
621our $NOCHAR = chr 0xffff;
622
299=head2 Variables in the C<urxvt> Package 623=head2 Variables in the C<urxvt> Package
300 624
301=over 4 625=over 4
626
627=item $urxvt::LIBDIR
628
629The rxvt-unicode library directory, where, among other things, the perl
630modules and scripts are stored.
631
632=item $urxvt::RESCLASS, $urxvt::RESCLASS
633
634The resource class and name rxvt-unicode uses to look up X resources.
635
636=item $urxvt::RXVTNAME
637
638The basename of the installed binaries, usually C<urxvt>.
302 639
303=item $urxvt::TERM 640=item $urxvt::TERM
304 641
305The current terminal. This variable stores the current C<urxvt::term> 642The current terminal. This variable stores the current C<urxvt::term>
306object, whenever a callback/hook is executing. 643object, whenever a callback/hook is executing.
307 644
645=item @urxvt::TERM_INIT
646
647All coderefs in this array will be called as methods of the next newly
648created C<urxvt::term> object (during the C<on_init> phase). The array
649gets cleared before the codereferences that were in it are being executed,
650so coderefs can push themselves onto it again if they so desire.
651
652This complements to the perl-eval commandline option, but gets executed
653first.
654
655=item @urxvt::TERM_EXT
656
657Works similar to C<@TERM_INIT>, but contains perl package/class names, which
658get registered as normal extensions after calling the hooks in C<@TERM_INIT>
659but before other extensions. Gets cleared just like C<@TERM_INIT>.
660
308=back 661=back
309 662
310=head2 Functions in the C<urxvt> Package 663=head2 Functions in the C<urxvt> Package
311 664
312=over 4 665=over 4
313
314=item $term = new urxvt [arg...]
315
316Creates a new terminal, very similar as if you had started it with
317C<system $binfile, arg...>. Croaks (and probably outputs an error message)
318if the new instance couldn't be created. Returns C<undef> if the new
319instance didn't initialise perl, and the terminal object otherwise. The
320C<init> and C<start> hooks will be called during the call.
321 666
322=item urxvt::fatal $errormessage 667=item urxvt::fatal $errormessage
323 668
324Fatally aborts execution with the given error message. Avoid at all 669Fatally aborts execution with the given error message. Avoid at all
325costs! The only time this is acceptable is when the terminal process 670costs! The only time this is acceptable is when the terminal process
332that calls this function. 677that calls this function.
333 678
334Using this function has the advantage that its output ends up in the 679Using this function has the advantage that its output ends up in the
335correct place, e.g. on stderr of the connecting urxvtc client. 680correct place, e.g. on stderr of the connecting urxvtc client.
336 681
682Messages have a size limit of 1023 bytes currently.
683
684=item @terms = urxvt::termlist
685
686Returns all urxvt::term objects that exist in this process, regardless of
687wether they are started, being destroyed etc., so be careful. Only term
688objects that have perl extensions attached will be returned (because there
689is no urxvt::term objet associated with others).
690
337=item $time = urxvt::NOW 691=item $time = urxvt::NOW
338 692
339Returns the "current time" (as per the event loop). 693Returns the "current time" (as per the event loop).
340 694
341=item urxvt::CurrentTime 695=item urxvt::CurrentTime
342 696
343=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, 697=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
344Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, 698Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
345Button4Mask, Button5Mask, AnyModifier 699Button4Mask, Button5Mask, AnyModifier
346 700
701=item urxvt::NoEventMask, KeyPressMask, KeyReleaseMask,
702ButtonPressMask, ButtonReleaseMask, EnterWindowMask, LeaveWindowMask,
703PointerMotionMask, PointerMotionHintMask, Button1MotionMask, Button2MotionMask,
704Button3MotionMask, Button4MotionMask, Button5MotionMask, ButtonMotionMask,
705KeymapStateMask, ExposureMask, VisibilityChangeMask, StructureNotifyMask,
706ResizeRedirectMask, SubstructureNotifyMask, SubstructureRedirectMask,
707FocusChangeMask, PropertyChangeMask, ColormapChangeMask, OwnerGrabButtonMask
708
709=item urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify,
710EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose,
711GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify, DestroyNotify,
712UnmapNotify, MapNotify, MapRequest, ReparentNotify, ConfigureNotify,
713ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify,
714CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest,
715SelectionNotify, ColormapNotify, ClientMessage, MappingNotify
716
347Various constants for use in X events. 717Various constants for use in X calls and event processing.
348 718
349=back 719=back
350 720
351=head2 RENDITION 721=head2 RENDITION
352 722
379 749
380=item $background = urxvt::GET_BASEBG $rend 750=item $background = urxvt::GET_BASEBG $rend
381 751
382Return the foreground/background colour index, respectively. 752Return the foreground/background colour index, respectively.
383 753
384=item $rend = urxvt::SET_FGCOLOR ($rend, $new_colour) 754=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
385 755
386=item $rend = urxvt::SET_BGCOLOR ($rend, $new_colour) 756=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
757
758=item $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
387 759
388Replace the foreground/background colour in the rendition mask with the 760Replace the foreground/background colour in the rendition mask with the
389specified one. 761specified one.
390 762
391=item $value = urxvt::GET_CUSTOM ($rend) 763=item $value = urxvt::GET_CUSTOM $rend
392 764
393Return the "custom" value: Every rendition has 5 bits for use by 765Return the "custom" value: Every rendition has 5 bits for use by
394extensions. They can be set and changed as you like and are initially 766extensions. They can be set and changed as you like and are initially
395zero. 767zero.
396 768
397=item $rend = urxvt::SET_CUSTOM ($rend, $new_value) 769=item $rend = urxvt::SET_CUSTOM $rend, $new_value
398 770
399Change the custom value. 771Change the custom value.
400 772
401=back 773=back
402 774
403=cut 775=cut
404 776
405package urxvt;
406
407use utf8;
408use strict;
409use Scalar::Util ();
410use List::Util ();
411
412our $TERM;
413our @HOOKNAME;
414our %OPTION;
415our $LIBDIR;
416
417BEGIN { 777BEGIN {
418 urxvt->bootstrap;
419
420 # overwrite perl's warn 778 # overwrite perl's warn
421 *CORE::GLOBAL::warn = sub { 779 *CORE::GLOBAL::warn = sub {
422 my $msg = join "", @_; 780 my $msg = join "", @_;
423 $msg .= "\n" 781 $msg .= "\n"
424 unless $msg =~ /\n$/; 782 unless $msg =~ /\n$/;
425 urxvt::warn ($msg); 783 urxvt::warn ($msg);
426 }; 784 };
427} 785}
428 786
429my @hook_count; 787no warnings 'utf8';
788
430my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 789my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
431 790
432sub verbose { 791sub verbose {
433 my ($level, $msg) = @_; 792 my ($level, $msg) = @_;
434 warn "$msg\n" if $level <= $verbosity; 793 warn "$msg\n" if $level <= $verbosity;
435} 794}
436 795
437# find on_xxx subs in the package and register them
438# as hooks
439sub register_package($) {
440 my ($pkg) = @_;
441
442 for my $htype (0.. $#HOOKNAME) {
443 my $name = $HOOKNAME[$htype];
444
445 my $ref = $pkg->can ("on_" . lc $name)
446 or next;
447
448 $TERM->{_hook}[$htype]{$pkg} = $ref;
449 $hook_count[$htype]++
450 or set_should_invoke $htype, 1;
451 }
452}
453
454my $extension_pkg = "extension0000";
455my %extension_pkg; 796my %extension_pkg;
456 797
457# load a single script into its own package, once only 798# load a single script into its own package, once only
458sub extension_package($) { 799sub extension_package($) {
459 my ($path) = @_; 800 my ($path) = @_;
460 801
461 $extension_pkg{$path} ||= do { 802 $extension_pkg{$path} ||= do {
462 my $pkg = "urxvt::" . ($extension_pkg++); 803 $path =~ /([^\/\\]+)$/;
804 my $pkg = $1;
805 $pkg =~ s/[^[:word:]]/_/g;
806 $pkg = "urxvt::ext::$pkg";
463 807
464 verbose 3, "loading extension '$path' into package '$pkg'"; 808 verbose 3, "loading extension '$path' into package '$pkg'";
465 809
466 open my $fh, "<:raw", $path 810 open my $fh, "<:raw", $path
467 or die "$path: $!"; 811 or die "$path: $!";
468 812
469 my $source = "package $pkg; use strict; use utf8;\n" 813 my $source =
470 . "use base urxvt::term::proxy::;\n" 814 "package $pkg; use strict; use utf8; no warnings 'utf8';\n"
471 . "#line 1 \"$path\"\n{\n" 815 . "#line 1 \"$path\"\n{\n"
472 . (do { local $/; <$fh> }) 816 . (do { local $/; <$fh> })
473 . "\n};\n1"; 817 . "\n};\n1";
474 818
819 eval $source
475 eval $source or die "$path: $@"; 820 or die "$path: $@";
476 821
477 $pkg 822 $pkg
478 } 823 }
479} 824}
480 825
486 my $htype = shift; 831 my $htype = shift;
487 832
488 if ($htype == 0) { # INIT 833 if ($htype == 0) { # INIT
489 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 834 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
490 835
491 my %want_ext; 836 my %ext_arg;
492 837
838 {
839 my @init = @TERM_INIT;
840 @TERM_INIT = ();
841 $_->($TERM) for @init;
842 my @pkg = @TERM_EXT;
843 @TERM_EXT = ();
844 $TERM->register_package ($_) for @pkg;
845 }
846
493 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) { 847 for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
494 if ($_ eq "default") { 848 if ($_ eq "default") {
495 $want_ext{$_}++ for qw(selection option-popup); 849 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback readline);
496 } elsif (/^-(.*)$/) { 850 } elsif (/^-(.*)$/) {
497 delete $want_ext{$1}; 851 delete $ext_arg{$1};
852 } elsif (/^([^<]+)<(.*)>$/) {
853 push @{ $ext_arg{$1} }, $2;
498 } else { 854 } else {
499 $want_ext{$_}++; 855 $ext_arg{$_} ||= [];
500 } 856 }
501 } 857 }
502 858
503 for my $ext (keys %want_ext) { 859 while (my ($ext, $argv) = each %ext_arg) {
504 my @files = grep -f $_, map "$_/$ext", @dirs; 860 my @files = grep -f $_, map "$_/$ext", @dirs;
505 861
506 if (@files) { 862 if (@files) {
507 register_package extension_package $files[0]; 863 $TERM->register_package (extension_package $files[0], $argv);
508 } else { 864 } else {
509 warn "perl extension '$ext' not found in perl library search path\n"; 865 warn "perl extension '$ext' not found in perl library search path\n";
510 } 866 }
511 } 867 }
868
869 eval "#line 1 \"--perl-eval resource/argument\"\n" . $TERM->resource ("perl_eval");
870 warn $@ if $@;
512 } 871 }
513 872
514 $retval = undef; 873 $retval = undef;
515 874
516 if (my $cb = $TERM->{_hook}[$htype]) { 875 if (my $cb = $TERM->{_hook}[$htype]) {
518 if $verbosity >= 10; 877 if $verbosity >= 10;
519 878
520 keys %$cb; 879 keys %$cb;
521 880
522 while (my ($pkg, $cb) = each %$cb) { 881 while (my ($pkg, $cb) = each %$cb) {
523 eval { 882 my $retval_ = eval { $cb->($TERM->{_pkg}{$pkg}, @_) };
524 $retval = $cb->( 883 $retval ||= $retval_;
525 $TERM->{_pkg}{$pkg} ||= do {
526 my $proxy = bless { }, $pkg;
527 Scalar::Util::weaken ($proxy->{term} = $TERM);
528 $proxy
529 },
530 @_,
531 ) and last;
532 };
533 warn $@ if $@;#d#
534 }
535 }
536 884
537 if ($htype == 1) { # DESTROY 885 if ($@) {
538 # remove hooks if unused 886 $TERM->ungrab; # better to lose the grab than the session
539 if (my $hook = $TERM->{_hook}) { 887 warn $@;
540 for my $htype (0..$#$hook) {
541 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
542 or set_should_invoke $htype, 0;
543 } 888 }
544 } 889 }
545 890
891 verbose 11, "$HOOKNAME[$htype] returning <$retval>"
892 if $verbosity >= 11;
893 }
894
895 if ($htype == 1) { # DESTROY
546 # clear package objects 896 # clear package objects
547 %$_ = () for values %{ $TERM->{_pkg} }; 897 %$_ = () for values %{ $TERM->{_pkg} };
548 898
549 # clear package 899 # clear package
550 %$TERM = (); 900 %$TERM = ();
551 } 901 }
552 902
553 $retval 903 $retval
554} 904}
555 905
556sub urxvt::term::proxy::AUTOLOAD { 906sub SET_COLOR($$$) {
557 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/ 907 SET_BGCOLOR (SET_FGCOLOR ($_[0], $_[1]), $_[2])
908}
909
910# urxvt::term::extension
911
912package urxvt::term::extension;
913
914sub enable {
915 my ($self, %hook) = @_;
916 my $pkg = $self->{_pkg};
917
918 while (my ($name, $cb) = each %hook) {
919 my $htype = $HOOKTYPE{uc $name};
920 defined $htype
921 or Carp::croak "unsupported hook type '$name'";
922
923 $self->set_should_invoke ($htype, +1)
924 unless exists $self->{term}{_hook}[$htype]{$pkg};
925
926 $self->{term}{_hook}[$htype]{$pkg} = $cb;
927 }
928}
929
930sub disable {
931 my ($self, @hook) = @_;
932 my $pkg = $self->{_pkg};
933
934 for my $name (@hook) {
935 my $htype = $HOOKTYPE{uc $name};
936 defined $htype
937 or Carp::croak "unsupported hook type '$name'";
938
939 $self->set_should_invoke ($htype, -1)
940 if delete $self->{term}{_hook}[$htype]{$pkg};
941 }
942}
943
944our $AUTOLOAD;
945
946sub AUTOLOAD {
947 $AUTOLOAD =~ /:([^:]+)$/
558 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable"; 948 or die "FATAL: \$AUTOLOAD '$AUTOLOAD' unparsable";
559 949
560 eval qq{ 950 eval qq{
561 sub $urxvt::term::proxy::AUTOLOAD { 951 sub $AUTOLOAD {
562 my \$proxy = shift; 952 my \$proxy = shift;
563 \$proxy->{term}->$1 (\@_) 953 \$proxy->{term}->$1 (\@_)
564 } 954 }
565 1 955 1
566 } or die "FATAL: unable to compile method forwarder: $@"; 956 } or die "FATAL: unable to compile method forwarder: $@";
567 957
568 goto &$urxvt::term::proxy::AUTOLOAD; 958 goto &$AUTOLOAD;
569} 959}
960
961sub DESTROY {
962 # nop
963}
964
965# urxvt::destroy_hook
570 966
571sub urxvt::destroy_hook::DESTROY { 967sub urxvt::destroy_hook::DESTROY {
572 ${$_[0]}->(); 968 ${$_[0]}->();
573} 969}
574 970
575sub urxvt::destroy_hook(&) { 971sub urxvt::destroy_hook(&) {
576 bless \shift, urxvt::destroy_hook:: 972 bless \shift, urxvt::destroy_hook::
577} 973}
578 974
975package urxvt::anyevent;
976
977=head2 The C<urxvt::anyevent> Class
978
979The sole purpose of this class is to deliver an interface to the
980C<AnyEvent> module - any module using it will work inside urxvt without
981further programming. The only exception is that you cannot wait on
982condition variables, but non-blocking condvar use is ok. What this means
983is that you cannot use blocking APIs, but the non-blocking variant should
984work.
985
986=cut
987
988our $VERSION = 1;
989
990$INC{"urxvt/anyevent.pm"} = 1; # mark us as there
991push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
992
993sub timer {
994 my ($class, %arg) = @_;
995
996 my $cb = $arg{cb};
997
998 urxvt::timer
999 ->new
1000 ->start (urxvt::NOW + $arg{after})
1001 ->cb (sub {
1002 $_[0]->stop; # need to cancel manually
1003 $cb->();
1004 })
1005}
1006
1007sub io {
1008 my ($class, %arg) = @_;
1009
1010 my $cb = $arg{cb};
1011
1012 bless [$arg{fh}, urxvt::iow
1013 ->new
1014 ->fd (fileno $arg{fh})
1015 ->events (($arg{poll} =~ /r/ ? 1 : 0)
1016 | ($arg{poll} =~ /w/ ? 2 : 0))
1017 ->start
1018 ->cb (sub {
1019 $cb->(($_[1] & 1 ? 'r' : '')
1020 . ($_[1] & 2 ? 'w' : ''));
1021 })],
1022 urxvt::anyevent::
1023}
1024
1025sub DESTROY {
1026 $_[0][1]->stop;
1027}
1028
1029sub condvar {
1030 bless \my $flag, urxvt::anyevent::condvar::
1031}
1032
1033sub urxvt::anyevent::condvar::broadcast {
1034 ${$_[0]}++;
1035}
1036
1037sub urxvt::anyevent::condvar::wait {
1038 unless (${$_[0]}) {
1039 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API";
1040 }
1041}
1042
1043package urxvt::term;
1044
579=head2 The C<urxvt::term> Class 1045=head2 The C<urxvt::term> Class
580 1046
581=over 4 1047=over 4
582 1048
1049=cut
1050
1051# find on_xxx subs in the package and register them
1052# as hooks
1053sub register_package {
1054 my ($self, $pkg, $argv) = @_;
1055
1056 no strict 'refs';
1057
1058 urxvt::verbose 6, "register package $pkg to $self";
1059
1060 @{"$pkg\::ISA"} = urxvt::term::extension::;
1061
1062 my $proxy = bless {
1063 _pkg => $pkg,
1064 argv => $argv,
1065 }, $pkg;
1066 Scalar::Util::weaken ($proxy->{term} = $self);
1067
1068 $self->{_pkg}{$pkg} = $proxy;
1069
1070 for my $name (@HOOKNAME) {
1071 if (my $ref = $pkg->can ("on_" . lc $name)) {
1072 $proxy->enable ($name => $ref);
1073 }
1074 }
1075}
1076
1077=item $term = new urxvt::term $envhashref, $rxvtname, [arg...]
1078
1079Creates a new terminal, very similar as if you had started it with system
1080C<$rxvtname, arg...>. C<$envhashref> must be a reference to a C<%ENV>-like
1081hash which defines the environment of the new terminal.
1082
1083Croaks (and probably outputs an error message) if the new instance
1084couldn't be created. Returns C<undef> if the new instance didn't
1085initialise perl, and the terminal object otherwise. The C<init> and
1086C<start> hooks will be called before this call returns, and are free to
1087refer to global data (which is race free).
1088
1089=cut
1090
1091sub new {
1092 my ($class, $env, @args) = @_;
1093
1094 $env or Carp::croak "environment hash missing in call to urxvt::term->new";
1095 @args or Carp::croak "name argument missing in call to urxvt::term->new";
1096
1097 _new ([ map "$_=$env->{$_}", keys %$env ], \@args);
1098}
1099
583=item $term->destroy 1100=item $term->destroy
584 1101
585Destroy the terminal object (close the window, free resources etc.). 1102Destroy the terminal object (close the window, free resources
1103etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event
1104watchers (timers, io watchers) are still active.
1105
1106=item $term->exec_async ($cmd[, @args])
1107
1108Works like the combination of the C<fork>/C<exec> builtins, which executes
1109("starts") programs in the background. This function takes care of setting
1110the user environment before exec'ing the command (e.g. C<PATH>) and should
1111be preferred over explicit calls to C<exec> or C<system>.
1112
1113Returns the pid of the subprocess or C<undef> on error.
1114
1115=cut
1116
1117sub exec_async {
1118 my $self = shift;
1119
1120 my $pid = fork;
1121
1122 return $pid
1123 if !defined $pid or $pid;
1124
1125 %ENV = %{ $self->env };
1126
1127 exec @_;
1128 urxvt::_exit 255;
1129}
586 1130
587=item $isset = $term->option ($optval[, $set]) 1131=item $isset = $term->option ($optval[, $set])
588 1132
589Returns true if the option specified by C<$optval> is enabled, and 1133Returns true if the option specified by C<$optval> is enabled, and
590optionally change it. All option values are stored by name in the hash 1134optionally change it. All option values are stored by name in the hash
593Here is a a likely non-exhaustive list of option names, please see the 1137Here is a a likely non-exhaustive list of option names, please see the
594source file F</src/optinc.h> to see the actual list: 1138source file F</src/optinc.h> to see the actual list:
595 1139
596 borderLess console cursorBlink cursorUnderline hold iconic insecure 1140 borderLess console cursorBlink cursorUnderline hold iconic insecure
597 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 1141 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
598 pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating 1142 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
599 scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer 1143 scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput
600 secondaryScreen secondaryScroll skipBuiltinGlyphs transparent 1144 scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs
601 tripleclickwords utmpInhibit visualBell 1145 transparent tripleclickwords utmpInhibit visualBell
602 1146
603=item $value = $term->resource ($name[, $newval]) 1147=item $value = $term->resource ($name[, $newval])
604 1148
605Returns the current resource value associated with a given name and 1149Returns the current resource value associated with a given name and
606optionally sets a new value. Setting values is most useful in the C<init> 1150optionally sets a new value. Setting values is most useful in the C<init>
623 1167
624 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1168 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
625 borderLess color cursorBlink cursorUnderline cutchars delete_key 1169 borderLess color cursorBlink cursorUnderline cutchars delete_key
626 display_name embed ext_bwidth fade font geometry hold iconName 1170 display_name embed ext_bwidth fade font geometry hold iconName
627 imFont imLocale inputMethod insecure int_bwidth intensityStyles 1171 imFont imLocale inputMethod insecure int_bwidth intensityStyles
628 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier 1172 italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier
629 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2 1173 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
630 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 1174 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
631 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 1175 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
632 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 1176 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
633 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 1177 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
634 shade term_name title transparent transparent_all tripleclickwords 1178 secondaryScreen secondaryScroll selectstyle shade term_name title
635 utmpInhibit visualBell 1179 transient_for transparent transparent_all tripleclickwords utmpInhibit
1180 visualBell
636 1181
637=cut 1182=cut
638 1183
639sub urxvt::term::resource($$;$) { 1184sub resource($$;$) {
640 my ($self, $name) = (shift, shift); 1185 my ($self, $name) = (shift, shift);
641 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 1186 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
642 &urxvt::term::_resource 1187 &urxvt::term::_resource
643} 1188}
644 1189
1190=item $value = $term->x_resource ($pattern)
1191
1192Returns the X-Resource for the given pattern, excluding the program or
1193class name, i.e. C<< $term->x_resource ("boldFont") >> should return the
1194same value as used by this instance of rxvt-unicode. Returns C<undef> if no
1195resource with that pattern exists.
1196
1197This method should only be called during the C<on_start> hook, as there is
1198only one resource database per display, and later invocations might return
1199the wrong resources.
1200
1201=item $success = $term->parse_keysym ($keysym_spec, $command_string)
1202
1203Adds a keymap translation exactly as specified via a resource. See the
1204C<keysym> resource in the @@RXVT_NAME@@(1) manpage.
1205
645=item $rend = $term->rstyle ([$new_rstyle]) 1206=item $rend = $term->rstyle ([$new_rstyle])
646 1207
647Return and optionally change the current rendition. Text that is output by 1208Return and optionally change the current rendition. Text that is output by
648the terminal application will use this style. 1209the terminal application will use this style.
649 1210
659=item ($row, $col) = $term->selection_end ([$row, $col]) 1220=item ($row, $col) = $term->selection_end ([$row, $col])
660 1221
661Return the current values of the selection mark, begin or end positions, 1222Return the current values of the selection mark, begin or end positions,
662and optionally set them to new values. 1223and optionally set them to new values.
663 1224
1225=item $term->selection_make ($eventtime[, $rectangular])
1226
1227Tries to make a selection as set by C<selection_beg> and
1228C<selection_end>. If C<$rectangular> is true (default: false), a
1229rectangular selection will be made. This is the prefered function to make
1230a selection.
1231
664=item $success = $term->selection_grab ($eventtime) 1232=item $success = $term->selection_grab ($eventtime)
665 1233
666Try to request the primary selection from the server (for example, as set 1234Try to request the primary selection text from the server (for example, as
667by the next method). 1235set by the next method). No visual feedback will be given. This function
1236is mostly useful from within C<on_sel_grab> hooks.
668 1237
669=item $oldtext = $term->selection ([$newtext]) 1238=item $oldtext = $term->selection ([$newtext])
670 1239
671Return the current selection text and optionally replace it by C<$newtext>. 1240Return the current selection text and optionally replace it by C<$newtext>.
672 1241
673#=item $term->overlay ($x, $y, $text) 1242=item $term->overlay_simple ($x, $y, $text)
674# 1243
675#Create a simple multi-line overlay box. See the next method for details. 1244Create a simple multi-line overlay box. See the next method for details.
676# 1245
677#=cut 1246=cut
678# 1247
679#sub urxvt::term::scr_overlay { 1248sub overlay_simple {
680# my ($self, $x, $y, $text) = @_; 1249 my ($self, $x, $y, $text) = @_;
681# 1250
682# my @lines = split /\n/, $text; 1251 my @lines = split /\n/, $text;
683# 1252
684# my $w = 0; 1253 my $w = List::Util::max map $self->strwidth ($_), @lines;
685# for (map $self->strwidth ($_), @lines) { 1254
686# $w = $_ if $w < $_;
687# }
688#
689# $self->scr_overlay_new ($x, $y, $w, scalar @lines); 1255 my $overlay = $self->overlay ($x, $y, $w, scalar @lines);
690# $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 1256 $overlay->set (0, $_, $lines[$_]) for 0.. $#lines;
691#} 1257
1258 $overlay
1259}
692 1260
693=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 1261=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
694 1262
695Create a new (empty) overlay at the given position with the given 1263Create a new (empty) overlay at the given position with the given
696width/height. C<$rstyle> defines the initial rendition style 1264width/height. C<$rstyle> defines the initial rendition style
731C<$event> I<must> be the event causing the menu to pop up (a button event, 1299C<$event> I<must> be the event causing the menu to pop up (a button event,
732currently). 1300currently).
733 1301
734=cut 1302=cut
735 1303
736sub urxvt::term::popup { 1304sub popup {
737 my ($self, $event) = @_; 1305 my ($self, $event) = @_;
738 1306
739 $self->grab ($event->{time}, 1) 1307 $self->grab ($event->{time}, 1)
740 or return; 1308 or return;
741 1309
763 1331
764=item $string = $term->locale_decode ($octets) 1332=item $string = $term->locale_decode ($octets)
765 1333
766Convert the given locale-encoded octets into a perl string. 1334Convert the given locale-encoded octets into a perl string.
767 1335
1336=item $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
1337
1338XORs the rendition values in the given span with the provided value
1339(default: C<RS_RVid>), which I<MUST NOT> contain font styles. Useful in
1340refresh hooks to provide effects similar to the selection.
1341
1342=item $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, $rstyle2]])
1343
1344Similar to C<scr_xor_span>, but xors a rectangle instead. Trailing
1345whitespace will additionally be xored with the C<$rstyle2>, which defaults
1346to C<RS_RVid | RS_Uline>, which removes reverse video again and underlines
1347it instead. Both styles I<MUST NOT> contain font styles.
1348
1349=item $term->scr_bell
1350
1351Ring the bell!
1352
768=item $term->scr_add_lines ($string) 1353=item $term->scr_add_lines ($string)
769 1354
770Write the given text string to the screen, as if output by the application 1355Write the given text string to the screen, as if output by the application
771running inside the terminal. It may not contain command sequences (escape 1356running inside the terminal. It may not contain command sequences (escape
772codes), but is free to use line feeds, carriage returns and tabs. The 1357codes), but is free to use line feeds, carriage returns and tabs. The
774 1359
775Normally its not a good idea to use this function, as programs might be 1360Normally its not a good idea to use this function, as programs might be
776confused by changes in cursor position or scrolling. Its useful inside a 1361confused by changes in cursor position or scrolling. Its useful inside a
777C<on_add_lines> hook, though. 1362C<on_add_lines> hook, though.
778 1363
1364=item $term->scr_change_screen ($screen)
1365
1366Switch to given screen - 0 primary, 1 secondary.
1367
779=item $term->cmd_parse ($octets) 1368=item $term->cmd_parse ($octets)
780 1369
781Similar to C<scr_add_lines>, but the argument must be in the 1370Similar to C<scr_add_lines>, but the argument must be in the
782locale-specific encoding of the terminal and can contain command sequences 1371locale-specific encoding of the terminal and can contain command sequences
783(escape codes) that will be interpreted. 1372(escape codes) that will be interpreted.
786 1375
787Write the octets given in C<$data> to the tty (i.e. as program input). To 1376Write the octets given in C<$data> to the tty (i.e. as program input). To
788pass characters instead of octets, you should convert your strings first 1377pass characters instead of octets, you should convert your strings first
789to the locale-specific encoding using C<< $term->locale_encode >>. 1378to the locale-specific encoding using C<< $term->locale_encode >>.
790 1379
1380=item $old_events = $term->pty_ev_events ([$new_events])
1381
1382Replaces the event mask of the pty watcher by the given event mask. Can
1383be used to suppress input and output handling to the pty/tty. See the
1384description of C<< urxvt::timer->events >>. Make sure to always restore
1385the previous value.
1386
1387=item $fd = $term->pty_fd
1388
1389Returns the master file descriptor for the pty in use, or C<-1> if no pty
1390is used.
1391
791=item $windowid = $term->parent 1392=item $windowid = $term->parent
792 1393
793Return the window id of the toplevel window. 1394Return the window id of the toplevel window.
794 1395
795=item $windowid = $term->vt 1396=item $windowid = $term->vt
796 1397
797Return the window id of the terminal window. 1398Return the window id of the terminal window.
798 1399
1400=item $term->vt_emask_add ($x_event_mask)
1401
1402Adds the specified events to the vt event mask. Useful e.g. when you want
1403to receive pointer events all the times:
1404
1405 $term->vt_emask_add (urxvt::PointerMotionMask);
1406
1407=item $term->focus_in
1408
1409=item $term->focus_out
1410
1411=item $term->key_press ($state, $keycode[, $time])
1412
1413=item $term->key_release ($state, $keycode[, $time])
1414
1415Deliver various fake events to to terminal.
1416
799=item $window_width = $term->width 1417=item $window_width = $term->width
800 1418
801=item $window_height = $term->height 1419=item $window_height = $term->height
802 1420
803=item $font_width = $term->fwidth 1421=item $font_width = $term->fwidth
816 1434
817=item $max_scrollback = $term->saveLines 1435=item $max_scrollback = $term->saveLines
818 1436
819=item $nrow_plus_saveLines = $term->total_rows 1437=item $nrow_plus_saveLines = $term->total_rows
820 1438
821=item $lines_in_scrollback = $term->nsaved 1439=item $topmost_scrollback_row = $term->top_row
822 1440
823Return various integers describing terminal characteristics. 1441Return various integers describing terminal characteristics.
1442
1443=item $x_display = $term->display_id
1444
1445Return the DISPLAY used by rxvt-unicode.
1446
1447=item $lc_ctype = $term->locale
1448
1449Returns the LC_CTYPE category string used by this rxvt-unicode.
1450
1451=item $env = $term->env
1452
1453Returns a copy of the environment in effect for the terminal as a hashref
1454similar to C<\%ENV>.
1455
1456=cut
1457
1458sub env {
1459 if (my $env = $_[0]->_env) {
1460 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env }
1461 } else {
1462 +{ %ENV }
1463 }
1464}
824 1465
825=item $modifiermask = $term->ModLevel3Mask 1466=item $modifiermask = $term->ModLevel3Mask
826 1467
827=item $modifiermask = $term->ModMetaMask 1468=item $modifiermask = $term->ModMetaMask
828 1469
829=item $modifiermask = $term->ModNumLockMask 1470=item $modifiermask = $term->ModNumLockMask
830 1471
831Return the modifier masks corresponding to the "ISO Level 3 Shift" (often 1472Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
832AltGr), the meta key (often Alt) and the num lock key, if applicable. 1473AltGr), the meta key (often Alt) and the num lock key, if applicable.
833 1474
1475=item $screen = $term->current_screen
1476
1477Returns the currently displayed screen (0 primary, 1 secondary).
1478
1479=item $cursor_is_hidden = $term->hidden_cursor
1480
1481Returns wether the cursor is currently hidden or not.
1482
834=item $view_start = $term->view_start ([$newvalue]) 1483=item $view_start = $term->view_start ([$newvalue])
835 1484
836Returns the negative row number of the topmost line. Minimum value is 1485Returns the row number of the topmost displayed line. Maximum value is
837C<0>, which displays the normal terminal contents. Larger values scroll 1486C<0>, which displays the normal terminal contents. Lower values scroll
838this many lines into the scrollback buffer. 1487this many lines into the scrollback buffer.
839 1488
840=item $term->want_refresh 1489=item $term->want_refresh
841 1490
842Requests a screen refresh. At the next opportunity, rxvt-unicode will 1491Requests a screen refresh. At the next opportunity, rxvt-unicode will
857line, starting at column C<$start_col> (default C<0>), which is useful 1506line, starting at column C<$start_col> (default C<0>), which is useful
858to replace only parts of a line. The font index in the rendition will 1507to replace only parts of a line. The font index in the rendition will
859automatically be updated. 1508automatically be updated.
860 1509
861C<$text> is in a special encoding: tabs and wide characters that use more 1510C<$text> is in a special encoding: tabs and wide characters that use more
862than one cell when displayed are padded with urxvt::NOCHAR characters 1511than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535)
863(C<chr 65535>). Characters with combining characters and other characters 1512characters. Characters with combining characters and other characters that
864that do not fit into the normal tetx encoding will be replaced with 1513do not fit into the normal tetx encoding will be replaced with characters
865characters in the private use area. 1514in the private use area.
866 1515
867You have to obey this encoding when changing text. The advantage is 1516You have to obey this encoding when changing text. The advantage is
868that C<substr> and similar functions work on screen cells and not on 1517that C<substr> and similar functions work on screen cells and not on
869characters. 1518characters.
870 1519
921Return the row number of the first/last row of the line, respectively. 1570Return the row number of the first/last row of the line, respectively.
922 1571
923=item $offset = $line->offset_of ($row, $col) 1572=item $offset = $line->offset_of ($row, $col)
924 1573
925Returns the character offset of the given row|col pair within the logical 1574Returns the character offset of the given row|col pair within the logical
926line. 1575line. Works for rows outside the line, too, and returns corresponding
1576offsets outside the string.
927 1577
928=item ($row, $col) = $line->coord_of ($offset) 1578=item ($row, $col) = $line->coord_of ($offset)
929 1579
930Translates a string offset into terminal coordinates again. 1580Translates a string offset into terminal coordinates again.
931 1581
932=back 1582=back
933 1583
934=cut 1584=cut
935 1585
936sub urxvt::term::line { 1586sub line {
937 my ($self, $row) = @_; 1587 my ($self, $row) = @_;
938 1588
939 my $maxrow = $self->nrow - 1; 1589 my $maxrow = $self->nrow - 1;
940 1590
941 my ($beg, $end) = ($row, $row); 1591 my ($beg, $end) = ($row, $row);
1005 $offset / $self->{ncol} + $self->{beg}, 1655 $offset / $self->{ncol} + $self->{beg},
1006 $offset % $self->{ncol} 1656 $offset % $self->{ncol}
1007 ) 1657 )
1008} 1658}
1009 1659
1010=item ($row, $col) = $line->coord_of ($offset)
1011=item $text = $term->special_encode $string 1660=item $text = $term->special_encode $string
1012 1661
1013Converts a perl string into the special encoding used by rxvt-unicode, 1662Converts a perl string into the special encoding used by rxvt-unicode,
1014where one character corresponds to one screen cell. See 1663where one character corresponds to one screen cell. See
1015C<< $term->ROW_t >> for details. 1664C<< $term->ROW_t >> for details.
1017=item $string = $term->special_decode $text 1666=item $string = $term->special_decode $text
1018 1667
1019Converts rxvt-unicodes text reprsentation into a perl string. See 1668Converts rxvt-unicodes text reprsentation into a perl string. See
1020C<< $term->ROW_t >> for details. 1669C<< $term->ROW_t >> for details.
1021 1670
1671=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1672
1673=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1674
1675Register/unregister a synchronous button grab. See the XGrabButton
1676manpage.
1677
1678=item $success = $term->grab ($eventtime[, $sync])
1679
1680Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1681synchronous (C<$sync> is true). Also remembers the grab timestampe.
1682
1683=item $term->allow_events_async
1684
1685Calls XAllowEvents with AsyncBoth for the most recent grab.
1686
1687=item $term->allow_events_sync
1688
1689Calls XAllowEvents with SyncBoth for the most recent grab.
1690
1691=item $term->allow_events_replay
1692
1693Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most
1694recent grab.
1695
1696=item $term->ungrab
1697
1698Calls XUngrab for the most recent grab. Is called automatically on
1699evaluation errors, as it is better to lose the grab in the error case as
1700the session.
1701
1702=item $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
1703
1704=item $atom_name = $term->XGetAtomName ($atom)
1705
1706=item @atoms = $term->XListProperties ($window)
1707
1708=item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
1709
1710=item $term->XChangeWindowProperty ($window, $property, $type, $format, $octets)
1711
1712=item $term->XDeleteProperty ($window, $property)
1713
1714=item $window = $term->DefaultRootWindow
1715
1716=item $term->XReparentWindow ($window, $parent, [$x, $y])
1717
1718=item $term->XMapWindow ($window)
1719
1720=item $term->XUnmapWindow ($window)
1721
1722=item $term->XMoveResizeWindow ($window, $x, $y, $width, $height)
1723
1724=item ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x, $y)
1725
1726=item $term->XChangeInput ($window, $add_events[, $del_events])
1727
1728Various X or X-related functions. The C<$term> object only serves as
1729the source of the display, otherwise those functions map more-or-less
1730directory onto the X functions of the same name.
1731
1022=back 1732=back
1023 1733
1734=cut
1735
1736package urxvt::popup;
1737
1024=head2 The C<urxvt::popup> Class 1738=head2 The C<urxvt::popup> Class
1025 1739
1026=over 4 1740=over 4
1027 1741
1028=cut 1742=cut
1029
1030package urxvt::popup;
1031 1743
1032sub add_item { 1744sub add_item {
1033 my ($self, $item) = @_; 1745 my ($self, $item) = @_;
1034 1746
1035 $item->{rend}{normal} = "\x1b[0;30;47m" unless exists $item->{rend}{normal}; 1747 $item->{rend}{normal} = "\x1b[0;30;47m" unless exists $item->{rend}{normal};
1039 $item->{render} ||= sub { $_[0]{text} }; 1751 $item->{render} ||= sub { $_[0]{text} };
1040 1752
1041 push @{ $self->{item} }, $item; 1753 push @{ $self->{item} }, $item;
1042} 1754}
1043 1755
1044sub add_separator { 1756=item $popup->add_title ($title)
1045 my ($self, $sep) = @_;
1046 1757
1047 $sep ||= "═"; 1758Adds a non-clickable title to the popup.
1048 1759
1049 $self->add_item ({ 1760=cut
1050 rend => { normal => "\x1b[0;30;47m", hover => "\x1b[0;30;47m", active => "\x1b[0;30;47m" },
1051 text => "",
1052 render => sub { $sep x $urxvt::TERM->ncol },
1053 activate => sub { },
1054 });
1055}
1056 1761
1057sub add_title { 1762sub add_title {
1058 my ($self, $title) = @_; 1763 my ($self, $title) = @_;
1059 1764
1060 $self->add_item ({ 1765 $self->add_item ({
1062 text => $title, 1767 text => $title,
1063 activate => sub { }, 1768 activate => sub { },
1064 }); 1769 });
1065} 1770}
1066 1771
1772=item $popup->add_separator ([$sepchr])
1773
1774Creates a separator, optionally using the character given as C<$sepchr>.
1775
1776=cut
1777
1778sub add_separator {
1779 my ($self, $sep) = @_;
1780
1781 $sep ||= "=";
1782
1783 $self->add_item ({
1784 rend => { normal => "\x1b[0;30;47m", hover => "\x1b[0;30;47m", active => "\x1b[0;30;47m" },
1785 text => "",
1786 render => sub { $sep x $self->{term}->ncol },
1787 activate => sub { },
1788 });
1789}
1790
1791=item $popup->add_button ($text, $cb)
1792
1793Adds a clickable button to the popup. C<$cb> is called whenever it is
1794selected.
1795
1796=cut
1797
1067sub add_button { 1798sub add_button {
1068 my ($self, $text, $cb) = @_; 1799 my ($self, $text, $cb) = @_;
1069 1800
1070 $self->add_item ({ type => "button", text => "[ $text ]", activate => $cb}); 1801 $self->add_item ({ type => "button", text => $text, activate => $cb});
1071} 1802}
1803
1804=item $popup->add_toggle ($text, $cb, $initial_value)
1805
1806Adds a toggle/checkbox item to the popup. Teh callback gets called
1807whenever it gets toggled, with a boolean indicating its value as its first
1808argument.
1809
1810=cut
1072 1811
1073sub add_toggle { 1812sub add_toggle {
1074 my ($self, $text, $cb, $value) = @_; 1813 my ($self, $text, $cb, $value) = @_;
1075 1814
1076 my $item; $item = { 1815 my $item; $item = {
1077 type => "button", 1816 type => "button",
1078 text => " $text", 1817 text => " $text",
1079 value => $value, 1818 value => $value,
1080 render => sub { ($item->{value} ? "* " : " ") . $text }, 1819 render => sub { ($_[0]{value} ? "* " : " ") . $text },
1081 activate => sub { $cb->($item->{value} = !$item->{value}); }, 1820 activate => sub { $cb->($_[1]{value} = !$_[1]{value}); },
1082 }; 1821 };
1083 1822
1084 $self->add_item ($item); 1823 $self->add_item ($item);
1085} 1824}
1825
1826=item $popup->show
1827
1828Displays the popup (which is initially hidden).
1829
1830=cut
1086 1831
1087sub show { 1832sub show {
1088 my ($self) = @_; 1833 my ($self) = @_;
1089 1834
1090 local $urxvt::popup::self = $self; 1835 local $urxvt::popup::self = $self;
1091 1836
1092 urxvt->new ("--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0, 1837 my $env = $self->{term}->env;
1838 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
1839 delete $env->{LC_ALL};
1840 $env->{LC_CTYPE} = $self->{term}->locale;
1841
1842 urxvt::term->new ($env, "popup",
1843 "--perl-lib" => "", "--perl-ext-common" => "",
1844 "-pty-fd" => -1, "-sl" => 0,
1845 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect",
1093 "--transient-for" => $self->{term}->parent, 1846 "--transient-for" => $self->{term}->parent,
1847 "-display" => $self->{term}->display_id,
1094 "-pe" => "urxvt-popup") 1848 "-pe" => "urxvt-popup")
1095 or die "unable to create popup window\n"; 1849 or die "unable to create popup window\n";
1096} 1850}
1097 1851
1098sub DESTROY { 1852sub DESTROY {
1099 my ($self) = @_; 1853 my ($self) = @_;
1100 1854
1855 delete $self->{term}{_destroy}{$self};
1101 $self->{term}->ungrab; 1856 $self->{term}->ungrab;
1102} 1857}
1858
1859=back
1860
1861=cut
1862
1863package urxvt::watcher;
1864
1865@urxvt::timer::ISA = __PACKAGE__;
1866@urxvt::iow::ISA = __PACKAGE__;
1867@urxvt::pw::ISA = __PACKAGE__;
1868@urxvt::iw::ISA = __PACKAGE__;
1103 1869
1104=head2 The C<urxvt::timer> Class 1870=head2 The C<urxvt::timer> Class
1105 1871
1106This class implements timer watchers/events. Time is represented as a 1872This class implements timer watchers/events. Time is represented as a
1107fractional number of seconds since the epoch. Example: 1873fractional number of seconds since the epoch. Example:
1146 1912
1147=item $timer = $timer->start ($tstamp) 1913=item $timer = $timer->start ($tstamp)
1148 1914
1149Set the event trigger time to C<$tstamp> and start the timer. 1915Set the event trigger time to C<$tstamp> and start the timer.
1150 1916
1917=item $timer = $timer->after ($delay)
1918
1919Like C<start>, but sets the expiry timer to c<urxvt::NOW + $delay>.
1920
1151=item $timer = $timer->stop 1921=item $timer = $timer->stop
1152 1922
1153Stop the timer. 1923Stop the timer.
1154 1924
1155=back 1925=back
1160 1930
1161 $term->{socket} = ... 1931 $term->{socket} = ...
1162 $term->{iow} = urxvt::iow 1932 $term->{iow} = urxvt::iow
1163 ->new 1933 ->new
1164 ->fd (fileno $term->{socket}) 1934 ->fd (fileno $term->{socket})
1165 ->events (1) # wait for read data 1935 ->events (urxvt::EVENT_READ)
1166 ->start 1936 ->start
1167 ->cb (sub { 1937 ->cb (sub {
1168 my ($iow, $revents) = @_; 1938 my ($iow, $revents) = @_;
1169 # $revents must be 1 here, no need to check 1939 # $revents must be 1 here, no need to check
1170 sysread $term->{socket}, my $buf, 8192 1940 sysread $term->{socket}, my $buf, 8192
1187 1957
1188Set the filedescriptor (not handle) to watch. 1958Set the filedescriptor (not handle) to watch.
1189 1959
1190=item $iow = $iow->events ($eventmask) 1960=item $iow = $iow->events ($eventmask)
1191 1961
1192Set the event mask to watch. Bit #0 (value C<1>) enables watching for read 1962Set the event mask to watch. The only allowed values are
1193data, Bit #1 (value C<2>) enables watching for write data. 1963C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed
1964together, or C<urxvt::EVENT_NONE>.
1194 1965
1195=item $iow = $iow->start 1966=item $iow = $iow->start
1196 1967
1197Start watching for requested events on the given handle. 1968Start watching for requested events on the given handle.
1198 1969
1199=item $iow = $iow->stop 1970=item $iow = $iow->stop
1200 1971
1201Stop watching for events on the given filehandle. 1972Stop watching for events on the given filehandle.
1973
1974=back
1975
1976=head2 The C<urxvt::iw> Class
1977
1978This class implements idle watchers, that get called automatically when
1979the process is idle. They should return as fast as possible, after doing
1980some useful work.
1981
1982=over 4
1983
1984=item $iw = new urxvt::iw
1985
1986Create a new idle watcher object in stopped state.
1987
1988=item $iw = $iw->cb (sub { my ($iw) = @_; ... })
1989
1990Set the callback to be called when the watcher triggers.
1991
1992=item $timer = $timer->start
1993
1994Start the watcher.
1995
1996=item $timer = $timer->stop
1997
1998Stop the watcher.
1999
2000=back
2001
2002=head2 The C<urxvt::pw> Class
2003
2004This class implements process watchers. They create an event whenever a
2005process exits, after which they stop automatically.
2006
2007 my $pid = fork;
2008 ...
2009 $term->{pw} = urxvt::pw
2010 ->new
2011 ->start ($pid)
2012 ->cb (sub {
2013 my ($pw, $exit_status) = @_;
2014 ...
2015 });
2016
2017=over 4
2018
2019=item $pw = new urxvt::pw
2020
2021Create a new process watcher in stopped state.
2022
2023=item $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
2024
2025Set the callback to be called when the timer triggers.
2026
2027=item $pw = $timer->start ($pid)
2028
2029Tells the wqtcher to start watching for process C<$pid>.
2030
2031=item $pw = $pw->stop
2032
2033Stop the watcher.
1202 2034
1203=back 2035=back
1204 2036
1205=head1 ENVIRONMENT 2037=head1 ENVIRONMENT
1206 2038
1209This variable controls the verbosity level of the perl extension. Higher 2041This variable controls the verbosity level of the perl extension. Higher
1210numbers indicate more verbose output. 2042numbers indicate more verbose output.
1211 2043
1212=over 4 2044=over 4
1213 2045
1214=item =0 - only fatal messages 2046=item == 0 - fatal messages
1215 2047
1216=item =3 - script loading and management 2048=item >= 3 - script loading and management
1217 2049
1218=item =10 - all events received 2050=item >=10 - all called hooks
2051
2052=item >=11 - hook reutrn values
1219 2053
1220=back 2054=back
1221 2055
1222=head1 AUTHOR 2056=head1 AUTHOR
1223 2057

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines