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