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