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.59 by root, Mon Jan 9 00:34:36 2006 UTC vs.
Revision 1.245 by root, Mon Dec 22 09:10:12 2014 UTC

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

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines