ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/rxvt-unicode/src/urxvt.pm
(Generate patch)

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

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines