*** empty log message ***
[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    # overwrite perl's warn
601    *CORE::GLOBAL::warn = sub {
602       my $msg = join "", @_;
603       $msg .= "\n"
604          unless $msg =~ /\n$/;
605       urxvt::warn ($msg);
606    };
607
608    # %ENV is the original startup environment
609    delete $ENV{IFS};
610    delete $ENV{CDPATH};
611    delete $ENV{BASH_ENV};
612    $ENV{PATH} = "/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/opt/bin:/opt/sbin";
613 }
614
615 my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
616
617 sub verbose {
618    my ($level, $msg) = @_;
619    warn "$msg\n" if $level <= $verbosity;
620 }
621
622 my %extension_pkg;
623
624 # load a single script into its own package, once only
625 sub extension_package($) {
626    my ($path) = @_;
627
628    no strict 'refs';
629
630    $extension_pkg{$path} ||= do {
631       $path =~ /([^\/\\]+)$/;
632       my $pkg = $1;
633       $pkg =~ s/[^[:word:]]/_/g;
634       $pkg = "urxvt::ext::$pkg";
635
636       verbose 3, "loading extension '$path' into package '$pkg'";
637
638       open my $fh, "<:raw", $path
639          or die "$path: $!";
640
641       @{"$pkg\::ISA"} = urxvt::term::extension::;
642
643       my $source =
644          "package $pkg; use strict; use utf8;\n"
645          . "#line 1 \"$path\"\n{\n"
646          . (do { local $/; <$fh> })
647          . "\n};\n1";
648
649       eval $source
650          or die "$path: $@";
651
652       $pkg
653    }
654 }
655
656 our $retval; # return value for urxvt
657
658 # called by the rxvt core
659 sub invoke {
660    local $TERM = shift;
661    my $htype = shift;
662
663    if ($htype == 0) { # INIT
664       my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
665       
666       my %ext_arg;
667
668       for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
669          if ($_ eq "default") {
670             $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback);
671          } elsif (/^-(.*)$/) {
672             delete $ext_arg{$1};
673          } elsif (/^([^<]+)<(.*)>$/) {
674             push @{ $ext_arg{$1} }, $2;
675          } else {
676             $ext_arg{$_} ||= [];
677          }
678       }
679
680       while (my ($ext, $argv) = each %ext_arg) {
681          my @files = grep -f $_, map "$_/$ext", @dirs;
682
683          if (@files) {
684             $TERM->register_package (extension_package $files[0], $argv);
685          } else {
686             warn "perl extension '$ext' not found in perl library search path\n";
687          }
688       }
689
690       eval "#line 1 \"--perl-eval resource/argument\"\n" . $TERM->resource ("perl_eval");
691       warn $@ if $@;
692    }
693
694    $retval = undef;
695
696    if (my $cb = $TERM->{_hook}[$htype]) {
697       verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
698          if $verbosity >= 10;
699
700       keys %$cb;
701
702       while (my ($pkg, $cb) = each %$cb) {
703          $retval = eval { $cb->($TERM->{_pkg}{$pkg}, @_) }
704             and last;
705
706          if ($@) {
707             $TERM->ungrab; # better to lose the grab than the session
708             warn $@;
709          }
710       }
711
712       verbose 11, "$HOOKNAME[$htype] returning <$retval>"
713          if $verbosity >= 11;
714    }
715
716    if ($htype == 1) { # DESTROY
717       # clear package objects
718       %$_ = () for values %{ $TERM->{_pkg} };
719
720       # clear package
721       %$TERM = ();
722    }
723
724    $retval
725 }
726
727 sub exec_async(@) {
728    my $pid = fork;
729
730    return
731       if !defined $pid or $pid;
732
733    %ENV = %{ $TERM->env };
734
735    exec @_;
736    _exit 255;
737 }
738
739 # urxvt::term::extension
740
741 package urxvt::term::extension;
742
743 sub enable {
744    my ($self, %hook) = @_;
745    my $pkg = $self->{_pkg};
746
747    while (my ($name, $cb) = each %hook) {
748       my $htype = $HOOKTYPE{uc $name};
749       defined $htype
750          or Carp::croak "unsupported hook type '$name'";
751
752       $self->set_should_invoke ($htype, +1)
753          unless exists $self->{term}{_hook}[$htype]{$pkg};
754
755       $self->{term}{_hook}[$htype]{$pkg} = $cb;
756    }
757 }
758
759 sub disable {
760    my ($self, @hook) = @_;
761    my $pkg = $self->{_pkg};
762
763    for my $name (@hook) {
764       my $htype = $HOOKTYPE{uc $name};
765       defined $htype
766          or Carp::croak "unsupported hook type '$name'";
767
768       $self->set_should_invoke ($htype, -1)
769          if delete $self->{term}{_hook}[$htype]{$pkg};
770    }
771 }
772
773 our $AUTOLOAD;
774
775 sub AUTOLOAD {
776    $AUTOLOAD =~ /:([^:]+)$/
777       or die "FATAL: \$AUTOLOAD '$AUTOLOAD' unparsable";
778
779    eval qq{
780       sub $AUTOLOAD {
781          my \$proxy = shift;
782          \$proxy->{term}->$1 (\@_)
783       }
784       1
785    } or die "FATAL: unable to compile method forwarder: $@";
786
787    goto &$AUTOLOAD;
788 }
789
790 sub DESTROY {
791    # nop
792 }
793
794 # urxvt::destroy_hook
795
796 sub urxvt::destroy_hook::DESTROY {
797    ${$_[0]}->();
798 }
799
800 sub urxvt::destroy_hook(&) {
801    bless \shift, urxvt::destroy_hook::
802 }
803
804 package urxvt::anyevent;
805
806 =head2 The C<urxvt::anyevent> Class
807
808 The sole purpose of this class is to deliver an interface to the
809 C<AnyEvent> module - any module using it will work inside urxvt without
810 further programming. The only exception is that you cannot wait on
811 condition variables, but non-blocking condvar use is ok. What this means
812 is that you cannot use blocking APIs, but the non-blocking variant should
813 work.
814
815 =cut
816
817 our $VERSION = 1;
818
819 $INC{"urxvt/anyevent.pm"} = 1; # mark us as there
820 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
821
822 sub timer {
823    my ($class, %arg) = @_;
824
825    my $cb = $arg{cb};
826
827    urxvt::timer
828       ->new
829       ->start (urxvt::NOW + $arg{after})
830       ->cb (sub {
831         $_[0]->stop; # need to cancel manually
832         $cb->();
833       })
834 }
835
836 sub io {
837    my ($class, %arg) = @_;
838
839    my $cb = $arg{cb};
840
841    bless [$arg{fh}, urxvt::iow
842              ->new
843              ->fd (fileno $arg{fh})
844              ->events (($arg{poll} =~ /r/ ? 1 : 0)
845                      | ($arg{poll} =~ /w/ ? 2 : 0))
846              ->start
847              ->cb (sub {
848                 $cb->(($_[1] & 1 ? 'r' : '')
849                     . ($_[1] & 2 ? 'w' : ''));
850              })],
851          urxvt::anyevent::
852 }
853
854 sub DESTROY {
855    $_[0][1]->stop;
856 }
857
858 sub condvar {
859    bless \my $flag, urxvt::anyevent::condvar::
860 }
861
862 sub urxvt::anyevent::condvar::broadcast {
863    ${$_[0]}++;
864 }
865
866 sub urxvt::anyevent::condvar::wait {
867    unless (${$_[0]}) {
868       Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API";
869    }
870 }
871
872 package urxvt::term;
873
874 =head2 The C<urxvt::term> Class
875
876 =over 4
877
878 =cut
879
880 # find on_xxx subs in the package and register them
881 # as hooks
882 sub register_package {
883    my ($self, $pkg, $argv) = @_;
884
885    my $proxy = bless {
886       _pkg => $pkg,
887       argv => $argv,
888    }, $pkg;
889    Scalar::Util::weaken ($proxy->{term} = $self);
890
891    $self->{_pkg}{$pkg} = $proxy;
892
893    for my $name (@HOOKNAME) {
894       if (my $ref = $pkg->can ("on_" . lc $name)) {
895          $proxy->enable ($name => $ref);
896       }
897    }
898 }
899
900 =item $term = new urxvt::term $envhashref, $rxvtname, [arg...]
901
902 Creates a new terminal, very similar as if you had started it with system
903 C<$rxvtname, arg...>. C<$envhashref> must be a reference to a C<%ENV>-like
904 hash which defines the environment of the new terminal.
905
906 Croaks (and probably outputs an error message) if the new instance
907 couldn't be created.  Returns C<undef> if the new instance didn't
908 initialise perl, and the terminal object otherwise. The C<init> and
909 C<start> hooks will be called during this call.
910
911 =cut
912
913 sub new {
914    my ($class, $env, @args) = @_;
915
916    _new ([ map "$_=$env->{$_}", keys %$env ], @args);
917 }
918
919 =item $term->destroy
920
921 Destroy the terminal object (close the window, free resources
922 etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event
923 watchers (timers, io watchers) are still active.
924
925 =item $isset = $term->option ($optval[, $set])
926
927 Returns true if the option specified by C<$optval> is enabled, and
928 optionally change it. All option values are stored by name in the hash
929 C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
930
931 Here is a a likely non-exhaustive list of option names, please see the
932 source file F</src/optinc.h> to see the actual list:
933
934  borderLess console cursorBlink cursorUnderline hold iconic insecure
935  intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
936  pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating
937  scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer
938  secondaryScreen secondaryScroll skipBuiltinGlyphs transparent
939  tripleclickwords utmpInhibit visualBell
940
941 =item $value = $term->resource ($name[, $newval])
942
943 Returns the current resource value associated with a given name and
944 optionally sets a new value. Setting values is most useful in the C<init>
945 hook. Unset resources are returned and accepted as C<undef>.
946
947 The new value must be properly encoded to a suitable character encoding
948 before passing it to this method. Similarly, the returned value may need
949 to be converted from the used encoding to text.
950
951 Resource names are as defined in F<src/rsinc.h>. Colours can be specified
952 as resource names of the form C<< color+<index> >>, e.g. C<color+5>. (will
953 likely change).
954
955 Please note that resource strings will currently only be freed when the
956 terminal is destroyed, so changing options frequently will eat memory.
957
958 Here is a a likely non-exhaustive list of resource names, not all of which
959 are supported in every build, please see the source file F</src/rsinc.h>
960 to see the actual list:
961
962   answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
963   borderLess color cursorBlink cursorUnderline cutchars delete_key
964   display_name embed ext_bwidth fade font geometry hold iconName
965   imFont imLocale inputMethod insecure int_bwidth intensityStyles
966   italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
967   mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2
968   perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
969   reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
970   scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
971   scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
972   shade term_name title transparent transparent_all tripleclickwords
973   utmpInhibit visualBell
974
975 =cut
976
977 sub resource($$;$) {
978    my ($self, $name) = (shift, shift);
979    unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
980    &urxvt::term::_resource
981 }
982
983 =item $value = $term->x_resource ($pattern)
984
985 Returns the X-Resource for the given pattern, excluding the program or
986 class name, i.e.  C<< $term->x_resource ("boldFont") >> should return the
987 same value as used by this instance of rxvt-unicode. Returns C<undef> if no
988 resource with that pattern exists.
989
990 This method should only be called during the C<on_start> hook, as there is
991 only one resource database per display, and later invocations might return
992 the wrong resources.
993
994 =item $success = $term->parse_keysym ($keysym_spec, $command_string)
995
996 Adds a keymap translation exactly as specified via a resource. See the
997 C<keysym> resource in the @@RXVT_NAME@@(1) manpage.
998
999 =item $rend = $term->rstyle ([$new_rstyle])
1000
1001 Return and optionally change the current rendition. Text that is output by
1002 the terminal application will use this style.
1003
1004 =item ($row, $col) = $term->screen_cur ([$row, $col])
1005
1006 Return the current coordinates of the text cursor position and optionally
1007 set it (which is usually bad as applications don't expect that).
1008
1009 =item ($row, $col) = $term->selection_mark ([$row, $col])
1010
1011 =item ($row, $col) = $term->selection_beg ([$row, $col])
1012
1013 =item ($row, $col) = $term->selection_end ([$row, $col])
1014
1015 Return the current values of the selection mark, begin or end positions,
1016 and optionally set them to new values.
1017
1018 =item $term->selection_make ($eventtime[, $rectangular])
1019
1020 Tries to make a selection as set by C<selection_beg> and
1021 C<selection_end>. If C<$rectangular> is true (default: false), a
1022 rectangular selection will be made. This is the prefered function to make
1023 a selection.
1024
1025 =item $success = $term->selection_grab ($eventtime)
1026
1027 Try to request the primary selection text from the server (for example, as
1028 set by the next method). No visual feedback will be given. This function
1029 is mostly useful from within C<on_sel_grab> hooks.
1030
1031 =item $oldtext = $term->selection ([$newtext])
1032
1033 Return the current selection text and optionally replace it by C<$newtext>.
1034
1035 =item $term->overlay_simple ($x, $y, $text)
1036
1037 Create a simple multi-line overlay box. See the next method for details.
1038
1039 =cut
1040
1041 sub overlay_simple {
1042    my ($self, $x, $y, $text) = @_;
1043
1044    my @lines = split /\n/, $text;
1045
1046    my $w = List::Util::max map $self->strwidth ($_), @lines;
1047
1048    my $overlay = $self->overlay ($x, $y, $w, scalar @lines);
1049    $overlay->set (0, $_, $lines[$_]) for 0.. $#lines;
1050
1051    $overlay
1052 }
1053
1054 =item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
1055
1056 Create a new (empty) overlay at the given position with the given
1057 width/height. C<$rstyle> defines the initial rendition style
1058 (default: C<OVERLAY_RSTYLE>).
1059
1060 If C<$border> is C<2> (default), then a decorative border will be put
1061 around the box.
1062
1063 If either C<$x> or C<$y> is negative, then this is counted from the
1064 right/bottom side, respectively.
1065
1066 This method returns an urxvt::overlay object. The overlay will be visible
1067 as long as the perl object is referenced.
1068
1069 The methods currently supported on C<urxvt::overlay> objects are:
1070
1071 =over 4
1072
1073 =item $overlay->set ($x, $y, $text, $rend)
1074
1075 Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts
1076 text in rxvt-unicode's special encoding and an array of rendition values
1077 at a specific position inside the overlay.
1078
1079 =item $overlay->hide
1080
1081 If visible, hide the overlay, but do not destroy it.
1082
1083 =item $overlay->show
1084
1085 If hidden, display the overlay again.
1086
1087 =back
1088
1089 =item $popup = $term->popup ($event)
1090
1091 Creates a new C<urxvt::popup> object that implements a popup menu. The
1092 C<$event> I<must> be the event causing the menu to pop up (a button event,
1093 currently).
1094
1095 =cut
1096
1097 sub popup {
1098    my ($self, $event) = @_;
1099
1100    $self->grab ($event->{time}, 1)
1101       or return;
1102
1103    my $popup = bless {
1104       term  => $self,
1105       event => $event,
1106    }, urxvt::popup::;
1107
1108    Scalar::Util::weaken $popup->{term};
1109
1110    $self->{_destroy}{$popup} = urxvt::destroy_hook { $popup->{popup}->destroy };
1111    Scalar::Util::weaken $self->{_destroy}{$popup};
1112
1113    $popup
1114 }
1115
1116 =item $cellwidth = $term->strwidth ($string)
1117
1118 Returns the number of screen-cells this string would need. Correctly
1119 accounts for wide and combining characters.
1120
1121 =item $octets = $term->locale_encode ($string)
1122
1123 Convert the given text string into the corresponding locale encoding.
1124
1125 =item $string = $term->locale_decode ($octets)
1126
1127 Convert the given locale-encoded octets into a perl string.
1128
1129 =item $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
1130
1131 XORs the rendition values in the given span with the provided value
1132 (default: C<RS_RVid>), which I<MUST NOT> contain font styles. Useful in
1133 refresh hooks to provide effects similar to the selection.
1134
1135 =item $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, $rstyle2]])
1136
1137 Similar to C<scr_xor_span>, but xors a rectangle instead. Trailing
1138 whitespace will additionally be xored with the C<$rstyle2>, which defaults
1139 to C<RS_RVid | RS_Uline>, which removes reverse video again and underlines
1140 it instead. Both styles I<MUST NOT> contain font styles.
1141
1142 =item $term->scr_bell
1143
1144 Ring the bell!
1145
1146 =item $term->scr_add_lines ($string)
1147
1148 Write the given text string to the screen, as if output by the application
1149 running inside the terminal. It may not contain command sequences (escape
1150 codes), but is free to use line feeds, carriage returns and tabs. The
1151 string is a normal text string, not in locale-dependent encoding.
1152
1153 Normally its not a good idea to use this function, as programs might be
1154 confused by changes in cursor position or scrolling. Its useful inside a
1155 C<on_add_lines> hook, though.
1156
1157 =item $term->cmd_parse ($octets)
1158
1159 Similar to C<scr_add_lines>, but the argument must be in the
1160 locale-specific encoding of the terminal and can contain command sequences
1161 (escape codes) that will be interpreted.
1162
1163 =item $term->tt_write ($octets)
1164
1165 Write the octets given in C<$data> to the tty (i.e. as program input). To
1166 pass characters instead of octets, you should convert your strings first
1167 to the locale-specific encoding using C<< $term->locale_encode >>.
1168
1169 =item $old_events = $term->pty_ev_events ([$new_events])
1170
1171 Replaces the event mask of the pty watcher by the given event mask. Can
1172 be used to suppress input and output handling to the pty/tty. See the
1173 description of C<< urxvt::timer->events >>. Make sure to always restore
1174 the previous value.
1175
1176 =item $windowid = $term->parent
1177
1178 Return the window id of the toplevel window.
1179
1180 =item $windowid = $term->vt
1181
1182 Return the window id of the terminal window.
1183
1184 =item $term->vt_emask_add ($x_event_mask)
1185
1186 Adds the specified events to the vt event mask. Useful e.g. when you want
1187 to receive pointer events all the times:
1188
1189    $term->vt_emask_add (urxvt::PointerMotionMask);
1190
1191 =item $window_width = $term->width
1192
1193 =item $window_height = $term->height
1194
1195 =item $font_width = $term->fwidth
1196
1197 =item $font_height = $term->fheight
1198
1199 =item $font_ascent = $term->fbase
1200
1201 =item $terminal_rows = $term->nrow
1202
1203 =item $terminal_columns = $term->ncol
1204
1205 =item $has_focus = $term->focus
1206
1207 =item $is_mapped = $term->mapped
1208
1209 =item $max_scrollback = $term->saveLines
1210
1211 =item $nrow_plus_saveLines = $term->total_rows
1212
1213 =item $topmost_scrollback_row = $term->top_row
1214
1215 Return various integers describing terminal characteristics.
1216
1217 =item $x_display = $term->display_id
1218
1219 Return the DISPLAY used by rxvt-unicode.
1220
1221 =item $lc_ctype = $term->locale
1222
1223 Returns the LC_CTYPE category string used by this rxvt-unicode.
1224
1225 =item $env = $term->env
1226
1227 Returns a copy of the environment in effect for the terminal as a hashref
1228 similar to C<\%ENV>.
1229
1230 =cut
1231
1232 sub env {
1233    if (my $env = $_[0]->_env) {
1234       +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env }
1235    } else {
1236       +{ %ENV }
1237    }
1238 }
1239
1240 =item $modifiermask = $term->ModLevel3Mask
1241
1242 =item $modifiermask = $term->ModMetaMask
1243
1244 =item $modifiermask = $term->ModNumLockMask
1245
1246 Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
1247 AltGr), the meta key (often Alt) and the num lock key, if applicable.
1248
1249 =item $view_start = $term->view_start ([$newvalue])
1250
1251 Returns the row number of the topmost displayed line. Maximum value is
1252 C<0>, which displays the normal terminal contents. Lower values scroll
1253 this many lines into the scrollback buffer.
1254
1255 =item $term->want_refresh
1256
1257 Requests a screen refresh. At the next opportunity, rxvt-unicode will
1258 compare the on-screen display with its stored representation. If they
1259 differ, it redraws the differences.
1260
1261 Used after changing terminal contents to display them.
1262
1263 =item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
1264
1265 Returns the text of the entire row with number C<$row_number>. Row C<0>
1266 is the topmost terminal line, row C<< $term->$ncol-1 >> is the bottommost
1267 terminal line. The scrollback buffer starts at line C<-1> and extends to
1268 line C<< -$term->nsaved >>. Nothing will be returned if a nonexistent line
1269 is requested.
1270
1271 If C<$new_text> is specified, it will replace characters in the current
1272 line, starting at column C<$start_col> (default C<0>), which is useful
1273 to replace only parts of a line. The font index in the rendition will
1274 automatically be updated.
1275
1276 C<$text> is in a special encoding: tabs and wide characters that use more
1277 than one cell when displayed are padded with urxvt::NOCHAR characters
1278 (C<chr 65535>). Characters with combining characters and other characters
1279 that do not fit into the normal tetx encoding will be replaced with
1280 characters in the private use area.
1281
1282 You have to obey this encoding when changing text. The advantage is
1283 that C<substr> and similar functions work on screen cells and not on
1284 characters.
1285
1286 The methods C<< $term->special_encode >> and C<< $term->special_decode >>
1287 can be used to convert normal strings into this encoding and vice versa.
1288
1289 =item $rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])
1290
1291 Like C<< $term->ROW_t >>, but returns an arrayref with rendition
1292 bitsets. Rendition bitsets contain information about colour, font, font
1293 styles and similar information. See also C<< $term->ROW_t >>.
1294
1295 When setting rendition, the font mask will be ignored.
1296
1297 See the section on RENDITION, above.
1298
1299 =item $length = $term->ROW_l ($row_number[, $new_length])
1300
1301 Returns the number of screen cells that are in use ("the line
1302 length"). Unlike the urxvt core, this returns C<< $term->ncol >> if the
1303 line is joined with the following one.
1304
1305 =item $bool = $term->is_longer ($row_number)
1306
1307 Returns true if the row is part of a multiple-row logical "line" (i.e.
1308 joined with the following row), which means all characters are in use
1309 and it is continued on the next row (and possibly a continuation of the
1310 previous row(s)).
1311
1312 =item $line = $term->line ($row_number)
1313
1314 Create and return a new C<urxvt::line> object that stores information
1315 about the logical line that row C<$row_number> is part of. It supports the
1316 following methods:
1317
1318 =over 4
1319
1320 =item $text = $line->t ([$new_text])
1321
1322 Returns or replaces the full text of the line, similar to C<ROW_t>
1323
1324 =item $rend = $line->r ([$new_rend])
1325
1326 Returns or replaces the full rendition array of the line, similar to C<ROW_r>
1327
1328 =item $length = $line->l
1329
1330 Returns the length of the line in cells, similar to C<ROW_l>.
1331
1332 =item $rownum = $line->beg
1333
1334 =item $rownum = $line->end
1335
1336 Return the row number of the first/last row of the line, respectively.
1337
1338 =item $offset = $line->offset_of ($row, $col)
1339
1340 Returns the character offset of the given row|col pair within the logical
1341 line. Works for rows outside the line, too, and returns corresponding
1342 offsets outside the string.
1343
1344 =item ($row, $col) = $line->coord_of ($offset)
1345
1346 Translates a string offset into terminal coordinates again.
1347
1348 =back
1349
1350 =cut
1351
1352 sub line {
1353    my ($self, $row) = @_;
1354
1355    my $maxrow = $self->nrow - 1;
1356
1357    my ($beg, $end) = ($row, $row);
1358
1359    --$beg while $self->ROW_is_longer ($beg - 1);
1360    ++$end while $self->ROW_is_longer ($end) && $end < $maxrow;
1361
1362    bless {
1363       term => $self,
1364       beg  => $beg,
1365       end  => $end,
1366       ncol => $self->ncol,
1367       len  => ($end - $beg) * $self->ncol + $self->ROW_l ($end),
1368    }, urxvt::line::
1369 }
1370
1371 sub urxvt::line::t {
1372    my ($self) = @_;
1373
1374    if (@_ > 1)
1375      {
1376        $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
1377           for $self->{beg} .. $self->{end};
1378      }
1379
1380    defined wantarray &&
1381       substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
1382              0, $self->{len}
1383 }
1384
1385 sub urxvt::line::r {
1386    my ($self) = @_;
1387
1388    if (@_ > 1)
1389      {
1390        $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
1391           for $self->{beg} .. $self->{end};
1392      }
1393
1394    if (defined wantarray) {
1395       my $rend = [
1396          map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
1397       ];
1398       $#$rend = $self->{len} - 1;
1399       return $rend;
1400    }
1401
1402    ()
1403 }
1404
1405 sub urxvt::line::beg { $_[0]{beg} }
1406 sub urxvt::line::end { $_[0]{end} }
1407 sub urxvt::line::l   { $_[0]{len} }
1408
1409 sub urxvt::line::offset_of {
1410    my ($self, $row, $col) = @_;
1411
1412    ($row - $self->{beg}) * $self->{ncol} + $col
1413 }
1414
1415 sub urxvt::line::coord_of {
1416    my ($self, $offset) = @_;
1417
1418    use integer;
1419
1420    (
1421       $offset / $self->{ncol} + $self->{beg},
1422       $offset % $self->{ncol}
1423    )
1424 }
1425
1426 =item $text = $term->special_encode $string
1427
1428 Converts a perl string into the special encoding used by rxvt-unicode,
1429 where one character corresponds to one screen cell. See
1430 C<< $term->ROW_t >> for details.
1431
1432 =item $string = $term->special_decode $text
1433
1434 Converts rxvt-unicodes text reprsentation into a perl string. See
1435 C<< $term->ROW_t >> for details.
1436
1437 =item $success = $term->grab_button ($button, $modifiermask)
1438
1439 Registers a synchronous button grab. See the XGrabButton manpage.
1440
1441 =item $success = $term->grab ($eventtime[, $sync])
1442
1443 Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1444 synchronous (C<$sync> is true). Also remembers the grab timestampe.
1445
1446 =item $term->allow_events_async
1447
1448 Calls XAllowEvents with AsyncBoth for the most recent grab.
1449
1450 =item $term->allow_events_sync
1451
1452 Calls XAllowEvents with SyncBoth for the most recent grab.
1453
1454 =item $term->allow_events_replay
1455
1456 Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most
1457 recent grab.
1458
1459 =item $term->ungrab
1460
1461 Calls XUngrab for the most recent grab. Is called automatically on
1462 evaluation errors, as it is better to lose the grab in the error case as
1463 the session.
1464
1465 =back
1466
1467 =cut
1468
1469 package urxvt::popup;
1470
1471 =head2 The C<urxvt::popup> Class
1472
1473 =over 4
1474
1475 =cut
1476
1477 sub add_item {
1478    my ($self, $item) = @_;
1479
1480    $item->{rend}{normal} = "\x1b[0;30;47m" unless exists $item->{rend}{normal};
1481    $item->{rend}{hover}  = "\x1b[0;30;46m" unless exists $item->{rend}{hover};
1482    $item->{rend}{active} = "\x1b[m"        unless exists $item->{rend}{active};
1483
1484    $item->{render} ||= sub { $_[0]{text} };
1485
1486    push @{ $self->{item} }, $item;
1487 }
1488
1489 =item $popup->add_title ($title)
1490
1491 Adds a non-clickable title to the popup.
1492
1493 =cut
1494
1495 sub add_title {
1496    my ($self, $title) = @_;
1497
1498    $self->add_item ({
1499       rend => { normal => "\x1b[38;5;11;44m", hover => "\x1b[38;5;11;44m", active => "\x1b[38;5;11;44m" },
1500       text => $title,
1501       activate => sub { },
1502    });
1503 }
1504
1505 =item $popup->add_separator ([$sepchr])
1506
1507 Creates a separator, optionally using the character given as C<$sepchr>.
1508
1509 =cut
1510
1511 sub add_separator {
1512    my ($self, $sep) = @_;
1513
1514    $sep ||= "=";
1515
1516    $self->add_item ({
1517       rend => { normal => "\x1b[0;30;47m", hover => "\x1b[0;30;47m", active => "\x1b[0;30;47m" },
1518       text => "",
1519       render => sub { $sep x $self->{term}->ncol },
1520       activate => sub { },
1521    });
1522 }
1523
1524 =item $popup->add_button ($text, $cb)
1525
1526 Adds a clickable button to the popup. C<$cb> is called whenever it is
1527 selected.
1528
1529 =cut
1530
1531 sub add_button {
1532    my ($self, $text, $cb) = @_;
1533
1534    $self->add_item ({ type => "button", text => $text, activate => $cb});
1535 }
1536
1537 =item $popup->add_toggle ($text, $cb, $initial_value)
1538
1539 Adds a toggle/checkbox item to the popup. Teh callback gets called
1540 whenever it gets toggled, with a boolean indicating its value as its first
1541 argument.
1542
1543 =cut
1544
1545 sub add_toggle {
1546    my ($self, $text, $cb, $value) = @_;
1547
1548    my $item; $item = {
1549       type => "button",
1550       text => "  $text",
1551       value => $value,
1552       render => sub { ($_[0]{value} ? "* " : "  ") . $text },
1553       activate => sub { $cb->($_[1]{value} = !$_[1]{value}); },
1554    };
1555
1556    $self->add_item ($item);
1557 }
1558
1559 =item $popup->show
1560
1561 Displays the popup (which is initially hidden).
1562
1563 =cut
1564
1565 sub show {
1566    my ($self) = @_;
1567
1568    local $urxvt::popup::self = $self;
1569
1570    my $env = $self->{term}->env;
1571    # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
1572    delete $env->{LC_ALL};
1573    $env->{LC_CTYPE} = $self->{term}->locale;
1574
1575    urxvt::term->new ($env, $self->{term}->resource ("name"),
1576                      "--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0,
1577                      "--transient-for" => $self->{term}->parent,
1578                      "-display" => $self->{term}->display_id,
1579                      "-pe" => "urxvt-popup")
1580       or die "unable to create popup window\n";
1581 }
1582
1583 sub DESTROY {
1584    my ($self) = @_;
1585
1586    delete $self->{term}{_destroy}{$self};
1587    $self->{term}->ungrab;
1588 }
1589
1590 =back
1591
1592 =head2 The C<urxvt::timer> Class
1593
1594 This class implements timer watchers/events. Time is represented as a
1595 fractional number of seconds since the epoch. Example:
1596
1597    $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
1598    $term->{timer} = urxvt::timer
1599                     ->new
1600                     ->interval (1)
1601                     ->cb (sub {
1602                        $term->{overlay}->set (0, 0,
1603                           sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
1604                     });                                                                                                                                      
1605
1606 =over 4
1607
1608 =item $timer = new urxvt::timer
1609
1610 Create a new timer object in started state. It is scheduled to fire
1611 immediately.
1612
1613 =item $timer = $timer->cb (sub { my ($timer) = @_; ... })
1614
1615 Set the callback to be called when the timer triggers.
1616
1617 =item $tstamp = $timer->at
1618
1619 Return the time this watcher will fire next.
1620
1621 =item $timer = $timer->set ($tstamp)
1622
1623 Set the time the event is generated to $tstamp.
1624
1625 =item $timer = $timer->interval ($interval)
1626
1627 Normally (and when C<$interval> is C<0>), the timer will automatically
1628 stop after it has fired once. If C<$interval> is non-zero, then the timer
1629 is automatically rescheduled at the given intervals.
1630
1631 =item $timer = $timer->start
1632
1633 Start the timer.
1634
1635 =item $timer = $timer->start ($tstamp)
1636
1637 Set the event trigger time to C<$tstamp> and start the timer.
1638
1639 =item $timer = $timer->stop
1640
1641 Stop the timer.
1642
1643 =back
1644
1645 =head2 The C<urxvt::iow> Class
1646
1647 This class implements io watchers/events. Example:
1648
1649   $term->{socket} = ...
1650   $term->{iow} = urxvt::iow
1651                  ->new
1652                  ->fd (fileno $term->{socket})
1653                  ->events (urxvt::EVENT_READ)
1654                  ->start
1655                  ->cb (sub {
1656                    my ($iow, $revents) = @_;
1657                    # $revents must be 1 here, no need to check
1658                    sysread $term->{socket}, my $buf, 8192
1659                       or end-of-file;
1660                  });
1661
1662
1663 =over 4
1664
1665 =item $iow = new urxvt::iow
1666
1667 Create a new io watcher object in stopped state.
1668
1669 =item $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
1670
1671 Set the callback to be called when io events are triggered. C<$reventmask>
1672 is a bitset as described in the C<events> method.
1673
1674 =item $iow = $iow->fd ($fd)
1675
1676 Set the filedescriptor (not handle) to watch.
1677
1678 =item $iow = $iow->events ($eventmask)
1679
1680 Set the event mask to watch. The only allowed values are
1681 C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed
1682 together, or C<urxvt::EVENT_NONE>.
1683
1684 =item $iow = $iow->start
1685
1686 Start watching for requested events on the given handle.
1687
1688 =item $iow = $iow->stop
1689
1690 Stop watching for events on the given filehandle.
1691
1692 =back
1693
1694 =head1 ENVIRONMENT
1695
1696 =head2 URXVT_PERL_VERBOSITY
1697
1698 This variable controls the verbosity level of the perl extension. Higher
1699 numbers indicate more verbose output.
1700
1701 =over 4
1702
1703 =item == 0 - fatal messages
1704
1705 =item >= 3 - script loading and management
1706
1707 =item >=10 - all called hooks
1708
1709 =item >=11 - hook reutrn values
1710
1711 =back
1712
1713 =head1 AUTHOR
1714
1715  Marc Lehmann <pcg@goof.com>
1716  http://software.schmorp.de/pkg/rxvt-unicode
1717
1718 =cut
1719
1720 1