--- rxvt-unicode/doc/rxvtperl.3.txt	2006/01/04 00:12:12	1.9
+++ rxvt-unicode/doc/rxvtperl.3.txt	2006/01/08 06:35:38	1.14
@@ -14,8 +14,8 @@
        rxvt --perl-lib $HOME -pe grab_test
 
 DESCRIPTION
-    Everytime a terminal object gets created, scripts specified via the
-    "perl" resource are loaded and associated with it.
+    Everytime a terminal object gets created, extension scripts specified
+    via the "perl" resource are loaded and associated with it.
 
     Scripts are compiled in a 'use strict' and 'use utf8' environment, and
     thus must be encoded as UTF-8.
@@ -31,7 +31,7 @@
 
       rxvt -pe <extensionname>
 
-    selection
+    selection (enabled by default)
         Intelligent selection. This extension tries to be more intelligent
         when the user extends selections (double-click). Right now, it tries
         to select urls and complete shell-quoted arguments, which is very
@@ -44,9 +44,22 @@
 
                URxvt.keysym.C-M-r: perl:selection:rot13
 
+    option-popup (enabled by default)
+        Binds a popup menu to Ctrl-Button3 that lets you toggle (some)
+        options at runtime.
+
     digital-clock
         Displays a digital clock using the built-in overlay.
 
+    mark-urls
+        Uses per-line display filtering ("on_line_update") to underline
+        urls.
+
+    block-graphics-to-ascii
+        A not very useful example of filtering all text output to the
+        terminal, by replacing all line-drawing characters (U+2500 ..
+        U+259F) by a similar-looking ascii character.
+
     example-refresh-hooks
         Displays a very simple digital clock in the upper right corner of
         the window. Illustrates overwriting the refresh callbacks to create
@@ -64,15 +77,34 @@
     the like inside the terminal object so they get destroyed as soon as the
     terminal is destroyed.
 
+    Argument names also often indicate the type of a parameter. Here are
+    some hints on what they mean:
+
+    $text
+        Rxvt-unicodes special way of encoding text, where one "unicode"
+        character always represents one screen cell. See row_t for a
+        discussion of this format.
+
+    $string
+        A perl text string, with an emphasis on *text*. It can store all
+        unicode characters and is to be distinguished with text encoded in a
+        specific encoding (often locale-specific) and binary data.
+
+    $octets
+        Either binary data or - more common - a text string encoded in a
+        locale-specific way.
+
   Hooks
-    The following subroutines can be declared in loaded scripts, and will be
-    called whenever the relevant event happens.
+    The following subroutines can be declared in extension files, and will
+    be called whenever the relevant event happens.
 
     The first argument passed to them is an object private to each terminal
     and extension package. You can call all "urxvt::term" methods on it, but
     its not a real "urxvt::term" object. Instead, the real "urxvt::term"
     object that is shared between all packages is stored in the "term"
-    member.
+    member. It is, however, blessed intot he package of the extension
+    script, so for all practical purposes you can treat an extension script
+    as a class.
 
     All of them must return a boolean value. If it is true, then the event
     counts as being *consumed*, and the invocation of other hooks is
@@ -83,7 +115,10 @@
 
     on_init $term
         Called after a new terminal object has been initialized, but before
-        windows are created or the command gets run.
+        windows are created or the command gets run. Most methods are unsafe
+        to call or deliver senseless data, as terminal size and other
+        characteristics have not yet been determined. You can safely query
+        and change resources, though.
 
     on_reset $term
         Called after the screen is "reset" for any reason, such as resizing
@@ -119,14 +154,6 @@
 
         See the selection example extension.
 
-    on_focus_in $term
-        Called whenever the window gets the keyboard focus, before urxvt
-        does focus in processing.
-
-    on_focus_out $term
-        Called wheneever the window loses keyboard focus, before urxvt does
-        focus out processing.
-
     on_view_change $term, $offset
         Called whenever the view offset changes, i..e the user or program
         scrolls. Offset 0 means display the normal terminal, positive values
@@ -157,6 +184,27 @@
         receive, as its source can not easily be controleld (e-mail content,
         messages from other users on the same system etc.).
 
+    on_add_lines $term, $string
+        Called whenever text is about to be output, with the text as
+        argument. You can filter/change and output the text yourself by
+        returning a true value and calling "$term->scr_add_lines" yourself.
+        Please note that this might be very slow, however, as your hook is
+        called for all text being output.
+
+    on_line_update $term, $row
+        Called whenever a line was updated or changed. Can be used to filter
+        screen output (e.g. underline urls or other useless stuff). Only
+        lines that are being shown will be filtered, and, due to performance
+        reasons, not always immediately.
+
+        The row number is always the topmost row of the line if the line
+        spans multiple rows.
+
+        Please note that, if you change the line, then the hook might get
+        called later with the already-modified line (e.g. if unrelated parts
+        change), so you cannot just toggle rendition bits, but only set
+        them.
+
     on_refresh_begin $term
         Called just before the screen gets redrawn. Can be used for overlay
         or similar effects by modify terminal contents in refresh_begin, and
@@ -171,12 +219,48 @@
         "perl:string" action bound to it (see description of the keysym
         resource in the rxvt(1) manpage).
 
+    on_focus_in $term
+        Called whenever the window gets the keyboard focus, before
+        rxvt-unicode does focus in processing.
+
+    on_focus_out $term
+        Called wheneever the window loses keyboard focus, before
+        rxvt-unicode does focus out processing.
+
+    on_key_press $term, $event, $octets
+    on_key_release $term, $event
+    on_button_press $term, $event
+    on_button_release $term, $event
+    on_motion_notify $term, $event
+    on_map_notify $term, $event
+    on_unmap_notify $term, $event
+        Called whenever the corresponding X event is received for the
+        terminal If the hook returns true, then the even will be ignored by
+        rxvt-unicode.
+
+        The event is a hash with most values as named by Xlib (see the
+        XEvent manpage), with the additional members "row" and "col", which
+        are the row and column under the mouse cursor.
+
+        "on_key_press" additionally receives the string rxvt-unicode would
+        output, if any, in locale-specific encoding.
+
+        subwindow.
+
   Variables in the "urxvt" Package
     $urxvt::TERM
-        The current terminal. Whenever a callback/Hook is bein executed,
-        this variable stores the current "urxvt::term" object.
+        The current terminal. This variable stores the current "urxvt::term"
+        object, whenever a callback/hook is executing.
 
   Functions in the "urxvt" Package
+    $term = new urxvt [arg...]
+        Creates a new terminal, very similar as if you had started it with
+        "system $binfile, arg...". Croaks (and probably outputs an error
+        message) if the new instance couldn't be created. Returns "undef" if
+        the new instance didn't initialise perl, and the terminal object
+        otherwise. The "init" and "start" hooks will be called during the
+        call.
+
     urxvt::fatal $errormessage
         Fatally aborts execution with the given error message. Avoid at all
         costs! The only time this is acceptable is when the terminal process
@@ -193,6 +277,12 @@
     $time = urxvt::NOW
         Returns the "current time" (as per the event loop).
 
+    urxvt::CurrentTime
+    urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask,
+    Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask,
+    Button5Mask, AnyModifier
+        Various constants for use in X calls and event processing.
+
   RENDITION
     Rendition bitsets contain information about colour, font, font styles
     and similar information for each screen cell.
@@ -232,7 +322,33 @@
     $rend = urxvt::SET_CUSTOM ($rend, $new_value)
         Change the custom value.
 
+  The "urxvt::anyevent" Class
+    The sole purpose of this class is to deliver an interface to the
+    "AnyEvent" module - any module using it will work inside urxvt without
+    further work. The only exception is that you cannot wait on condition
+    variables, but non-blocking condvar use is ok. What this means is that
+    you cannot use blocking APIs, but the non-blocking variant should work.
+
   The "urxvt::term" Class
+    $term->destroy
+        Destroy the terminal object (close the window, free resources etc.).
+
+    $isset = $term->option ($optval[, $set])
+        Returns true if the option specified by $optval is enabled, and
+        optionally change it. All option values are stored by name in the
+        hash %urxvt::OPTION. Options not enabled in this binary are not in
+        the hash.
+
+        Here is a a likely non-exhaustive list of option names, please see
+        the source file /src/optinc.h to see the actual list:
+
+         borderLess console cursorBlink cursorUnderline hold iconic insecure
+         intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
+         pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating
+         scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer
+         secondaryScreen secondaryScroll skipBuiltinGlyphs transparent
+         tripleclickwords utmpInhibit visualBell
+
     $value = $term->resource ($name[, $newval])
         Returns the current resource value associated with a given name and
         optionally sets a new value. Setting values is most useful in the
@@ -251,15 +367,15 @@
         memory.
 
         Here is a a likely non-exhaustive list of resource names, not all of
-        which are supported in every build, please see the source to see the
-        actual list:
+        which are supported in every build, please see the source file
+        /src/rsinc.h to see the actual list:
 
           answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
           borderLess color cursorBlink cursorUnderline cutchars delete_key
           display_name embed ext_bwidth fade font geometry hold iconName
           imFont imLocale inputMethod insecure int_bwidth intensityStyles
           italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
-          mouseWheelScrollPage name pastableTabs path perl_eval perl_ext
+          mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2
           perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
           reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
           scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
@@ -267,6 +383,15 @@
           shade term_name title transparent transparent_all tripleclickwords
           utmpInhibit visualBell
 
+    $rend = $term->rstyle ([$new_rstyle])
+        Return and optionally change the current rendition. Text that is
+        output by the terminal application will use this style.
+
+    ($row, $col) = $term->screen_cur ([$row, $col])
+        Return the current coordinates of the text cursor position and
+        optionally set it (which is usually bad as applications don't expect
+        that).
+
     ($row, $col) = $term->selection_mark ([$row, $col])
     ($row, $col) = $term->selection_beg ([$row, $col])
     ($row, $col) = $term->selection_end ([$row, $col])
@@ -282,20 +407,12 @@
         $newtext.
 
         #=item $term->overlay ($x, $y, $text) # #Create a simple multi-line
-        overlay box. See the next method for details. # #=cut
-
-        sub urxvt::term::scr_overlay { die; my ($self, $x, $y, $text) = @_;
-
-           my @lines = split /\n/, $text;
-
-           my $w = 0;
-           for (map $self->strwidth ($_), @lines) {
-              $w = $_ if $w < $_;
-           }
-
-           $self->scr_overlay_new ($x, $y, $w, scalar @lines);
-           $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
-        }
+        overlay box. See the next method for details. # #=cut # #sub
+        urxvt::term::scr_overlay { # my ($self, $x, $y, $text) = @_; # # my
+        @lines = split /\n/, $text; # # my $w = 0; # for (map
+        $self->strwidth ($_), @lines) { # $w = $_ if $w < $_; # } # #
+        $self->scr_overlay_new ($x, $y, $w, scalar @lines); #
+        $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; #}
 
     $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
         Create a new (empty) overlay at the given position with the given
@@ -324,30 +441,70 @@
         $overlay->show
             If hidden, display the overlay again.
 
-    $cellwidth = $term->strwidth $string
+    $popup = $term->popup ($event)
+        Creates a new "urxvt::popup" object that implements a popup menu.
+        The $event *must* be the event causing the menu to pop up (a button
+        event, currently).
+
+    $cellwidth = $term->strwidth ($string)
         Returns the number of screen-cells this string would need. Correctly
         accounts for wide and combining characters.
 
-    $octets = $term->locale_encode $string
+    $octets = $term->locale_encode ($string)
         Convert the given text string into the corresponding locale
         encoding.
 
-    $string = $term->locale_decode $octets
+    $string = $term->locale_decode ($octets)
         Convert the given locale-encoded octets into a perl string.
 
+    $term->scr_add_lines ($string)
+        Write the given text string to the screen, as if output by the
+        application running inside the terminal. It may not contain command
+        sequences (escape codes), but is free to use line feeds, carriage
+        returns and tabs. The string is a normal text string, not in
+        locale-dependent encoding.
+
+        Normally its not a good idea to use this function, as programs might
+        be confused by changes in cursor position or scrolling. Its useful
+        inside a "on_add_lines" hook, though.
+
+    $term->cmd_parse ($octets)
+        Similar to "scr_add_lines", but the argument must be in the
+        locale-specific encoding of the terminal and can contain command
+        sequences (escape codes) that will be interpreted.
+
     $term->tt_write ($octets)
         Write the octets given in $data to the tty (i.e. as program input).
         To pass characters instead of octets, you should convert your
         strings first to the locale-specific encoding using
         "$term->locale_encode".
 
-    $nrow = $term->nrow
-    $ncol = $term->ncol
-        Return the number of rows/columns of the terminal window (i.e. as
-        specified by "-geometry", excluding any scrollback).
+    $windowid = $term->parent
+        Return the window id of the toplevel window.
+
+    $windowid = $term->vt
+        Return the window id of the terminal window.
 
-    $nsaved = $term->nsaved
-        Returns the number of lines in the scrollback buffer.
+    $window_width = $term->width
+    $window_height = $term->height
+    $font_width = $term->fwidth
+    $font_height = $term->fheight
+    $font_ascent = $term->fbase
+    $terminal_rows = $term->nrow
+    $terminal_columns = $term->ncol
+    $has_focus = $term->focus
+    $is_mapped = $term->mapped
+    $max_scrollback = $term->saveLines
+    $nrow_plus_saveLines = $term->total_rows
+    $lines_in_scrollback = $term->nsaved
+        Return various integers describing terminal characteristics.
+
+    $modifiermask = $term->ModLevel3Mask
+    $modifiermask = $term->ModMetaMask
+    $modifiermask = $term->ModNumLockMask
+        Return the modifier masks corresponding to the "ISO Level 3 Shift"
+        (often AltGr), the meta key (often Alt) and the num lock key, if
+        applicable.
 
     $view_start = $term->view_start ([$newvalue])
         Returns the negative row number of the topmost line. Minimum value
@@ -411,11 +568,13 @@
         about the logical line that row $row_number is part of. It supports
         the following methods:
 
-        $text = $line->t
-            Returns the full text of the line, similar to "ROW_t"
-
-        $rend = $line->r
-            Returns the full rendition array of the line, similar to "ROW_r"
+        $text = $line->t ([$new_text])
+            Returns or replaces the full text of the line, similar to
+            "ROW_t"
+
+        $rend = $line->r ([$new_rend])
+            Returns or replaces the full rendition array of the line,
+            similar to "ROW_r"
 
         $length = $line->l
             Returns the length of the line in cells, similar to "ROW_l".
@@ -442,92 +601,93 @@
         Converts rxvt-unicodes text reprsentation into a perl string. See
         "$term->ROW_t" for details.
 
+  The "urxvt::popup" Class
   The "urxvt::timer" Class
-    This class implements timer watchers/events. Time is represented as a
-    fractional number of seconds since the epoch. Example:
+        This class implements timer watchers/events. Time is represented as
+        a fractional number of seconds since the epoch. Example:
 
-       $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
-       $term->{timer} = urxvt::timer
-                        ->new
-                        ->interval (1)
-                        ->cb (sub {
-                           $term->{overlay}->set (0, 0,
-                              sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
-                        });                                                                                                                                      
-
-    $timer = new urxvt::timer
-        Create a new timer object in started state. It is scheduled to fire
-        immediately.
-
-    $timer = $timer->cb (sub { my ($timer) = @_; ... })
-        Set the callback to be called when the timer triggers.
-
-    $tstamp = $timer->at
-        Return the time this watcher will fire next.
-
-    $timer = $timer->set ($tstamp)
-        Set the time the event is generated to $tstamp.
-
-    $timer = $timer->interval ($interval)
-        Normally (and when $interval is 0), the timer will automatically
-        stop after it has fired once. If $interval is non-zero, then the
-        timer is automatically rescheduled at the given intervals.
+           $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
+           $term->{timer} = urxvt::timer
+                            ->new
+                            ->interval (1)
+                            ->cb (sub {
+                               $term->{overlay}->set (0, 0,
+                                  sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
+                            });                                                                                                                                      
+
+        $timer = new urxvt::timer
+            Create a new timer object in started state. It is scheduled to
+            fire immediately.
+
+        $timer = $timer->cb (sub { my ($timer) = @_; ... })
+            Set the callback to be called when the timer triggers.
+
+        $tstamp = $timer->at
+            Return the time this watcher will fire next.
+
+        $timer = $timer->set ($tstamp)
+            Set the time the event is generated to $tstamp.
+
+        $timer = $timer->interval ($interval)
+            Normally (and when $interval is 0), the timer will automatically
+            stop after it has fired once. If $interval is non-zero, then the
+            timer is automatically rescheduled at the given intervals.
 
-    $timer = $timer->start
-        Start the timer.
+        $timer = $timer->start
+            Start the timer.
 
-    $timer = $timer->start ($tstamp)
-        Set the event trigger time to $tstamp and start the timer.
+        $timer = $timer->start ($tstamp)
+            Set the event trigger time to $tstamp and start the timer.
 
-    $timer = $timer->stop
-        Stop the timer.
+        $timer = $timer->stop
+            Stop the timer.
 
   The "urxvt::iow" Class
-    This class implements io watchers/events. Example:
+        This class implements io watchers/events. Example:
 
-      $term->{socket} = ...
-      $term->{iow} = urxvt::iow
-                     ->new
-                     ->fd (fileno $term->{socket})
-                     ->events (1) # wait for read data
-                     ->start
-                     ->cb (sub {
-                       my ($iow, $revents) = @_;
-                       # $revents must be 1 here, no need to check
-                       sysread $term->{socket}, my $buf, 8192
-                          or end-of-file;
-                     });
-
-    $iow = new urxvt::iow
-        Create a new io watcher object in stopped state.
-
-    $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
-        Set the callback to be called when io events are triggered.
-        $reventmask is a bitset as described in the "events" method.
-
-    $iow = $iow->fd ($fd)
-        Set the filedescriptor (not handle) to watch.
-
-    $iow = $iow->events ($eventmask)
-        Set the event mask to watch. Bit #0 (value 1) enables watching for
-        read data, Bit #1 (value 2) enables watching for write data.
+          $term->{socket} = ...
+          $term->{iow} = urxvt::iow
+                         ->new
+                         ->fd (fileno $term->{socket})
+                         ->events (1) # wait for read data
+                         ->start
+                         ->cb (sub {
+                           my ($iow, $revents) = @_;
+                           # $revents must be 1 here, no need to check
+                           sysread $term->{socket}, my $buf, 8192
+                              or end-of-file;
+                         });
+
+        $iow = new urxvt::iow
+            Create a new io watcher object in stopped state.
+
+        $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
+            Set the callback to be called when io events are triggered.
+            $reventmask is a bitset as described in the "events" method.
+
+        $iow = $iow->fd ($fd)
+            Set the filedescriptor (not handle) to watch.
+
+        $iow = $iow->events ($eventmask)
+            Set the event mask to watch. Bit #0 (value 1) enables watching
+            for read data, Bit #1 (value 2) enables watching for write data.
 
-    $iow = $iow->start
-        Start watching for requested events on the given handle.
+        $iow = $iow->start
+            Start watching for requested events on the given handle.
 
-    $iow = $iow->stop
-        Stop watching for events on the given filehandle.
+        $iow = $iow->stop
+            Stop watching for events on the given filehandle.
 
 ENVIRONMENT
   URXVT_PERL_VERBOSITY
-    This variable controls the verbosity level of the perl extension. Higher
-    numbers indicate more verbose output.
+        This variable controls the verbosity level of the perl extension.
+        Higher numbers indicate more verbose output.
 
-    =0 - only fatal messages
-    =3 - script loading and management
-    =10 - all events received
+        =0 - only fatal messages
+        =3 - script loading and management
+        =10 - all events received
 
 AUTHOR
-     Marc Lehmann <pcg@goof.com>
-     http://software.schmorp.de/pkg/rxvt-unicode
+         Marc Lehmann <pcg@goof.com>
+         http://software.schmorp.de/pkg/rxvt-unicode