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