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