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.28 by root, Wed Jan 4 00:09:12 2006 UTC vs.
Revision 1.102 by root, Wed Jan 18 10:31:37 2006 UTC

17 17
18 @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test 18 @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test
19 19
20=head1 DESCRIPTION 20=head1 DESCRIPTION
21 21
22Everytime a terminal object gets created, scripts specified via the 22Everytime a terminal object gets created, extension scripts specified via
23C<perl> resource are loaded and associated with it. 23the C<perl> resource are loaded and associated with it.
24 24
25Scripts are compiled in a 'use strict' and 'use utf8' environment, and 25Scripts are compiled in a 'use strict' and 'use utf8' environment, and
26thus must be encoded as UTF-8. 26thus must be encoded as UTF-8.
27 27
28Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where 28Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where
29scripts will be shared (but not enabled) for all terminals. 29scripts will be shared (but not enabled) for all terminals.
30 30
31=head2 Prepackaged Extensions 31=head1 PREPACKAGED EXTENSIONS
32 32
33This section describes the extensiosn delivered with this version. You can 33This section describes the extensions delivered with this release. You can
34find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>. 34find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>.
35 35
36You can activate them like this: 36You can activate them like this:
37 37
38 @@RXVT_NAME@@ -pe <extensionname> 38 @@RXVT_NAME@@ -pe <extensionname>
39 39
40=over 4 40=over 4
41 41
42=item selection 42=item selection (enabled by default)
43 43
44Intelligent selection. This extension tries to be more intelligent when 44(More) intelligent selection. This extension tries to be more intelligent
45the user extends selections (double-click). Right now, it tries to select 45when the user extends selections (double-click and further clicks). Right
46urls and complete shell-quoted arguments, which is very convenient, too, 46now, it tries to select words, urls and complete shell-quoted
47if your F<ls> supports C<--quoting-style=shell>. 47arguments, which is very convenient, too, if your F<ls> supports
48C<--quoting-style=shell>.
48 49
49It also offers the following bindable event: 50A double-click usually selects the word under the cursor, further clicks
51will enlarge the selection.
52
53The selection works by trying to match a number of regexes and displaying
54them in increasing order of length. You can add your own regexes by
55specifying resources of the form:
56
57 URxvt.selection.pattern-0: perl-regex
58 URxvt.selection.pattern-1: perl-regex
59 ...
60
61The index number (0, 1...) must not have any holes, and each regex must
62contain at least one pair of capturing parentheses, which will be used for
63the match. For example, the followign adds a regex that matches everything
64between two vertical bars:
65
66 URxvt.selection.pattern-0: \\|([^|]+)\\|
67
68You can look at the source of the selection extension to see more
69interesting uses, such as parsing a line from beginning to end.
70
71This extension also offers following bindable keyboard commands:
50 72
51=over 4 73=over 4
52 74
53=item rot13 75=item rot13
54 76
55Rot-13 the selection when activated. Used via keyboard trigger: 77Rot-13 the selection when activated. Used via keyboard trigger:
56 78
57 URxvt.keysym.C-M-r: perl:selection:rot13 79 URxvt.keysym.C-M-r: perl:selection:rot13
58 80
59=back 81=back
82
83=item option-popup (enabled by default)
84
85Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at
86runtime.
87
88=item selection-popup (enabled by default)
89
90Binds a popup menu to Ctrl-Button3 that lets you convert the selection
91text into various other formats/action (such as uri unescaping, perl
92evalution, web-browser starting etc.), depending on content.
93
94Other extensions can extend this popup menu by pushing a code reference onto
95C<@urxvt::ext::selection_popup::hook>, that is called whenever the popup is displayed.
96
97It's sole argument is the popup menu, which can be modified. The selection
98is in C<$_>, which can be used to decide wether to add something or not.
99It should either return nothing or a string and a code reference. The
100string will be used as button text and the code reference will be called
101when the button gets activated and should transform C<$_>.
102
103The following will add an entry C<a to b> that transforms all C<a>s in
104the selection to C<b>s, but only if the selection currently contains any
105C<a>s:
106
107 push urxvt::ext::selection_popup::hook, sub {
108 /a/ ? ("a to be" => sub { s/a/b/g }
109 : ()
110 };
111
112=item searchable-scrollback<hotkey> (enabled by default)
113
114Adds regex search functionality to the scrollback buffer, triggered
115by a hotkey (default: C<M-s>). While in search mode, normal terminal
116input/output is suspended and a regex is displayed at the bottom of the
117screen.
118
119Inputting characters appends them to the regex and continues incremental
120search. C<BackSpace> removes a character from the regex, C<Up> and C<Down>
121search upwards/downwards in the scrollback buffer, C<End> jumps to the
122bottom. C<Escape> leaves search mode and returns to the point where search
123was started, while C<Enter> or C<Return> stay at the current position and
124additionally stores the first match in the current line into the primary
125selection.
126
127=item selection-autotransform
128
129This selection allows you to do automatic transforms on a selection
130whenever a selection is made.
131
132It works by specifying perl snippets (most useful is a single C<s///>
133operator) that modify C<$_> as resources:
134
135 URxvt.selection-autotransform.0: transform
136 URxvt.selection-autotransform.1: transform
137 ...
138
139For example, the following will transform selections of the form
140C<filename:number>, often seen in compiler messages, into C<vi +$filename
141$word>:
142
143 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
144
145And this example matches the same,but replaces it with vi-commands you can
146paste directly into your (vi :) editor:
147
148 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/\\x1b:e \\Q$1\\E\\x0d:$2\\x0d/
149
150Of course, this can be modified to suit your needs and your editor :)
151
152To expand the example above to typical perl error messages ("XXX at
153FILENAME line YYY."), you need a slightly more elaborate solution:
154
155 URxvt.selection.pattern-0: ( at .*? line \\d+\\.)
156 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)\\.$/\x1b:e \\Q$1\E\\x0d:$2\\x0d/
157
158The first line tells the selection code to treat the unchanging part of
159every error message as a selection pattern, and the second line transforms
160the message into vi commands to load the file.
161
162=item mark-urls
163
164Uses per-line display filtering (C<on_line_update>) to underline urls and
165make them clickable. When middle-clicked, the program specified in the
166resource C<urlLauncher> (default C<x-www-browser>) will be started with
167the URL as first argument.
168
169=item block-graphics-to-ascii
170
171A not very useful example of filtering all text output to the terminal,
172by replacing all line-drawing characters (U+2500 .. U+259F) by a
173similar-looking ascii character.
60 174
61=item digital-clock 175=item digital-clock
62 176
63Displays a digital clock using the built-in overlay. 177Displays a digital clock using the built-in overlay.
64 178
66 180
67Displays a very simple digital clock in the upper right corner of the 181Displays a very simple digital clock in the upper right corner of the
68window. Illustrates overwriting the refresh callbacks to create your own 182window. Illustrates overwriting the refresh callbacks to create your own
69overlays or changes. 183overlays or changes.
70 184
185=item selection-pastebin
186
187This is a little rarely useful extension that Uploads the selection as
188textfile to a remote site (or does other things). (The implementation is
189not currently secure for use in a multiuser environment as it writes to
190F</tmp> directly.).
191
192It listens to the C<selection-pastebin:remote-pastebin> keyboard command,
193i.e.
194
195 URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin
196
197Pressing this combination runs a command with C<%> replaced by the name of
198the textfile. This command can be set via a resource:
199
200 URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
201
202And the default is likely not useful to anybody but the few people around
203here :)
204
205The name of the textfile is the hex encoded md5 sum of the selection, so
206the same content should lead to the same filename.
207
208After a successful upload the selection will be replaced by the text given
209in the C<selection-pastebin-url> resource (again, the % is the placeholder
210for the filename):
211
212 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
213
71=back 214=back
215
216=head1 API DOCUMENTATION
72 217
73=head2 General API Considerations 218=head2 General API Considerations
74 219
75All objects (such as terminals, time watchers etc.) are typical 220All objects (such as terminals, time watchers etc.) are typical
76reference-to-hash objects. The hash can be used to store anything you 221reference-to-hash objects. The hash can be used to store anything you
81When objects are destroyed on the C++ side, the perl object hashes are 226When objects are destroyed on the C++ side, the perl object hashes are
82emptied, so its best to store related objects such as time watchers and 227emptied, so its best to store related objects such as time watchers and
83the like inside the terminal object so they get destroyed as soon as the 228the like inside the terminal object so they get destroyed as soon as the
84terminal is destroyed. 229terminal is destroyed.
85 230
231Argument names also often indicate the type of a parameter. Here are some
232hints on what they mean:
233
234=over 4
235
236=item $text
237
238Rxvt-unicodes special way of encoding text, where one "unicode" character
239always represents one screen cell. See L<ROW_t> for a discussion of this format.
240
241=item $string
242
243A perl text string, with an emphasis on I<text>. It can store all unicode
244characters and is to be distinguished with text encoded in a specific
245encoding (often locale-specific) and binary data.
246
247=item $octets
248
249Either binary data or - more common - a text string encoded in a
250locale-specific way.
251
252=back
253
254=head2 Extension Objects
255
256Very perl extension is a perl class. A separate perl object is created
257for each terminal and each extension and passed as the first parameter to
258hooks. So extensions can use their C<$self> object without having to think
259about other extensions, with the exception of methods and members that
260begin with an underscore character C<_>: these are reserved for internal
261use.
262
263Although it isn't a C<urxvt::term> object, you can call all methods of the
264C<urxvt::term> class on this object.
265
266It has the following methods and data members:
267
268=over 4
269
270=item $urxvt_term = $self->{term}
271
272Returns the C<urxvt::term> object associated with this instance of the
273extension. This member I<must not> be changed in any way.
274
275=item $self->enable ($hook_name => $cb, [$hook_name => $cb..])
276
277Dynamically enable the given hooks (named without the C<on_> prefix) for
278this extension, replacing any previous hook. This is useful when you want
279to overwrite time-critical hooks only temporarily.
280
281=item $self->disable ($hook_name[, $hook_name..])
282
283Dynamically disable the given hooks.
284
285=back
286
86=head2 Hooks 287=head2 Hooks
87 288
88The following subroutines can be declared in loaded scripts, and will be 289The following subroutines can be declared in extension files, and will be
89called whenever the relevant event happens. 290called whenever the relevant event happens.
90 291
91The first argument passed to them is an object private to each terminal 292The first argument passed to them is an extension oject as described in
92and extension package. You can call all C<urxvt::term> methods on it, but 293the in the C<Extension Objects> section.
93its not a real C<urxvt::term> object. Instead, the real C<urxvt::term>
94object that is shared between all packages is stored in the C<term>
95member.
96 294
97All of them must return a boolean value. If it is true, then the event 295B<All> of these hooks must return a boolean value. If it is true, then the
98counts as being I<consumed>, and the invocation of other hooks is skipped, 296event counts as being I<consumed>, and the invocation of other hooks is
99and the relevant action might not be carried out by the C++ code. 297skipped, and the relevant action might not be carried out by the C++ code.
100 298
101When in doubt, return a false value (preferably C<()>). 299I<< When in doubt, return a false value (preferably C<()>). >>
102 300
103=over 4 301=over 4
104 302
105=item on_init $term 303=item on_init $term
106 304
107Called after a new terminal object has been initialized, but before 305Called after a new terminal object has been initialized, but before
108windows are created or the command gets run. 306windows are created or the command gets run. Most methods are unsafe to
307call or deliver senseless data, as terminal size and other characteristics
308have not yet been determined. You can safely query and change resources,
309though.
109 310
110=item on_reset $term 311=item on_reset $term
111 312
112Called after the screen is "reset" for any reason, such as resizing or 313Called after the screen is "reset" for any reason, such as resizing or
113control sequences. Here is where you can react on changes to size-related 314control sequences. Here is where you can react on changes to size-related
138=item on_sel_extend $term 339=item on_sel_extend $term
139 340
140Called whenever the user tries to extend the selection (e.g. with a double 341Called whenever the user tries to extend the selection (e.g. with a double
141click) and is either supposed to return false (normal operation), or 342click) and is either supposed to return false (normal operation), or
142should extend the selection itelf and return true to suppress the built-in 343should extend the selection itelf and return true to suppress the built-in
143processing. 344processing. This can happen multiple times, as long as the callback
345returns true, it will be called on every further click by the user and is
346supposed to enlarge the selection more and more, if possible.
144 347
145See the F<selection> example extension. 348See the F<selection> example extension.
146
147=item on_focus_in $term
148
149Called whenever the window gets the keyboard focus, before urxvt does
150focus in processing.
151
152=item on_focus_out $term
153
154Called wheneever the window loses keyboard focus, before urxvt does focus
155out processing.
156 349
157=item on_view_change $term, $offset 350=item on_view_change $term, $offset
158 351
159Called whenever the view offset changes, i..e the user or program 352Called whenever the view offset changes, i..e the user or program
160scrolls. Offset C<0> means display the normal terminal, positive values 353scrolls. Offset C<0> means display the normal terminal, positive values
168 361
169It is called before lines are scrolled out (so rows 0 .. min ($lines - 1, 362It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
170$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total 363$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
171number of lines that will be in the scrollback buffer. 364number of lines that will be in the scrollback buffer.
172 365
173=item on_tty_activity $term *NYI*
174
175Called whenever the program(s) running in the urxvt window send output.
176
177=item on_osc_seq $term, $string 366=item on_osc_seq $term, $string
178 367
179Called whenever the B<ESC ] 777 ; string ST> command sequence is 368Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
180processed. Cursor position and other state information is up-to-date when 369operating system command) is processed. Cursor position and other state
181this happens. For interoperability, the string should start with the 370information is up-to-date when this happens. For interoperability, the
182extension name and a colon, to distinguish it from commands for other 371string should start with the extension name and a colon, to distinguish
183extensions, and this might be enforced in the future. 372it from commands for other extensions, and this might be enforced in the
373future.
374
375Be careful not ever to trust (in a security sense) the data you receive,
376as its source can not easily be controleld (e-mail content, messages from
377other users on the same system etc.).
378
379=item on_add_lines $term, $string
380
381Called whenever text is about to be output, with the text as argument. You
382can filter/change and output the text yourself by returning a true value
383and calling C<< $term->scr_add_lines >> yourself. Please note that this
384might be very slow, however, as your hook is called for B<all> text being
385output.
386
387=item on_tt_write $term, $octets
388
389Called whenever some data is written to the tty/pty and can be used to
390suppress or filter tty input.
391
392=item on_line_update $term, $row
393
394Called whenever a line was updated or changed. Can be used to filter
395screen output (e.g. underline urls or other useless stuff). Only lines
396that are being shown will be filtered, and, due to performance reasons,
397not always immediately.
398
399The row number is always the topmost row of the line if the line spans
400multiple rows.
401
402Please note that, if you change the line, then the hook might get called
403later with the already-modified line (e.g. if unrelated parts change), so
404you cannot just toggle rendition bits, but only set them.
184 405
185=item on_refresh_begin $term 406=item on_refresh_begin $term
186 407
187Called just before the screen gets redrawn. Can be used for overlay 408Called just before the screen gets redrawn. Can be used for overlay
188or similar effects by modify terminal contents in refresh_begin, and 409or similar effects by modify terminal contents in refresh_begin, and
197 418
198Called whenever the user presses a key combination that has a 419Called whenever the user presses a key combination that has a
199C<perl:string> action bound to it (see description of the B<keysym> 420C<perl:string> action bound to it (see description of the B<keysym>
200resource in the @@RXVT_NAME@@(1) manpage). 421resource in the @@RXVT_NAME@@(1) manpage).
201 422
423=item on_x_event $term, $event
424
425Called on every X event received on the vt window (and possibly other
426windows). Should only be used as a last resort. Most event structure
427members are not passed.
428
429=item on_focus_in $term
430
431Called whenever the window gets the keyboard focus, before rxvt-unicode
432does focus in processing.
433
434=item on_focus_out $term
435
436Called wheneever the window loses keyboard focus, before rxvt-unicode does
437focus out processing.
438
439=item on_configure_notify $term, $event
440
441=item on_key_press $term, $event, $keysym, $octets
442
443=item on_key_release $term, $event, $keysym
444
445=item on_button_press $term, $event
446
447=item on_button_release $term, $event
448
449=item on_motion_notify $term, $event
450
451=item on_map_notify $term, $event
452
453=item on_unmap_notify $term, $event
454
455Called whenever the corresponding X event is received for the terminal If
456the hook returns true, then the even will be ignored by rxvt-unicode.
457
458The event is a hash with most values as named by Xlib (see the XEvent
459manpage), with the additional members C<row> and C<col>, which are the row
460and column under the mouse cursor.
461
462C<on_key_press> additionally receives the string rxvt-unicode would
463output, if any, in locale-specific encoding.
464
465subwindow.
466
202=back 467=back
203 468
469=cut
470
471package urxvt;
472
473use utf8;
474use strict;
475use Carp ();
476use Scalar::Util ();
477use List::Util ();
478
479our $VERSION = 1;
480our $TERM;
481our @HOOKNAME;
482our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
483our %OPTION;
484
485our $LIBDIR;
486our $RESNAME;
487our $RESCLASS;
488our $RXVTNAME;
489
204=head2 Variables in the C<urxvt> Package 490=head2 Variables in the C<urxvt> Package
205 491
206=over 4 492=over 4
207 493
494=item $urxvt::LIBDIR
495
496The rxvt-unicode library directory, where, among other things, the perl
497modules and scripts are stored.
498
499=item $urxvt::RESCLASS, $urxvt::RESCLASS
500
501The resource class and name rxvt-unicode uses to look up X resources.
502
503=item $urxvt::RXVTNAME
504
505The basename of the installed binaries, usually C<urxvt>.
506
208=item $urxvt::TERM 507=item $urxvt::TERM
209 508
210The current terminal. Whenever a callback/Hook is bein executed, this 509The current terminal. This variable stores the current C<urxvt::term>
211variable stores the current C<urxvt::term> object. 510object, whenever a callback/hook is executing.
212 511
213=back 512=back
214 513
215=head2 Functions in the C<urxvt> Package 514=head2 Functions in the C<urxvt> Package
216 515
229that calls this function. 528that calls this function.
230 529
231Using this function has the advantage that its output ends up in the 530Using this function has the advantage that its output ends up in the
232correct place, e.g. on stderr of the connecting urxvtc client. 531correct place, e.g. on stderr of the connecting urxvtc client.
233 532
533Messages have a size limit of 1023 bytes currently.
534
234=item $time = urxvt::NOW 535=item $time = urxvt::NOW
235 536
236Returns the "current time" (as per the event loop). 537Returns the "current time" (as per the event loop).
538
539=item urxvt::CurrentTime
540
541=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
542Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
543Button4Mask, Button5Mask, AnyModifier
544
545=item urxvt::NoEventMask, KeyPressMask, KeyReleaseMask,
546ButtonPressMask, ButtonReleaseMask, EnterWindowMask, LeaveWindowMask,
547PointerMotionMask, PointerMotionHintMask, Button1MotionMask, Button2MotionMask,
548Button3MotionMask, Button4MotionMask, Button5MotionMask, ButtonMotionMask,
549KeymapStateMask, ExposureMask, VisibilityChangeMask, StructureNotifyMask,
550ResizeRedirectMask, SubstructureNotifyMask, SubstructureRedirectMask,
551FocusChangeMask, PropertyChangeMask, ColormapChangeMask, OwnerGrabButtonMask
552
553=item urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify,
554EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose,
555GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify, DestroyNotify,
556UnmapNotify, MapNotify, MapRequest, ReparentNotify, ConfigureNotify,
557ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify,
558CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest,
559SelectionNotify, ColormapNotify, ClientMessage, MappingNotify
560
561Various constants for use in X calls and event processing.
237 562
238=back 563=back
239 564
240=head2 RENDITION 565=head2 RENDITION
241 566
268 593
269=item $background = urxvt::GET_BASEBG $rend 594=item $background = urxvt::GET_BASEBG $rend
270 595
271Return the foreground/background colour index, respectively. 596Return the foreground/background colour index, respectively.
272 597
273=item $rend = urxvt::SET_FGCOLOR ($rend, $new_colour) 598=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
274 599
275=item $rend = urxvt::SET_BGCOLOR ($rend, $new_colour) 600=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
276 601
277Replace the foreground/background colour in the rendition mask with the 602Replace the foreground/background colour in the rendition mask with the
278specified one. 603specified one.
279 604
280=item $value = urxvt::GET_CUSTOM ($rend) 605=item $value = urxvt::GET_CUSTOM $rend
281 606
282Return the "custom" value: Every rendition has 5 bits for use by 607Return the "custom" value: Every rendition has 5 bits for use by
283extensions. They can be set and changed as you like and are initially 608extensions. They can be set and changed as you like and are initially
284zero. 609zero.
285 610
286=item $rend = urxvt::SET_CUSTOM ($rend, $new_value) 611=item $rend = urxvt::SET_CUSTOM $rend, $new_value
287 612
288Change the custom value. 613Change the custom value.
289 614
290=back 615=back
291 616
292=cut 617=cut
293 618
294package urxvt;
295
296use strict;
297use Scalar::Util ();
298
299our $TERM;
300our @HOOKNAME;
301our $LIBDIR;
302
303BEGIN { 619BEGIN {
304 urxvt->bootstrap;
305
306 # overwrite perl's warn 620 # overwrite perl's warn
307 *CORE::GLOBAL::warn = sub { 621 *CORE::GLOBAL::warn = sub {
308 my $msg = join "", @_; 622 my $msg = join "", @_;
309 $msg .= "\n" 623 $msg .= "\n"
310 unless $msg =~ /\n$/; 624 unless $msg =~ /\n$/;
311 urxvt::warn ($msg); 625 urxvt::warn ($msg);
312 }; 626 };
313}
314 627
315my @hook_count; 628 # %ENV is the original startup environment
629 delete $ENV{IFS};
630 delete $ENV{CDPATH};
631 delete $ENV{BASH_ENV};
632 $ENV{PATH} = "/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/opt/bin:/opt/sbin";
633}
634
316my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 635my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
317 636
318sub verbose { 637sub verbose {
319 my ($level, $msg) = @_; 638 my ($level, $msg) = @_;
320 warn "$msg\n" if $level <= $verbosity; 639 warn "$msg\n" if $level <= $verbosity;
321} 640}
322 641
323# find on_xxx subs in the package and register them 642my %extension_pkg;
324# as hooks
325sub register_package($) {
326 my ($pkg) = @_;
327
328 for my $htype (0.. $#HOOKNAME) {
329 my $name = $HOOKNAME[$htype];
330
331 my $ref = $pkg->can ("on_" . lc $name)
332 or next;
333
334 $TERM->{_hook}[$htype]{$pkg} = $ref;
335 $hook_count[$htype]++
336 or set_should_invoke $htype, 1;
337 }
338}
339
340my $script_pkg = "script0000";
341my %script_pkg;
342 643
343# load a single script into its own package, once only 644# load a single script into its own package, once only
344sub script_package($) { 645sub extension_package($) {
345 my ($path) = @_; 646 my ($path) = @_;
346 647
648 no strict 'refs';
649
347 $script_pkg{$path} ||= do { 650 $extension_pkg{$path} ||= do {
348 my $pkg = "urxvt::" . ($script_pkg++); 651 $path =~ /([^\/\\]+)$/;
652 my $pkg = $1;
653 $pkg =~ s/[^[:word:]]/_/g;
654 $pkg = "urxvt::ext::$pkg";
349 655
350 verbose 3, "loading script '$path' into package '$pkg'"; 656 verbose 3, "loading extension '$path' into package '$pkg'";
351 657
352 open my $fh, "<:raw", $path 658 open my $fh, "<:raw", $path
353 or die "$path: $!"; 659 or die "$path: $!";
354 660
661 @{"$pkg\::ISA"} = urxvt::term::extension::;
662
663 my $source =
355 my $source = "package $pkg; use strict; use utf8;\n" 664 "package $pkg; use strict; use utf8;\n"
356 . "#line 1 \"$path\"\n{\n" 665 . "#line 1 \"$path\"\n{\n"
357 . (do { local $/; <$fh> }) 666 . (do { local $/; <$fh> })
358 . "\n};\n1"; 667 . "\n};\n1";
359 668
669 eval $source
360 eval $source or die "$path: $@"; 670 or die "$path: $@";
361 671
362 $pkg 672 $pkg
363 } 673 }
364} 674}
675
676our $retval; # return value for urxvt
365 677
366# called by the rxvt core 678# called by the rxvt core
367sub invoke { 679sub invoke {
368 local $TERM = shift; 680 local $TERM = shift;
369 my $htype = shift; 681 my $htype = shift;
370 682
371 if ($htype == 0) { # INIT 683 if ($htype == 0) { # INIT
372 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 684 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
685
686 my %ext_arg;
373 687
374 for my $ext (split /:/, $TERM->resource ("perl_ext")) { 688 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
689 if ($_ eq "default") {
690 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback);
691 } elsif (/^-(.*)$/) {
692 delete $ext_arg{$1};
693 } elsif (/^([^<]+)<(.*)>$/) {
694 push @{ $ext_arg{$1} }, $2;
695 } else {
696 $ext_arg{$_} ||= [];
697 }
698 }
699
700 while (my ($ext, $argv) = each %ext_arg) {
375 my @files = grep -f $_, map "$_/$ext", @dirs; 701 my @files = grep -f $_, map "$_/$ext", @dirs;
376 702
377 if (@files) { 703 if (@files) {
378 register_package script_package $files[0]; 704 $TERM->register_package (extension_package $files[0], $argv);
379 } else { 705 } else {
380 warn "perl extension '$ext' not found in perl library search path\n"; 706 warn "perl extension '$ext' not found in perl library search path\n";
381 } 707 }
382 } 708 }
383 709
384 } elsif ($htype == 1) { # DESTROY 710 eval "#line 1 \"--perl-eval resource/argument\"\n" . $TERM->resource ("perl_eval");
711 warn $@ if $@;
712 }
713
714 $retval = undef;
715
385 if (my $hook = $TERM->{_hook}) { 716 if (my $cb = $TERM->{_hook}[$htype]) {
386 for my $htype (0..$#$hook) { 717 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
387 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} } 718 if $verbosity >= 10;
388 or set_should_invoke $htype, 0; 719
720 keys %$cb;
721
722 while (my ($pkg, $cb) = each %$cb) {
723 $retval = eval { $cb->($TERM->{_pkg}{$pkg}, @_) }
724 and last;
725
726 if ($@) {
727 $TERM->ungrab; # better to lose the grab than the session
728 warn $@;
389 } 729 }
390 } 730 }
731
732 verbose 11, "$HOOKNAME[$htype] returning <$retval>"
733 if $verbosity >= 11;
391 } 734 }
392 735
393 my $cb = $TERM->{_hook}[$htype] 736 if ($htype == 1) { # DESTROY
394 or return; 737 # clear package objects
738 %$_ = () for values %{ $TERM->{_pkg} };
395 739
396 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")" 740 # clear package
397 if $verbosity >= 10; 741 %$TERM = ();
398
399 keys %$cb;
400
401 while (my ($pkg, $cb) = each %$cb) {
402 return 1
403 if $cb->(
404 $TERM->{$pkg} ||= do {
405 my $proxy = bless { }, urxvt::term::proxy::;
406 Scalar::Util::weaken ($proxy->{term} = $TERM);
407 $proxy
408 },
409 @_,
410 );
411 } 742 }
412 743
744 $retval
745}
746
747sub exec_async(@) {
748 my $pid = fork;
749
750 return
751 if !defined $pid or $pid;
752
753 %ENV = %{ $TERM->env };
754
755 exec @_;
756 _exit 255;
757}
758
759# urxvt::term::extension
760
761package urxvt::term::extension;
762
763sub enable {
764 my ($self, %hook) = @_;
765 my $pkg = $self->{_pkg};
766
767 while (my ($name, $cb) = each %hook) {
768 my $htype = $HOOKTYPE{uc $name};
769 defined $htype
770 or Carp::croak "unsupported hook type '$name'";
771
772 $self->set_should_invoke ($htype, +1)
773 unless exists $self->{term}{_hook}[$htype]{$pkg};
774
775 $self->{term}{_hook}[$htype]{$pkg} = $cb;
413 0 776 }
414} 777}
415 778
416sub urxvt::term::proxy::AUTOLOAD { 779sub disable {
417 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/ 780 my ($self, @hook) = @_;
781 my $pkg = $self->{_pkg};
782
783 for my $name (@hook) {
784 my $htype = $HOOKTYPE{uc $name};
785 defined $htype
786 or Carp::croak "unsupported hook type '$name'";
787
788 $self->set_should_invoke ($htype, -1)
789 if delete $self->{term}{_hook}[$htype]{$pkg};
790 }
791}
792
793our $AUTOLOAD;
794
795sub AUTOLOAD {
796 $AUTOLOAD =~ /:([^:]+)$/
418 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable"; 797 or die "FATAL: \$AUTOLOAD '$AUTOLOAD' unparsable";
419 798
420 eval qq{ 799 eval qq{
421 sub $urxvt::term::proxy::AUTOLOAD { 800 sub $AUTOLOAD {
422 my \$proxy = shift; 801 my \$proxy = shift;
423 \$proxy->{term}->$1 (\@_) 802 \$proxy->{term}->$1 (\@_)
424 } 803 }
425 1 804 1
426 } or die "FATAL: unable to compile method forwarder: $@"; 805 } or die "FATAL: unable to compile method forwarder: $@";
427 806
428 goto &$urxvt::term::proxy::AUTOLOAD; 807 goto &$AUTOLOAD;
429} 808}
809
810sub DESTROY {
811 # nop
812}
813
814# urxvt::destroy_hook
815
816sub urxvt::destroy_hook::DESTROY {
817 ${$_[0]}->();
818}
819
820sub urxvt::destroy_hook(&) {
821 bless \shift, urxvt::destroy_hook::
822}
823
824package urxvt::anyevent;
825
826=head2 The C<urxvt::anyevent> Class
827
828The sole purpose of this class is to deliver an interface to the
829C<AnyEvent> module - any module using it will work inside urxvt without
830further programming. The only exception is that you cannot wait on
831condition variables, but non-blocking condvar use is ok. What this means
832is that you cannot use blocking APIs, but the non-blocking variant should
833work.
834
835=cut
836
837our $VERSION = 1;
838
839$INC{"urxvt/anyevent.pm"} = 1; # mark us as there
840push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
841
842sub timer {
843 my ($class, %arg) = @_;
844
845 my $cb = $arg{cb};
846
847 urxvt::timer
848 ->new
849 ->start (urxvt::NOW + $arg{after})
850 ->cb (sub {
851 $_[0]->stop; # need to cancel manually
852 $cb->();
853 })
854}
855
856sub io {
857 my ($class, %arg) = @_;
858
859 my $cb = $arg{cb};
860
861 bless [$arg{fh}, urxvt::iow
862 ->new
863 ->fd (fileno $arg{fh})
864 ->events (($arg{poll} =~ /r/ ? 1 : 0)
865 | ($arg{poll} =~ /w/ ? 2 : 0))
866 ->start
867 ->cb (sub {
868 $cb->(($_[1] & 1 ? 'r' : '')
869 . ($_[1] & 2 ? 'w' : ''));
870 })],
871 urxvt::anyevent::
872}
873
874sub DESTROY {
875 $_[0][1]->stop;
876}
877
878sub condvar {
879 bless \my $flag, urxvt::anyevent::condvar::
880}
881
882sub urxvt::anyevent::condvar::broadcast {
883 ${$_[0]}++;
884}
885
886sub urxvt::anyevent::condvar::wait {
887 unless (${$_[0]}) {
888 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API";
889 }
890}
891
892package urxvt::term;
430 893
431=head2 The C<urxvt::term> Class 894=head2 The C<urxvt::term> Class
432 895
433=over 4 896=over 4
897
898=cut
899
900# find on_xxx subs in the package and register them
901# as hooks
902sub register_package {
903 my ($self, $pkg, $argv) = @_;
904
905 my $proxy = bless {
906 _pkg => $pkg,
907 argv => $argv,
908 }, $pkg;
909 Scalar::Util::weaken ($proxy->{term} = $self);
910
911 $self->{_pkg}{$pkg} = $proxy;
912
913 for my $name (@HOOKNAME) {
914 if (my $ref = $pkg->can ("on_" . lc $name)) {
915 $proxy->enable ($name => $ref);
916 }
917 }
918}
919
920=item $term = new urxvt::term $envhashref, $rxvtname, [arg...]
921
922Creates a new terminal, very similar as if you had started it with system
923C<$rxvtname, arg...>. C<$envhashref> must be a reference to a C<%ENV>-like
924hash which defines the environment of the new terminal.
925
926Croaks (and probably outputs an error message) if the new instance
927couldn't be created. Returns C<undef> if the new instance didn't
928initialise perl, and the terminal object otherwise. The C<init> and
929C<start> hooks will be called during this call.
930
931=cut
932
933sub new {
934 my ($class, $env, @args) = @_;
935
936 _new ([ map "$_=$env->{$_}", keys %$env ], @args);
937}
938
939=item $term->destroy
940
941Destroy the terminal object (close the window, free resources
942etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event
943watchers (timers, io watchers) are still active.
944
945=item $isset = $term->option ($optval[, $set])
946
947Returns true if the option specified by C<$optval> is enabled, and
948optionally change it. All option values are stored by name in the hash
949C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
950
951Here is a a likely non-exhaustive list of option names, please see the
952source file F</src/optinc.h> to see the actual list:
953
954 borderLess console cursorBlink cursorUnderline hold iconic insecure
955 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
956 pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating
957 scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer
958 secondaryScreen secondaryScroll skipBuiltinGlyphs transparent
959 tripleclickwords utmpInhibit visualBell
434 960
435=item $value = $term->resource ($name[, $newval]) 961=item $value = $term->resource ($name[, $newval])
436 962
437Returns the current resource value associated with a given name and 963Returns the current resource value associated with a given name and
438optionally sets a new value. Setting values is most useful in the C<init> 964optionally sets a new value. Setting values is most useful in the C<init>
448 974
449Please note that resource strings will currently only be freed when the 975Please note that resource strings will currently only be freed when the
450terminal is destroyed, so changing options frequently will eat memory. 976terminal is destroyed, so changing options frequently will eat memory.
451 977
452Here is a a likely non-exhaustive list of resource names, not all of which 978Here is a a likely non-exhaustive list of resource names, not all of which
453are supported in every build, please see the source to see the actual 979are supported in every build, please see the source file F</src/rsinc.h>
454list: 980to see the actual list:
455 981
456 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 982 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
457 borderLess color cursorBlink cursorUnderline cutchars delete_key 983 borderLess color cursorBlink cursorUnderline cutchars delete_key
458 display_name embed ext_bwidth fade font geometry hold iconName 984 display_name embed ext_bwidth fade font geometry hold iconName
459 imFont imLocale inputMethod insecure int_bwidth intensityStyles 985 imFont imLocale inputMethod insecure int_bwidth intensityStyles
460 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier 986 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
461 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext 987 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2
462 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 988 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
463 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 989 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
464 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 990 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
465 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 991 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
466 shade term_name title transparent transparent_all tripleclickwords 992 shade term_name title transparent transparent_all tripleclickwords
467 utmpInhibit visualBell 993 utmpInhibit visualBell
468 994
469=cut 995=cut
470 996
471sub urxvt::term::resource($$;$) { 997sub resource($$;$) {
472 my ($self, $name) = (shift, shift); 998 my ($self, $name) = (shift, shift);
473 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 999 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
474 goto &urxvt::term::_resource; 1000 &urxvt::term::_resource
475} 1001}
1002
1003=item $value = $term->x_resource ($pattern)
1004
1005Returns the X-Resource for the given pattern, excluding the program or
1006class name, i.e. C<< $term->x_resource ("boldFont") >> should return the
1007same value as used by this instance of rxvt-unicode. Returns C<undef> if no
1008resource with that pattern exists.
1009
1010This method should only be called during the C<on_start> hook, as there is
1011only one resource database per display, and later invocations might return
1012the wrong resources.
1013
1014=item $success = $term->parse_keysym ($keysym_spec, $command_string)
1015
1016Adds a keymap translation exactly as specified via a resource. See the
1017C<keysym> resource in the @@RXVT_NAME@@(1) manpage.
1018
1019=item $rend = $term->rstyle ([$new_rstyle])
1020
1021Return and optionally change the current rendition. Text that is output by
1022the terminal application will use this style.
1023
1024=item ($row, $col) = $term->screen_cur ([$row, $col])
1025
1026Return the current coordinates of the text cursor position and optionally
1027set it (which is usually bad as applications don't expect that).
476 1028
477=item ($row, $col) = $term->selection_mark ([$row, $col]) 1029=item ($row, $col) = $term->selection_mark ([$row, $col])
478 1030
479=item ($row, $col) = $term->selection_beg ([$row, $col]) 1031=item ($row, $col) = $term->selection_beg ([$row, $col])
480 1032
481=item ($row, $col) = $term->selection_end ([$row, $col]) 1033=item ($row, $col) = $term->selection_end ([$row, $col])
482 1034
483Return the current values of the selection mark, begin or end positions, 1035Return the current values of the selection mark, begin or end positions,
484and optionally set them to new values. 1036and optionally set them to new values.
485 1037
1038=item $term->selection_make ($eventtime[, $rectangular])
1039
1040Tries to make a selection as set by C<selection_beg> and
1041C<selection_end>. If C<$rectangular> is true (default: false), a
1042rectangular selection will be made. This is the prefered function to make
1043a selection.
1044
486=item $success = $term->selection_grab ($eventtime) 1045=item $success = $term->selection_grab ($eventtime)
487 1046
488Try to request the primary selection from the server (for example, as set 1047Try to request the primary selection text from the server (for example, as
489by the next method). 1048set by the next method). No visual feedback will be given. This function
1049is mostly useful from within C<on_sel_grab> hooks.
490 1050
491=item $oldtext = $term->selection ([$newtext]) 1051=item $oldtext = $term->selection ([$newtext])
492 1052
493Return the current selection text and optionally replace it by C<$newtext>. 1053Return the current selection text and optionally replace it by C<$newtext>.
494 1054
495#=item $term->overlay ($x, $y, $text) 1055=item $term->overlay_simple ($x, $y, $text)
496# 1056
497#Create a simple multi-line overlay box. See the next method for details. 1057Create a simple multi-line overlay box. See the next method for details.
498# 1058
499#=cut 1059=cut
500 1060
501sub urxvt::term::scr_overlay { 1061sub overlay_simple {
502die;
503 my ($self, $x, $y, $text) = @_; 1062 my ($self, $x, $y, $text) = @_;
504 1063
505 my @lines = split /\n/, $text; 1064 my @lines = split /\n/, $text;
506 1065
507 my $w = 0; 1066 my $w = List::Util::max map $self->strwidth ($_), @lines;
508 for (map $self->strwidth ($_), @lines) {
509 $w = $_ if $w < $_;
510 }
511 1067
512 $self->scr_overlay_new ($x, $y, $w, scalar @lines); 1068 my $overlay = $self->overlay ($x, $y, $w, scalar @lines);
513 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 1069 $overlay->set (0, $_, $lines[$_]) for 0.. $#lines;
1070
1071 $overlay
514} 1072}
515 1073
516=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 1074=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
517 1075
518Create a new (empty) overlay at the given position with the given 1076Create a new (empty) overlay at the given position with the given
546 1104
547If hidden, display the overlay again. 1105If hidden, display the overlay again.
548 1106
549=back 1107=back
550 1108
1109=item $popup = $term->popup ($event)
1110
1111Creates a new C<urxvt::popup> object that implements a popup menu. The
1112C<$event> I<must> be the event causing the menu to pop up (a button event,
1113currently).
1114
1115=cut
1116
1117sub popup {
1118 my ($self, $event) = @_;
1119
1120 $self->grab ($event->{time}, 1)
1121 or return;
1122
1123 my $popup = bless {
1124 term => $self,
1125 event => $event,
1126 }, urxvt::popup::;
1127
1128 Scalar::Util::weaken $popup->{term};
1129
1130 $self->{_destroy}{$popup} = urxvt::destroy_hook { $popup->{popup}->destroy };
1131 Scalar::Util::weaken $self->{_destroy}{$popup};
1132
1133 $popup
1134}
1135
551=item $cellwidth = $term->strwidth $string 1136=item $cellwidth = $term->strwidth ($string)
552 1137
553Returns the number of screen-cells this string would need. Correctly 1138Returns the number of screen-cells this string would need. Correctly
554accounts for wide and combining characters. 1139accounts for wide and combining characters.
555 1140
556=item $octets = $term->locale_encode $string 1141=item $octets = $term->locale_encode ($string)
557 1142
558Convert the given text string into the corresponding locale encoding. 1143Convert the given text string into the corresponding locale encoding.
559 1144
560=item $string = $term->locale_decode $octets 1145=item $string = $term->locale_decode ($octets)
561 1146
562Convert the given locale-encoded octets into a perl string. 1147Convert the given locale-encoded octets into a perl string.
1148
1149=item $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
1150
1151XORs the rendition values in the given span with the provided value
1152(default: C<RS_RVid>), which I<MUST NOT> contain font styles. Useful in
1153refresh hooks to provide effects similar to the selection.
1154
1155=item $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, $rstyle2]])
1156
1157Similar to C<scr_xor_span>, but xors a rectangle instead. Trailing
1158whitespace will additionally be xored with the C<$rstyle2>, which defaults
1159to C<RS_RVid | RS_Uline>, which removes reverse video again and underlines
1160it instead. Both styles I<MUST NOT> contain font styles.
1161
1162=item $term->scr_bell
1163
1164Ring the bell!
1165
1166=item $term->scr_add_lines ($string)
1167
1168Write the given text string to the screen, as if output by the application
1169running inside the terminal. It may not contain command sequences (escape
1170codes), but is free to use line feeds, carriage returns and tabs. The
1171string is a normal text string, not in locale-dependent encoding.
1172
1173Normally its not a good idea to use this function, as programs might be
1174confused by changes in cursor position or scrolling. Its useful inside a
1175C<on_add_lines> hook, though.
1176
1177=item $term->cmd_parse ($octets)
1178
1179Similar to C<scr_add_lines>, but the argument must be in the
1180locale-specific encoding of the terminal and can contain command sequences
1181(escape codes) that will be interpreted.
563 1182
564=item $term->tt_write ($octets) 1183=item $term->tt_write ($octets)
565 1184
566Write the octets given in C<$data> to the tty (i.e. as program input). To 1185Write the octets given in C<$data> to the tty (i.e. as program input). To
567pass characters instead of octets, you should convert your strings first 1186pass characters instead of octets, you should convert your strings first
568to the locale-specific encoding using C<< $term->locale_encode >>. 1187to the locale-specific encoding using C<< $term->locale_encode >>.
569 1188
1189=item $old_events = $term->pty_ev_events ([$new_events])
1190
1191Replaces the event mask of the pty watcher by the given event mask. Can
1192be used to suppress input and output handling to the pty/tty. See the
1193description of C<< urxvt::timer->events >>. Make sure to always restore
1194the previous value.
1195
1196=item $windowid = $term->parent
1197
1198Return the window id of the toplevel window.
1199
1200=item $windowid = $term->vt
1201
1202Return the window id of the terminal window.
1203
1204=item $term->vt_emask_add ($x_event_mask)
1205
1206Adds the specified events to the vt event mask. Useful e.g. when you want
1207to receive pointer events all the times:
1208
1209 $term->vt_emask_add (urxvt::PointerMotionMask);
1210
1211=item $window_width = $term->width
1212
1213=item $window_height = $term->height
1214
1215=item $font_width = $term->fwidth
1216
1217=item $font_height = $term->fheight
1218
1219=item $font_ascent = $term->fbase
1220
570=item $nrow = $term->nrow 1221=item $terminal_rows = $term->nrow
571 1222
572=item $ncol = $term->ncol 1223=item $terminal_columns = $term->ncol
573 1224
574Return the number of rows/columns of the terminal window (i.e. as 1225=item $has_focus = $term->focus
575specified by C<-geometry>, excluding any scrollback).
576 1226
1227=item $is_mapped = $term->mapped
1228
1229=item $max_scrollback = $term->saveLines
1230
1231=item $nrow_plus_saveLines = $term->total_rows
1232
1233=item $topmost_scrollback_row = $term->top_row
1234
1235Return various integers describing terminal characteristics.
1236
1237=item $x_display = $term->display_id
1238
1239Return the DISPLAY used by rxvt-unicode.
1240
1241=item $lc_ctype = $term->locale
1242
1243Returns the LC_CTYPE category string used by this rxvt-unicode.
1244
577=item $nsaved = $term->nsaved 1245=item $env = $term->env
578 1246
579Returns the number of lines in the scrollback buffer. 1247Returns a copy of the environment in effect for the terminal as a hashref
1248similar to C<\%ENV>.
1249
1250=cut
1251
1252sub env {
1253 if (my $env = $_[0]->_env) {
1254 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env }
1255 } else {
1256 +{ %ENV }
1257 }
1258}
1259
1260=item $modifiermask = $term->ModLevel3Mask
1261
1262=item $modifiermask = $term->ModMetaMask
1263
1264=item $modifiermask = $term->ModNumLockMask
1265
1266Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
1267AltGr), the meta key (often Alt) and the num lock key, if applicable.
580 1268
581=item $view_start = $term->view_start ([$newvalue]) 1269=item $view_start = $term->view_start ([$newvalue])
582 1270
583Returns the negative row number of the topmost line. Minimum value is 1271Returns the row number of the topmost displayed line. Maximum value is
584C<0>, which displays the normal terminal contents. Larger values scroll 1272C<0>, which displays the normal terminal contents. Lower values scroll
585this many lines into the scrollback buffer. 1273this many lines into the scrollback buffer.
586 1274
587=item $term->want_refresh 1275=item $term->want_refresh
588 1276
589Requests a screen refresh. At the next opportunity, rxvt-unicode will 1277Requests a screen refresh. At the next opportunity, rxvt-unicode will
647about the logical line that row C<$row_number> is part of. It supports the 1335about the logical line that row C<$row_number> is part of. It supports the
648following methods: 1336following methods:
649 1337
650=over 4 1338=over 4
651 1339
652=item $text = $line->t 1340=item $text = $line->t ([$new_text])
653 1341
654Returns the full text of the line, similar to C<ROW_t> 1342Returns or replaces the full text of the line, similar to C<ROW_t>
655 1343
656=item $rend = $line->r 1344=item $rend = $line->r ([$new_rend])
657 1345
658Returns the full rendition array of the line, similar to C<ROW_r> 1346Returns or replaces the full rendition array of the line, similar to C<ROW_r>
659 1347
660=item $length = $line->l 1348=item $length = $line->l
661 1349
662Returns the length of the line in cells, similar to C<ROW_l>. 1350Returns the length of the line in cells, similar to C<ROW_l>.
663 1351
668Return the row number of the first/last row of the line, respectively. 1356Return the row number of the first/last row of the line, respectively.
669 1357
670=item $offset = $line->offset_of ($row, $col) 1358=item $offset = $line->offset_of ($row, $col)
671 1359
672Returns the character offset of the given row|col pair within the logical 1360Returns the character offset of the given row|col pair within the logical
673line. 1361line. Works for rows outside the line, too, and returns corresponding
1362offsets outside the string.
674 1363
675=item ($row, $col) = $line->coord_of ($offset) 1364=item ($row, $col) = $line->coord_of ($offset)
676 1365
677Translates a string offset into terminal coordinates again. 1366Translates a string offset into terminal coordinates again.
678 1367
679=back 1368=back
680 1369
681=cut 1370=cut
682 1371
683sub urxvt::term::line { 1372sub line {
684 my ($self, $row) = @_; 1373 my ($self, $row) = @_;
685 1374
686 my $maxrow = $self->nrow - 1; 1375 my $maxrow = $self->nrow - 1;
687 1376
688 my ($beg, $end) = ($row, $row); 1377 my ($beg, $end) = ($row, $row);
692 1381
693 bless { 1382 bless {
694 term => $self, 1383 term => $self,
695 beg => $beg, 1384 beg => $beg,
696 end => $end, 1385 end => $end,
1386 ncol => $self->ncol,
697 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end), 1387 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end),
698 }, urxvt::line:: 1388 }, urxvt::line::
699} 1389}
700 1390
701sub urxvt::line::t { 1391sub urxvt::line::t {
702 my ($self) = @_; 1392 my ($self) = @_;
703 1393
1394 if (@_ > 1)
1395 {
1396 $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
1397 for $self->{beg} .. $self->{end};
1398 }
1399
1400 defined wantarray &&
704 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}), 1401 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
705 0, $self->{len} 1402 0, $self->{len}
706} 1403}
707 1404
708sub urxvt::line::r { 1405sub urxvt::line::r {
709 my ($self) = @_; 1406 my ($self) = @_;
710 1407
1408 if (@_ > 1)
1409 {
1410 $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
1411 for $self->{beg} .. $self->{end};
1412 }
1413
1414 if (defined wantarray) {
711 my $rend = [ 1415 my $rend = [
712 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end} 1416 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
713 ]; 1417 ];
714 $#$rend = $self->{len} - 1; 1418 $#$rend = $self->{len} - 1;
715 $rend 1419 return $rend;
1420 }
1421
1422 ()
716} 1423}
717 1424
718sub urxvt::line::beg { $_[0]{beg} } 1425sub urxvt::line::beg { $_[0]{beg} }
719sub urxvt::line::end { $_[0]{end} } 1426sub urxvt::line::end { $_[0]{end} }
720sub urxvt::line::l { $_[0]{len} } 1427sub urxvt::line::l { $_[0]{len} }
721 1428
722sub urxvt::line::offset_of { 1429sub urxvt::line::offset_of {
723 my ($self, $row, $col) = @_; 1430 my ($self, $row, $col) = @_;
724 1431
725 ($row - $self->{beg}) * $self->{term}->ncol + $col 1432 ($row - $self->{beg}) * $self->{ncol} + $col
726} 1433}
727 1434
728sub urxvt::line::coord_of { 1435sub urxvt::line::coord_of {
729 my ($self, $offset) = @_; 1436 my ($self, $offset) = @_;
730 1437
731 use integer; 1438 use integer;
732 1439
733 ( 1440 (
734 $offset / $self->{term}->ncol + $self->{beg}, 1441 $offset / $self->{ncol} + $self->{beg},
735 $offset % $self->{term}->ncol 1442 $offset % $self->{ncol}
736 ) 1443 )
737} 1444}
738 1445
739=item ($row, $col) = $line->coord_of ($offset)
740=item $text = $term->special_encode $string 1446=item $text = $term->special_encode $string
741 1447
742Converts a perl string into the special encoding used by rxvt-unicode, 1448Converts a perl string into the special encoding used by rxvt-unicode,
743where one character corresponds to one screen cell. See 1449where one character corresponds to one screen cell. See
744C<< $term->ROW_t >> for details. 1450C<< $term->ROW_t >> for details.
745 1451
746=item $string = $term->special_decode $text 1452=item $string = $term->special_decode $text
747 1453
748Converts rxvt-unicodes text reprsentation into a perl string. See 1454Converts rxvt-unicodes text reprsentation into a perl string. See
749C<< $term->ROW_t >> for details. 1455C<< $term->ROW_t >> for details.
1456
1457=item $success = $term->grab_button ($button, $modifiermask)
1458
1459Registers a synchronous button grab. See the XGrabButton manpage.
1460
1461=item $success = $term->grab ($eventtime[, $sync])
1462
1463Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1464synchronous (C<$sync> is true). Also remembers the grab timestampe.
1465
1466=item $term->allow_events_async
1467
1468Calls XAllowEvents with AsyncBoth for the most recent grab.
1469
1470=item $term->allow_events_sync
1471
1472Calls XAllowEvents with SyncBoth for the most recent grab.
1473
1474=item $term->allow_events_replay
1475
1476Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most
1477recent grab.
1478
1479=item $term->ungrab
1480
1481Calls XUngrab for the most recent grab. Is called automatically on
1482evaluation errors, as it is better to lose the grab in the error case as
1483the session.
1484
1485=back
1486
1487=cut
1488
1489package urxvt::popup;
1490
1491=head2 The C<urxvt::popup> Class
1492
1493=over 4
1494
1495=cut
1496
1497sub add_item {
1498 my ($self, $item) = @_;
1499
1500 $item->{rend}{normal} = "\x1b[0;30;47m" unless exists $item->{rend}{normal};
1501 $item->{rend}{hover} = "\x1b[0;30;46m" unless exists $item->{rend}{hover};
1502 $item->{rend}{active} = "\x1b[m" unless exists $item->{rend}{active};
1503
1504 $item->{render} ||= sub { $_[0]{text} };
1505
1506 push @{ $self->{item} }, $item;
1507}
1508
1509=item $popup->add_title ($title)
1510
1511Adds a non-clickable title to the popup.
1512
1513=cut
1514
1515sub add_title {
1516 my ($self, $title) = @_;
1517
1518 $self->add_item ({
1519 rend => { normal => "\x1b[38;5;11;44m", hover => "\x1b[38;5;11;44m", active => "\x1b[38;5;11;44m" },
1520 text => $title,
1521 activate => sub { },
1522 });
1523}
1524
1525=item $popup->add_separator ([$sepchr])
1526
1527Creates a separator, optionally using the character given as C<$sepchr>.
1528
1529=cut
1530
1531sub add_separator {
1532 my ($self, $sep) = @_;
1533
1534 $sep ||= "=";
1535
1536 $self->add_item ({
1537 rend => { normal => "\x1b[0;30;47m", hover => "\x1b[0;30;47m", active => "\x1b[0;30;47m" },
1538 text => "",
1539 render => sub { $sep x $self->{term}->ncol },
1540 activate => sub { },
1541 });
1542}
1543
1544=item $popup->add_button ($text, $cb)
1545
1546Adds a clickable button to the popup. C<$cb> is called whenever it is
1547selected.
1548
1549=cut
1550
1551sub add_button {
1552 my ($self, $text, $cb) = @_;
1553
1554 $self->add_item ({ type => "button", text => $text, activate => $cb});
1555}
1556
1557=item $popup->add_toggle ($text, $cb, $initial_value)
1558
1559Adds a toggle/checkbox item to the popup. Teh callback gets called
1560whenever it gets toggled, with a boolean indicating its value as its first
1561argument.
1562
1563=cut
1564
1565sub add_toggle {
1566 my ($self, $text, $cb, $value) = @_;
1567
1568 my $item; $item = {
1569 type => "button",
1570 text => " $text",
1571 value => $value,
1572 render => sub { ($_[0]{value} ? "* " : " ") . $text },
1573 activate => sub { $cb->($_[1]{value} = !$_[1]{value}); },
1574 };
1575
1576 $self->add_item ($item);
1577}
1578
1579=item $popup->show
1580
1581Displays the popup (which is initially hidden).
1582
1583=cut
1584
1585sub show {
1586 my ($self) = @_;
1587
1588 local $urxvt::popup::self = $self;
1589
1590 my $env = $self->{term}->env;
1591 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
1592 delete $env->{LC_ALL};
1593 $env->{LC_CTYPE} = $self->{term}->locale;
1594
1595 urxvt::term->new ($env, $self->{term}->resource ("name"),
1596 "--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0,
1597 "--transient-for" => $self->{term}->parent,
1598 "-display" => $self->{term}->display_id,
1599 "-pe" => "urxvt-popup")
1600 or die "unable to create popup window\n";
1601}
1602
1603sub DESTROY {
1604 my ($self) = @_;
1605
1606 delete $self->{term}{_destroy}{$self};
1607 $self->{term}->ungrab;
1608}
750 1609
751=back 1610=back
752 1611
753=head2 The C<urxvt::timer> Class 1612=head2 The C<urxvt::timer> Class
754 1613
809 1668
810 $term->{socket} = ... 1669 $term->{socket} = ...
811 $term->{iow} = urxvt::iow 1670 $term->{iow} = urxvt::iow
812 ->new 1671 ->new
813 ->fd (fileno $term->{socket}) 1672 ->fd (fileno $term->{socket})
814 ->events (1) # wait for read data 1673 ->events (urxvt::EVENT_READ)
815 ->start 1674 ->start
816 ->cb (sub { 1675 ->cb (sub {
817 my ($iow, $revents) = @_; 1676 my ($iow, $revents) = @_;
818 # $revents must be 1 here, no need to check 1677 # $revents must be 1 here, no need to check
819 sysread $term->{socket}, my $buf, 8192 1678 sysread $term->{socket}, my $buf, 8192
836 1695
837Set the filedescriptor (not handle) to watch. 1696Set the filedescriptor (not handle) to watch.
838 1697
839=item $iow = $iow->events ($eventmask) 1698=item $iow = $iow->events ($eventmask)
840 1699
841Set the event mask to watch. Bit #0 (value C<1>) enables watching for read 1700Set the event mask to watch. The only allowed values are
842data, Bit #1 (value C<2>) enables watching for write data. 1701C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed
1702together, or C<urxvt::EVENT_NONE>.
843 1703
844=item $iow = $iow->start 1704=item $iow = $iow->start
845 1705
846Start watching for requested events on the given handle. 1706Start watching for requested events on the given handle.
847 1707
858This variable controls the verbosity level of the perl extension. Higher 1718This variable controls the verbosity level of the perl extension. Higher
859numbers indicate more verbose output. 1719numbers indicate more verbose output.
860 1720
861=over 4 1721=over 4
862 1722
863=item =0 - only fatal messages 1723=item == 0 - fatal messages
864 1724
865=item =3 - script loading and management 1725=item >= 3 - script loading and management
866 1726
867=item =10 - all events received 1727=item >=10 - all called hooks
1728
1729=item >=11 - hook reutrn values
868 1730
869=back 1731=back
870 1732
871=head1 AUTHOR 1733=head1 AUTHOR
872 1734

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines