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 =head2 Prepackaged Extensions
  32
  33 This section describes the extensiosn delivered with this version. 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 Intelligent selection. This extension tries to be more intelligent when
  45 the user extends selections (double-click). Right now, it tries to select
  46 urls and complete shell-quoted arguments, which is very convenient, too,
  47 if your F<ls> supports C<--quoting-style=shell>.
  48
  49 It also offers the following bindable event:
  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-Button3 that lets you toggle (some) options at
  64 runtime.
  65
  66 =item digital-clock
  67
  68 Displays a digital clock using the built-in overlay.
  69
  70 =item mark-urls
  71
  72 Uses per-line display filtering (C<on_line_update>) to underline urls.
  73
  74 =item block-graphics-to-ascii
  75
  76 A not very useful example of filtering all text output to the terminal,
  77 by replacing all line-drawing characters (U+2500 .. U+259F) by a
  78 similar-looking ascii character.
  79
  80 =item example-refresh-hooks
  81
  82 Displays a very simple digital clock in the upper right corner of the
  83 window. Illustrates overwriting the refresh callbacks to create your own
  84 overlays or changes.
  85
  86 =back
  87
  88 =head2 General API Considerations
  89
  90 All objects (such as terminals, time watchers etc.) are typical
  91 reference-to-hash objects. The hash can be used to store anything you
  92 like. All members starting with an underscore (such as C<_ptr> or
  93 C<_hook>) are reserved for internal uses and B<MUST NOT> be accessed or
  94 modified).
  95
  96 When objects are destroyed on the C++ side, the perl object hashes are
  97 emptied, so its best to store related objects such as time watchers and
  98 the like inside the terminal object so they get destroyed as soon as the
  99 terminal is destroyed.
 100
 101 Argument names also often indicate the type of a parameter. Here are some
 102 hints on what they mean:
 103
 104 =over 4
 105
 106 =item $text
 107
 108 Rxvt-unicodes special way of encoding text, where one "unicode" character
 109 always represents one screen cell. See L<row_t> for a discussion of this format.
 110
 111 =item $string
 112
 113 A perl text string, with an emphasis on I<text>. It can store all unicode
 114 characters and is to be distinguished with text encoded in a specific
 115 encoding (often locale-specific) and binary data.
 116
 117 =item $octets
 118
 119 Either binary data or - more common - a text string encoded in a
 120 locale-specific way.
 121
 122 =back
 123
 124 =head2 Hooks
 125
 126 The following subroutines can be declared in extension files, and will be
 127 called whenever the relevant event happens.
 128
 129 The first argument passed to them is an object private to each terminal
 130 and extension package. You can call all C<urxvt::term> methods on it, but
 131 its not a real C<urxvt::term> object. Instead, the real C<urxvt::term>
 132 object that is shared between all packages is stored in the C<term>
 133 member. It is, however, blessed intot he package of the extension script,
 134 so for all practical purposes you can treat an extension script as a class.
 135
 136 All of them must return a boolean value. If it is true, then the event
 137 counts as being I<consumed>, and the invocation of other hooks is skipped,
 138 and the relevant action might not be carried out by the C++ code.
 139
 140 When in doubt, return a false value (preferably C<()>).
 141
 142 =over 4
 143
 144 =item on_init $term
 145
 146 Called after a new terminal object has been initialized, but before
 147 windows are created or the command gets run. Most methods are unsafe to
 148 call or deliver senseless data, as terminal size and other characteristics
 149 have not yet been determined. You can safely query and change resources,
 150 though.
 151
 152 =item on_reset $term
 153
 154 Called after the screen is "reset" for any reason, such as resizing or
 155 control sequences. Here is where you can react on changes to size-related
 156 variables.
 157
 158 =item on_start $term
 159
 160 Called at the very end of initialisation of a new terminal, just before
 161 returning to the mainloop.
 162
 163 =item on_sel_make $term, $eventtime
 164
 165 Called whenever a selection has been made by the user, but before the
 166 selection text is copied, so changes to the beginning, end or type of the
 167 selection will be honored.
 168
 169 Returning a true value aborts selection making by urxvt, in which case you
 170 have to make a selection yourself by calling C<< $term->selection_grab >>.
 171
 172 =item on_sel_grab $term, $eventtime
 173
 174 Called whenever a selection has been copied, but before the selection is
 175 requested from the server.  The selection text can be queried and changed
 176 by calling C<< $term->selection >>.
 177
 178 Returning a true value aborts selection grabbing. It will still be hilighted.
 179
 180 =item on_sel_extend $term
 181
 182 Called whenever the user tries to extend the selection (e.g. with a double
 183 click) and is either supposed to return false (normal operation), or
 184 should extend the selection itelf and return true to suppress the built-in
 185 processing.
 186
 187 See the F<selection> example extension.
 188
 189 =item on_view_change $term, $offset
 190
 191 Called whenever the view offset changes, i..e the user or program
 192 scrolls. Offset C<0> means display the normal terminal, positive values
 193 show this many lines of scrollback.
 194
 195 =item on_scroll_back $term, $lines, $saved
 196
 197 Called whenever lines scroll out of the terminal area into the scrollback
 198 buffer. C<$lines> is the number of lines scrolled out and may be larger
 199 than the scroll back buffer or the terminal.
 200
 201 It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
 202 $nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
 203 number of lines that will be in the scrollback buffer.
 204
 205 =item on_tty_activity $term *NYI*
 206
 207 Called whenever the program(s) running in the urxvt window send output.
 208
 209 =item on_osc_seq $term, $string
 210
 211 Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
 212 operating system command) is processed. Cursor position and other state
 213 information is up-to-date when this happens. For interoperability, the
 214 string should start with the extension name and a colon, to distinguish
 215 it from commands for other extensions, and this might be enforced in the
 216 future.
 217
 218 Be careful not ever to trust (in a security sense) the data you receive,
 219 as its source can not easily be controleld (e-mail content, messages from
 220 other users on the same system etc.).
 221
 222 =item on_add_lines $term, $string
 223
 224 Called whenever text is about to be output, with the text as argument. You
 225 can filter/change and output the text yourself by returning a true value
 226 and calling C<< $term->scr_add_lines >> yourself. Please note that this
 227 might be very slow, however, as your hook is called for B<all> text being
 228 output.
 229
 230 =item on_line_update $term, $row
 231
 232 Called whenever a line was updated or changed. Can be used to filter
 233 screen output (e.g. underline urls or other useless stuff). Only lines
 234 that are being shown will be filtered, and, due to performance reasons,
 235 not always immediately.
 236
 237 The row number is always the topmost row of the line if the line spans
 238 multiple rows.
 239
 240 Please note that, if you change the line, then the hook might get called
 241 later with the already-modified line (e.g. if unrelated parts change), so
 242 you cannot just toggle rendition bits, but only set them.
 243
 244 =item on_refresh_begin $term
 245
 246 Called just before the screen gets redrawn. Can be used for overlay
 247 or similar effects by modify terminal contents in refresh_begin, and
 248 restoring them in refresh_end. The built-in overlay and selection display
 249 code is run after this hook, and takes precedence.
 250
 251 =item on_refresh_end $term
 252
 253 Called just after the screen gets redrawn. See C<on_refresh_begin>.
 254
 255 =item on_keyboard_command $term, $string
 256
 257 Called whenever the user presses a key combination that has a
 258 C<perl:string> action bound to it (see description of the B<keysym>
 259 resource in the @@RXVT_NAME@@(1) manpage).
 260
 261 =item on_focus_in $term
 262
 263 Called whenever the window gets the keyboard focus, before rxvt-unicode
 264 does focus in processing.
 265
 266 =item on_focus_out $term
 267
 268 Called wheneever the window loses keyboard focus, before rxvt-unicode does
 269 focus out processing.
 270
 271 =item on_key_press $term, $event, $octets
 272
 273 =item on_key_release $term, $event
 274
 275 =item on_button_press $term, $event
 276
 277 =item on_button_release $term, $event
 278
 279 =item on_motion_notify $term, $event
 280
 281 =item on_map_notify $term, $event
 282
 283 =item on_unmap_notify $term, $event
 284
 285 Called whenever the corresponding X event is received for the terminal If
 286 the hook returns true, then the even will be ignored by rxvt-unicode.
 287
 288 The event is a hash with most values as named by Xlib (see the XEvent
 289 manpage), with the additional members C<row> and C<col>, which are the row
 290 and column under the mouse cursor.
 291
 292 C<on_key_press> additionally receives the string rxvt-unicode would
 293 output, if any, in locale-specific encoding.
 294
 295 subwindow.
 296
 297 =back
 298
 299 =head2 Variables in the C<urxvt> Package
 300
 301 =over 4
 302
 303 =item $urxvt::TERM
 304
 305 The current terminal. This variable stores the current C<urxvt::term>
 306 object, whenever a callback/hook is executing.
 307
 308 =back
 309
 310 =head2 Functions in the C<urxvt> Package
 311
 312 =over 4
 313
 314 =item $term = new urxvt [arg...]
 315
 316 Creates a new terminal, very similar as if you had started it with
 317 C<system $binfile, arg...>. Croaks (and probably outputs an error message)
 318 if the new instance couldn't be created.  Returns C<undef> if the new
 319 instance didn't initialise perl, and the terminal object otherwise. The
 320 C<init> and C<start> hooks will be called during the call.
 321
 322 =item urxvt::fatal $errormessage
 323
 324 Fatally aborts execution with the given error message. Avoid at all
 325 costs! The only time this is acceptable is when the terminal process
 326 starts up.
 327
 328 =item urxvt::warn $string
 329
 330 Calls C<rxvt_warn> with the given string which should not include a
 331 newline. The module also overwrites the C<warn> builtin with a function
 332 that calls this function.
 333
 334 Using this function has the advantage that its output ends up in the
 335 correct place, e.g. on stderr of the connecting urxvtc client.
 336
 337 =item $time = urxvt::NOW
 338
 339 Returns the "current time" (as per the event loop).
 340
 341 =item urxvt::CurrentTime
 342
 343 =item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
 344 Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
 345 Button4Mask, Button5Mask, AnyModifier
 346
 347 Various constants for use in X events.
 348
 349 =back
 350
 351 =head2 RENDITION
 352
 353 Rendition bitsets contain information about colour, font, font styles and
 354 similar information for each screen cell.
 355
 356 The following "macros" deal with changes in rendition sets. You should
 357 never just create a bitset, you should always modify an existing one,
 358 as they contain important information required for correct operation of
 359 rxvt-unicode.
 360
 361 =over 4
 362
 363 =item $rend = urxvt::DEFAULT_RSTYLE
 364
 365 Returns the default rendition, as used when the terminal is starting up or
 366 being reset. Useful as a base to start when creating renditions.
 367
 368 =item $rend = urxvt::OVERLAY_RSTYLE
 369
 370 Return the rendition mask used for overlays by default.
 371
 372 =item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
 373
 374 Return the bit that enabled bold, italic, blink, reverse-video and
 375 underline, respectively. To enable such a style, just logically OR it into
 376 the bitset.
 377
 378 =item $foreground = urxvt::GET_BASEFG $rend
 379
 380 =item $background = urxvt::GET_BASEBG $rend
 381
 382 Return the foreground/background colour index, respectively.
 383
 384 =item $rend = urxvt::SET_FGCOLOR ($rend, $new_colour)
 385
 386 =item $rend = urxvt::SET_BGCOLOR ($rend, $new_colour)
 387
 388 Replace the foreground/background colour in the rendition mask with the
 389 specified one.
 390
 391 =item $value = urxvt::GET_CUSTOM ($rend)
 392
 393 Return the "custom" value: Every rendition has 5 bits for use by
 394 extensions. They can be set and changed as you like and are initially
 395 zero.
 396
 397 =item $rend = urxvt::SET_CUSTOM ($rend, $new_value)
 398
 399 Change the custom value.
 400
 401 =back
 402
 403 =cut
 404
 405 package urxvt;
 406
 407 use utf8;
 408 use strict;
 409 use Scalar::Util ();
 410 use List::Util ();
 411
 412 our $TERM;
 413 our @HOOKNAME;
 414 our %OPTION;
 415 our $LIBDIR;
 416
 417 BEGIN {
 418    urxvt->bootstrap;
 419
 420    # overwrite perl's warn
 421    *CORE::GLOBAL::warn = sub {
 422       my $msg = join "", @_;
 423       $msg .= "\n"
 424          unless $msg =~ /\n$/;
 425       urxvt::warn ($msg);
 426    };
 427 }
 428
 429 my @hook_count;
 430 my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
 431
 432 sub verbose {
 433    my ($level, $msg) = @_;
 434    warn "$msg\n" if $level <= $verbosity;
 435 }
 436
 437 # find on_xxx subs in the package and register them
 438 # as hooks
 439 sub register_package($) {
 440    my ($pkg) = @_;
 441
 442    for my $htype (0.. $#HOOKNAME) {
 443       my $name = $HOOKNAME[$htype];
 444
 445       my $ref = $pkg->can ("on_" . lc $name)
 446          or next;
 447
 448       $TERM->{_hook}[$htype]{$pkg} = $ref;
 449       $hook_count[$htype]++
 450          or set_should_invoke $htype, 1;
 451    }
 452 }
 453
 454 my $extension_pkg = "extension0000";
 455 my %extension_pkg;
 456
 457 # load a single script into its own package, once only
 458 sub extension_package($) {
 459    my ($path) = @_;
 460
 461    $extension_pkg{$path} ||= do {
 462       my $pkg = "urxvt::" . ($extension_pkg++);
 463
 464       verbose 3, "loading extension '$path' into package '$pkg'";
 465
 466       open my $fh, "<:raw", $path
 467          or die "$path: $!";
 468
 469       my $source = "package $pkg; use strict; use utf8;\n"
 470                    . "use base urxvt::term::proxy::;\n"
 471                    . "#line 1 \"$path\"\n{\n"
 472                    . (do { local $/; <$fh> })
 473                    . "\n};\n1";
 474
 475       eval $source or die "$path: $@";
 476
 477       $pkg
 478    }
 479 }
 480
 481 our $retval; # return value for urxvt
 482
 483 # called by the rxvt core
 484 sub invoke {
 485    local $TERM = shift;
 486    my $htype = shift;
 487
 488    if ($htype == 0) { # INIT
 489       my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
 490
 491       my %want_ext;
 492
 493       for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
 494          if ($_ eq "default") {
 495             $want_ext{$_}++ for qw(selection option-popup);
 496          } elsif (/^-(.*)$/) {
 497             delete $want_ext{$1};
 498          } else {
 499             $want_ext{$_}++;
 500          }
 501       }
 502
 503       for my $ext (keys %want_ext) {
 504          my @files = grep -f $_, map "$_/$ext", @dirs;
 505
 506          if (@files) {
 507             register_package extension_package $files[0];
 508          } else {
 509             warn "perl extension '$ext' not found in perl library search path\n";
 510          }
 511       }
 512    }
 513
 514    $retval = undef;
 515
 516    if (my $cb = $TERM->{_hook}[$htype]) {
 517       verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
 518          if $verbosity >= 10;
 519
 520       keys %$cb;
 521
 522       while (my ($pkg, $cb) = each %$cb) {
 523          eval {
 524             $retval = $cb->(
 525                $TERM->{_pkg}{$pkg} ||= do {
 526                   my $proxy = bless { }, $pkg;
 527                   Scalar::Util::weaken ($proxy->{term} = $TERM);
 528                   $proxy
 529                },
 530                @_,
 531             ) and last;
 532          };
 533          warn $@ if $@;#d#
 534       }
 535    }
 536
 537    if ($htype == 1) { # DESTROY
 538       # remove hooks if unused
 539       if (my $hook = $TERM->{_hook}) {
 540          for my $htype (0..$#$hook) {
 541             $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
 542                or set_should_invoke $htype, 0;
 543          }
 544       }
 545
 546       # clear package objects
 547       %$_ = () for values %{ $TERM->{_pkg} };
 548
 549       # clear package
 550       %$TERM = ();
 551    }
 552
 553    $retval
 554 }
 555
 556 sub urxvt::term::proxy::AUTOLOAD {
 557    $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/
 558       or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable";
 559
 560    eval qq{
 561       sub $urxvt::term::proxy::AUTOLOAD {
 562          my \$proxy = shift;
 563          \$proxy->{term}->$1 (\@_)
 564       }
 565       1
 566    } or die "FATAL: unable to compile method forwarder: $@";
 567
 568    goto &$urxvt::term::proxy::AUTOLOAD;
 569 }
 570
 571 sub urxvt::destroy_hook::DESTROY {
 572    ${$_[0]}->();
 573 }
 574
 575 sub urxvt::destroy_hook(&) {
 576    bless \shift, urxvt::destroy_hook::
 577 }
 578
 579 =head2 The C<urxvt::term> Class
 580
 581 =over 4
 582
 583 =item $term->destroy
 584
 585 Destroy the terminal object (close the window, free resources etc.).
 586
 587 =item $isset = $term->option ($optval[, $set])
 588
 589 Returns true if the option specified by C<$optval> is enabled, and
 590 optionally change it. All option values are stored by name in the hash
 591 C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
 592
 593 Here is a a likely non-exhaustive list of option names, please see the
 594 source file F</src/optinc.h> to see the actual list:
 595
 596  borderLess console cursorBlink cursorUnderline hold iconic insecure
 597  intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
 598  pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating
 599  scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer
 600  secondaryScreen secondaryScroll skipBuiltinGlyphs transparent
 601  tripleclickwords utmpInhibit visualBell
 602
 603 =item $value = $term->resource ($name[, $newval])
 604
 605 Returns the current resource value associated with a given name and
 606 optionally sets a new value. Setting values is most useful in the C<init>
 607 hook. Unset resources are returned and accepted as C<undef>.
 608
 609 The new value must be properly encoded to a suitable character encoding
 610 before passing it to this method. Similarly, the returned value may need
 611 to be converted from the used encoding to text.
 612
 613 Resource names are as defined in F<src/rsinc.h>. Colours can be specified
 614 as resource names of the form C<< color+<index> >>, e.g. C<color+5>. (will
 615 likely change).
 616
 617 Please note that resource strings will currently only be freed when the
 618 terminal is destroyed, so changing options frequently will eat memory.
 619
 620 Here is a a likely non-exhaustive list of resource names, not all of which
 621 are supported in every build, please see the source file F</src/rsinc.h>
 622 to see the actual list:
 623
 624   answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
 625   borderLess color cursorBlink cursorUnderline cutchars delete_key
 626   display_name embed ext_bwidth fade font geometry hold iconName
 627   imFont imLocale inputMethod insecure int_bwidth intensityStyles
 628   italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
 629   mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2
 630   perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
 631   reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
 632   scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
 633   scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
 634   shade term_name title transparent transparent_all tripleclickwords
 635   utmpInhibit visualBell
 636
 637 =cut
 638
 639 sub urxvt::term::resource($$;$) {
 640    my ($self, $name) = (shift, shift);
 641    unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
 642    &urxvt::term::_resource
 643 }
 644
 645 =item $rend = $term->rstyle ([$new_rstyle])
 646
 647 Return and optionally change the current rendition. Text that is output by
 648 the terminal application will use this style.
 649
 650 =item ($row, $col) = $term->screen_cur ([$row, $col])
 651
 652 Return the current coordinates of the text cursor position and optionally
 653 set it (which is usually bad as applications don't expect that).
 654
 655 =item ($row, $col) = $term->selection_mark ([$row, $col])
 656
 657 =item ($row, $col) = $term->selection_beg ([$row, $col])
 658
 659 =item ($row, $col) = $term->selection_end ([$row, $col])
 660
 661 Return the current values of the selection mark, begin or end positions,
 662 and optionally set them to new values.
 663
 664 =item $success = $term->selection_grab ($eventtime)
 665
 666 Try to request the primary selection from the server (for example, as set
 667 by the next method).
 668
 669 =item $oldtext = $term->selection ([$newtext])
 670
 671 Return the current selection text and optionally replace it by C<$newtext>.
 672
 673 #=item $term->overlay ($x, $y, $text)
 674 #
 675 #Create a simple multi-line overlay box. See the next method for details.
 676 #
 677 #=cut
 678 #
 679 #sub urxvt::term::scr_overlay {
 680 #   my ($self, $x, $y, $text) = @_;
 681 #
 682 #   my @lines = split /\n/, $text;
 683 #
 684 #   my $w = 0;
 685 #   for (map $self->strwidth ($_), @lines) {
 686 #      $w = $_ if $w < $_;
 687 #   }
 688 #
 689 #   $self->scr_overlay_new ($x, $y, $w, scalar @lines);
 690 #   $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
 691 #}
 692
 693 =item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
 694
 695 Create a new (empty) overlay at the given position with the given
 696 width/height. C<$rstyle> defines the initial rendition style
 697 (default: C<OVERLAY_RSTYLE>).
 698
 699 If C<$border> is C<2> (default), then a decorative border will be put
 700 around the box.
 701
 702 If either C<$x> or C<$y> is negative, then this is counted from the
 703 right/bottom side, respectively.
 704
 705 This method returns an urxvt::overlay object. The overlay will be visible
 706 as long as the perl object is referenced.
 707
 708 The methods currently supported on C<urxvt::overlay> objects are:
 709
 710 =over 4
 711
 712 =item $overlay->set ($x, $y, $text, $rend)
 713
 714 Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts
 715 text in rxvt-unicode's special encoding and an array of rendition values
 716 at a specific position inside the overlay.
 717
 718 =item $overlay->hide
 719
 720 If visible, hide the overlay, but do not destroy it.
 721
 722 =item $overlay->show
 723
 724 If hidden, display the overlay again.
 725
 726 =back
 727
 728 =item $popup = $term->popup ($event)
 729
 730 Creates a new C<urxvt::popup> object that implements a popup menu. The
 731 C<$event> I<must> be the event causing the menu to pop up (a button event,
 732 currently).
 733
 734 =cut
 735
 736 sub urxvt::term::popup {
 737    my ($self, $event) = @_;
 738
 739    $self->grab ($event->{time}, 1)
 740       or return;
 741
 742    my $popup = bless {
 743       term  => $self,
 744       event => $event,
 745    }, urxvt::popup::;
 746
 747    Scalar::Util::weaken $popup->{term};
 748
 749    $self->{_destroy}{$popup} = urxvt::destroy_hook { $popup->{popup}->destroy };
 750    Scalar::Util::weaken $self->{_destroy}{$popup};
 751
 752    $popup
 753 }
 754
 755 =item $cellwidth = $term->strwidth ($string)
 756
 757 Returns the number of screen-cells this string would need. Correctly
 758 accounts for wide and combining characters.
 759
 760 =item $octets = $term->locale_encode ($string)
 761
 762 Convert the given text string into the corresponding locale encoding.
 763
 764 =item $string = $term->locale_decode ($octets)
 765
 766 Convert the given locale-encoded octets into a perl string.
 767
 768 =item $term->scr_add_lines ($string)
 769
 770 Write the given text string to the screen, as if output by the application
 771 running inside the terminal. It may not contain command sequences (escape
 772 codes), but is free to use line feeds, carriage returns and tabs. The
 773 string is a normal text string, not in locale-dependent encoding.
 774
 775 Normally its not a good idea to use this function, as programs might be
 776 confused by changes in cursor position or scrolling. Its useful inside a
 777 C<on_add_lines> hook, though.
 778
 779 =item $term->cmd_parse ($octets)
 780
 781 Similar to C<scr_add_lines>, but the argument must be in the
 782 locale-specific encoding of the terminal and can contain command sequences
 783 (escape codes) that will be interpreted.
 784
 785 =item $term->tt_write ($octets)
 786
 787 Write the octets given in C<$data> to the tty (i.e. as program input). To
 788 pass characters instead of octets, you should convert your strings first
 789 to the locale-specific encoding using C<< $term->locale_encode >>.
 790
 791 =item $windowid = $term->parent
 792
 793 Return the window id of the toplevel window.
 794
 795 =item $windowid = $term->vt
 796
 797 Return the window id of the terminal window.
 798
 799 =item $window_width = $term->width
 800
 801 =item $window_height = $term->height
 802
 803 =item $font_width = $term->fwidth
 804
 805 =item $font_height = $term->fheight
 806
 807 =item $font_ascent = $term->fbase
 808
 809 =item $terminal_rows = $term->nrow
 810
 811 =item $terminal_columns = $term->ncol
 812
 813 =item $has_focus = $term->focus
 814
 815 =item $is_mapped = $term->mapped
 816
 817 =item $max_scrollback = $term->saveLines
 818
 819 =item $nrow_plus_saveLines = $term->total_rows
 820
 821 =item $lines_in_scrollback = $term->nsaved
 822
 823 Return various integers describing terminal characteristics.
 824
 825 =item $modifiermask = $term->ModLevel3Mask
 826
 827 =item $modifiermask = $term->ModMetaMask
 828
 829 =item $modifiermask = $term->ModNumLockMask
 830
 831 Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
 832 AltGr), the meta key (often Alt) and the num lock key, if applicable.
 833
 834 =item $view_start = $term->view_start ([$newvalue])
 835
 836 Returns the negative row number of the topmost line. Minimum value is
 837 C<0>, which displays the normal terminal contents. Larger values scroll
 838 this many lines into the scrollback buffer.
 839
 840 =item $term->want_refresh
 841
 842 Requests a screen refresh. At the next opportunity, rxvt-unicode will
 843 compare the on-screen display with its stored representation. If they
 844 differ, it redraws the differences.
 845
 846 Used after changing terminal contents to display them.
 847
 848 =item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
 849
 850 Returns the text of the entire row with number C<$row_number>. Row C<0>
 851 is the topmost terminal line, row C<< $term->$ncol-1 >> is the bottommost
 852 terminal line. The scrollback buffer starts at line C<-1> and extends to
 853 line C<< -$term->nsaved >>. Nothing will be returned if a nonexistent line
 854 is requested.
 855
 856 If C<$new_text> is specified, it will replace characters in the current
 857 line, starting at column C<$start_col> (default C<0>), which is useful
 858 to replace only parts of a line. The font index in the rendition will
 859 automatically be updated.
 860
 861 C<$text> is in a special encoding: tabs and wide characters that use more
 862 than one cell when displayed are padded with urxvt::NOCHAR characters
 863 (C<chr 65535>). Characters with combining characters and other characters
 864 that do not fit into the normal tetx encoding will be replaced with
 865 characters in the private use area.
 866
 867 You have to obey this encoding when changing text. The advantage is
 868 that C<substr> and similar functions work on screen cells and not on
 869 characters.
 870
 871 The methods C<< $term->special_encode >> and C<< $term->special_decode >>
 872 can be used to convert normal strings into this encoding and vice versa.
 873
 874 =item $rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])
 875
 876 Like C<< $term->ROW_t >>, but returns an arrayref with rendition
 877 bitsets. Rendition bitsets contain information about colour, font, font
 878 styles and similar information. See also C<< $term->ROW_t >>.
 879
 880 When setting rendition, the font mask will be ignored.
 881
 882 See the section on RENDITION, above.
 883
 884 =item $length = $term->ROW_l ($row_number[, $new_length])
 885
 886 Returns the number of screen cells that are in use ("the line
 887 length"). Unlike the urxvt core, this returns C<< $term->ncol >> if the
 888 line is joined with the following one.
 889
 890 =item $bool = $term->is_longer ($row_number)
 891
 892 Returns true if the row is part of a multiple-row logical "line" (i.e.
 893 joined with the following row), which means all characters are in use
 894 and it is continued on the next row (and possibly a continuation of the
 895 previous row(s)).
 896
 897 =item $line = $term->line ($row_number)
 898
 899 Create and return a new C<urxvt::line> object that stores information
 900 about the logical line that row C<$row_number> is part of. It supports the
 901 following methods:
 902
 903 =over 4
 904
 905 =item $text = $line->t ([$new_text])
 906
 907 Returns or replaces the full text of the line, similar to C<ROW_t>
 908
 909 =item $rend = $line->r ([$new_rend])
 910
 911 Returns or replaces the full rendition array of the line, similar to C<ROW_r>
 912
 913 =item $length = $line->l
 914
 915 Returns the length of the line in cells, similar to C<ROW_l>.
 916
 917 =item $rownum = $line->beg
 918
 919 =item $rownum = $line->end
 920
 921 Return the row number of the first/last row of the line, respectively.
 922
 923 =item $offset = $line->offset_of ($row, $col)
 924
 925 Returns the character offset of the given row|col pair within the logical
 926 line.
 927
 928 =item ($row, $col) = $line->coord_of ($offset)
 929
 930 Translates a string offset into terminal coordinates again.
 931
 932 =back
 933
 934 =cut
 935
 936 sub urxvt::term::line {
 937    my ($self, $row) = @_;
 938
 939    my $maxrow = $self->nrow - 1;
 940
 941    my ($beg, $end) = ($row, $row);
 942
 943    --$beg while $self->ROW_is_longer ($beg - 1);
 944    ++$end while $self->ROW_is_longer ($end) && $end < $maxrow;
 945
 946    bless {
 947       term => $self,
 948       beg  => $beg,
 949       end  => $end,
 950       ncol => $self->ncol,
 951       len  => ($end - $beg) * $self->ncol + $self->ROW_l ($end),
 952    }, urxvt::line::
 953 }
 954
 955 sub urxvt::line::t {
 956    my ($self) = @_;
 957
 958    if (@_ > 1)
 959      {
 960        $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
 961           for $self->{beg} .. $self->{end};
 962      }
 963
 964    defined wantarray &&
 965       substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
 966              0, $self->{len}
 967 }
 968
 969 sub urxvt::line::r {
 970    my ($self) = @_;
 971
 972    if (@_ > 1)
 973      {
 974        $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
 975           for $self->{beg} .. $self->{end};
 976      }
 977
 978    if (defined wantarray) {
 979       my $rend = [
 980          map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
 981       ];
 982       $#$rend = $self->{len} - 1;
 983       return $rend;
 984    }
 985
 986    ()
 987 }
 988
 989 sub urxvt::line::beg { $_[0]{beg} }
 990 sub urxvt::line::end { $_[0]{end} }
 991 sub urxvt::line::l   { $_[0]{len} }
 992
 993 sub urxvt::line::offset_of {
 994    my ($self, $row, $col) = @_;
 995
 996    ($row - $self->{beg}) * $self->{ncol} + $col
 997 }
 998
 999 sub urxvt::line::coord_of {
1000    my ($self, $offset) = @_;
1001
1002    use integer;
1003
1004    (
1005       $offset / $self->{ncol} + $self->{beg},
1006       $offset % $self->{ncol}
1007    )
1008 }
1009
1010 =item ($row, $col) = $line->coord_of ($offset)
1011 =item $text = $term->special_encode $string
1012
1013 Converts a perl string into the special encoding used by rxvt-unicode,
1014 where one character corresponds to one screen cell. See
1015 C<< $term->ROW_t >> for details.
1016
1017 =item $string = $term->special_decode $text
1018
1019 Converts rxvt-unicodes text reprsentation into a perl string. See
1020 C<< $term->ROW_t >> for details.
1021
1022 =back
1023
1024 =head2 The C<urxvt::popup> Class
1025
1026 =over 4
1027
1028 =cut
1029
1030 package urxvt::popup;
1031
1032 sub add_item {
1033    my ($self, $item) = @_;
1034
1035    $item->{rend}{normal} = "\x1b[0;30;47m" unless exists $item->{rend}{normal};
1036    $item->{rend}{hover}  = "\x1b[0;30;46m" unless exists $item->{rend}{hover};
1037    $item->{rend}{active} = "\x1b[m"        unless exists $item->{rend}{active};
1038
1039    $item->{render} ||= sub { $_[0]{text} };
1040
1041    push @{ $self->{item} }, $item;
1042 }
1043
1044 sub add_separator {
1045    my ($self, $sep) = @_;
1046
1047    $sep ||= "═";
1048
1049    $self->add_item ({
1050       rend => { normal => "\x1b[0;30;47m", hover => "\x1b[0;30;47m", active => "\x1b[0;30;47m" },
1051       text => "",
1052       render => sub { $sep x $urxvt::TERM->ncol },
1053       activate => sub { },
1054    });
1055 }
1056
1057 sub add_title {
1058    my ($self, $title) = @_;
1059
1060    $self->add_item ({
1061       rend => { normal => "\x1b[38;5;11;44m", hover => "\x1b[38;5;11;44m", active => "\x1b[38;5;11;44m" },
1062       text => $title,
1063       activate => sub { },
1064    });
1065 }
1066
1067 sub add_button {
1068    my ($self, $text, $cb) = @_;
1069
1070    $self->add_item ({ type => "button", text => "[ $text ]", activate => $cb});
1071 }
1072
1073 sub add_toggle {
1074    my ($self, $text, $cb, $value) = @_;
1075
1076    my $item; $item = {
1077       type => "button",
1078       text => "  $text",
1079       value => $value,
1080       render => sub { ($item->{value} ? "* " : "  ") . $text },
1081       activate => sub { $cb->($item->{value} = !$item->{value}); },
1082    };
1083
1084    $self->add_item ($item);
1085 }
1086
1087 sub show {
1088    my ($self) = @_;
1089
1090    local $urxvt::popup::self = $self;
1091
1092    urxvt->new ("--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0,
1093                "--transient-for" => $self->{term}->parent,
1094                "-pe" => "urxvt-popup")
1095       or die "unable to create popup window\n";
1096 }
1097
1098 sub DESTROY {
1099    my ($self) = @_;
1100
1101    $self->{term}->ungrab;
1102 }
1103
1104 =head2 The C<urxvt::timer> Class
1105
1106 This class implements timer watchers/events. Time is represented as a
1107 fractional number of seconds since the epoch. Example:
1108
1109    $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
1110    $term->{timer} = urxvt::timer
1111                     ->new
1112                     ->interval (1)
1113                     ->cb (sub {
1114                        $term->{overlay}->set (0, 0,
1115                           sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
1116                     });
1117
1118 =over 4
1119
1120 =item $timer = new urxvt::timer
1121
1122 Create a new timer object in started state. It is scheduled to fire
1123 immediately.
1124
1125 =item $timer = $timer->cb (sub { my ($timer) = @_; ... })
1126
1127 Set the callback to be called when the timer triggers.
1128
1129 =item $tstamp = $timer->at
1130
1131 Return the time this watcher will fire next.
1132
1133 =item $timer = $timer->set ($tstamp)
1134
1135 Set the time the event is generated to $tstamp.
1136
1137 =item $timer = $timer->interval ($interval)
1138
1139 Normally (and when C<$interval> is C<0>), the timer will automatically
1140 stop after it has fired once. If C<$interval> is non-zero, then the timer
1141 is automatically rescheduled at the given intervals.
1142
1143 =item $timer = $timer->start
1144
1145 Start the timer.
1146
1147 =item $timer = $timer->start ($tstamp)
1148
1149 Set the event trigger time to C<$tstamp> and start the timer.
1150
1151 =item $timer = $timer->stop
1152
1153 Stop the timer.
1154
1155 =back
1156
1157 =head2 The C<urxvt::iow> Class
1158
1159 This class implements io watchers/events. Example:
1160
1161   $term->{socket} = ...
1162   $term->{iow} = urxvt::iow
1163                  ->new
1164                  ->fd (fileno $term->{socket})
1165                  ->events (1) # wait for read data
1166                  ->start
1167                  ->cb (sub {
1168                    my ($iow, $revents) = @_;
1169                    # $revents must be 1 here, no need to check
1170                    sysread $term->{socket}, my $buf, 8192
1171                       or end-of-file;
1172                  });
1173
1174
1175 =over 4
1176
1177 =item $iow = new urxvt::iow
1178
1179 Create a new io watcher object in stopped state.
1180
1181 =item $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
1182
1183 Set the callback to be called when io events are triggered. C<$reventmask>
1184 is a bitset as described in the C<events> method.
1185
1186 =item $iow = $iow->fd ($fd)
1187
1188 Set the filedescriptor (not handle) to watch.
1189
1190 =item $iow = $iow->events ($eventmask)
1191
1192 Set the event mask to watch. Bit #0 (value C<1>) enables watching for read
1193 data, Bit #1 (value C<2>) enables watching for write data.
1194
1195 =item $iow = $iow->start
1196
1197 Start watching for requested events on the given handle.
1198
1199 =item $iow = $iow->stop
1200
1201 Stop watching for events on the given filehandle.
1202
1203 =back
1204
1205 =head1 ENVIRONMENT
1206
1207 =head2 URXVT_PERL_VERBOSITY
1208
1209 This variable controls the verbosity level of the perl extension. Higher
1210 numbers indicate more verbose output.
1211
1212 =over 4
1213
1214 =item =0 - only fatal messages
1215
1216 =item =3 - script loading and management
1217
1218 =item =10 - all events received
1219
1220 =back
1221
1222 =head1 AUTHOR
1223
1224  Marc Lehmann <pcg@goof.com>
1225  http://software.schmorp.de/pkg/rxvt-unicode
1226
1227 =cut
1228
1229 1