--- rxvt-unicode/src/urxvt.pm	2006/01/04 19:39:46	1.31
+++ rxvt-unicode/src/urxvt.pm	2006/01/06 05:28:55	1.39
@@ -62,12 +62,23 @@
 
 Displays a digital clock using the built-in overlay.
 
+=item mark-urls
+
+Uses per-line filtering (C<on_line_update>) to underline urls.
+
 =item example-refresh-hooks
 
 Displays a very simple digital clock in the upper right corner of the
 window. Illustrates overwriting the refresh callbacks to create your own
 overlays or changes.
 
+=item example-filter-input
+
+A not very useful example of filtering all text output to the terminal, by
+underlining all urls that matches a certain regex (i.e. some urls :). It
+is not very useful because urls that are output in multiple steps (e.g.
+when typing them) do not get marked.
+
 =back
 
 =head2 General API Considerations
@@ -83,6 +94,29 @@
 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:
+
+=over 4
+
+=item $text
+
+Rxvt-unicodes special way of encoding text, where one "unicode" character
+always represents one screen cell. See L<row_t> for a discussion of this format.
+
+=item $string
+
+A perl text string, with an emphasis on I<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.
+
+=item $octets
+
+Either binary data or - more common - a text string encoded in a
+locale-specific way.
+
+=back
+
 =head2 Hooks
 
 The following subroutines can be declared in loaded scripts, and will be
@@ -105,7 +139,10 @@
 =item 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.
 
 =item on_reset $term
 
@@ -187,6 +224,28 @@
 as its source can not easily be controleld (e-mail content, messages from
 other users on the same system etc.).
 
+=item 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 C<< $term->scr_add_lines >> yourself. Please note that this
+might be very slow, however, as your hook is called for B<all> text being
+output.
+
+=item 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.
+
 =item on_refresh_begin $term
 
 Called just before the screen gets redrawn. Can be used for overlay
@@ -204,6 +263,28 @@
 C<perl:string> action bound to it (see description of the B<keysym>
 resource in the @@RXVT_NAME@@(1) manpage).
 
+=item on_key_press $term, $event, $octets
+
+=item on_key_release $term, $event
+
+=item on_button_press $term, $event
+
+=item on_button_release $term, $event
+
+=item on_motion_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 C<row> and C<col>, which are the row
+and column under the mouse cursor.
+
+C<on_key_press> additionally receives the string rxvt-unicode would
+output, if any, in locale-specific encoding.
+
+subwindow.
+
 =back
 
 =head2 Variables in the C<urxvt> Package
@@ -221,6 +302,14 @@
 
 =over 4
 
+=item $term = new urxvt [arg...]
+
+Creates a new terminal, very similar as if you had started it with
+C<system $binfile, arg...>. Croaks (and probably outputs an error message)
+if the new instance couldn't be created.  Returns C<undef> if the new
+instance didn't initialise perl, and the terminal object otherwise. The
+C<init> and C<start> hooks will be called during the call.
+
 =item urxvt::fatal $errormessage
 
 Fatally aborts execution with the given error message. Avoid at all
@@ -447,6 +536,10 @@
 
 =over 4
 
+=item $term->destroy
+
+Destroy the terminal object (close the window, free resources etc.).
+
 =item $value = $term->resource ($name[, $newval])
 
 Returns the current resource value associated with a given name and
@@ -489,6 +582,16 @@
    goto &urxvt::term::_resource;
 }
 
+=item $rend = $term->rstyle ([$new_rstyle])
+
+Return and optionally change the current rendition. Text that is output by
+the terminal application will use this style.
+
+=item ($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).
+
 =item ($row, $col) = $term->selection_mark ([$row, $col])
 
 =item ($row, $col) = $term->selection_beg ([$row, $col])
@@ -512,21 +615,20 @@
 #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;
-}
+#
+#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;
+#}
 
 =item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
 
@@ -576,22 +678,54 @@
 
 Convert the given locale-encoded octets into a perl string.
 
+=item $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
+C<on_add_lines> hook, though.
+
+=item $term->cmd_parse ($octets)
+
+Similar to C<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.
+
 =item $term->tt_write ($octets)
 
 Write the octets given in C<$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 C<< $term->locale_encode >>.
 
-=item $nrow = $term->nrow
+=item $window_width = $term->width
+
+=item $window_height = $term->height
+
+=item $font_width = $term->fwidth
+
+=item $font_height = $term->fheight
+
+=item $font_ascent = $term->fbase
 
-=item $ncol = $term->ncol
+=item $terminal_rows = $term->nrow
 
-Return the number of rows/columns of the terminal window (i.e. as
-specified by C<-geometry>, excluding any scrollback).
+=item $terminal_columns = $term->ncol
 
-=item $nsaved = $term->nsaved
+=item $has_focus = $term->focus
 
-Returns the number of lines in the scrollback buffer.
+=item $is_mapped = $term->mapped
+
+=item $max_scrollback = $term->saveLines
+
+=item $nrow_plus_saveLines = $term->total_rows
+
+=item $lines_in_scrollback = $term->nsaved
+
+Return various integers describing terminal characteristics.
 
 =item $view_start = $term->view_start ([$newvalue])
 
@@ -664,13 +798,13 @@
 
 =over 4
 
-=item $text = $line->t
+=item $text = $line->t ([$new_text])
 
-Returns the full text of the line, similar to C<ROW_t>
+Returns or replaces the full text of the line, similar to C<ROW_t>
 
-=item $rend = $line->r
+=item $rend = $line->r ([$new_rend])
 
-Returns the full rendition array of the line, similar to C<ROW_r>
+Returns or replaces the full rendition array of the line, similar to C<ROW_r>
 
 =item $length = $line->l
 
@@ -709,6 +843,7 @@
       term => $self,
       beg  => $beg,
       end  => $end,
+      ncol => $self->ncol,
       len  => ($end - $beg) * $self->ncol + $self->ROW_l ($end),
    }, urxvt::line::
 }
@@ -716,18 +851,35 @@
 sub urxvt::line::t {
    my ($self) = @_;
 
-   substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
-          0, $self->{len}
+   if (@_ > 1)
+     {
+       $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
+          for $self->{beg} .. $self->{end};
+     }
+
+   defined wantarray &&
+      substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
+             0, $self->{len}
 }
 
 sub urxvt::line::r {
    my ($self) = @_;
 
-   my $rend = [
-      map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
-   ];
-   $#$rend = $self->{len} - 1;
-   $rend
+   if (@_ > 1)
+     {
+       $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
+          for $self->{beg} .. $self->{end};
+     }
+
+   if (defined wantarray) {
+      my $rend = [
+         map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
+      ];
+      $#$rend = $self->{len} - 1;
+      return $rend;
+   }
+
+   ()
 }
 
 sub urxvt::line::beg { $_[0]{beg} }
@@ -737,7 +889,7 @@
 sub urxvt::line::offset_of {
    my ($self, $row, $col) = @_;
 
-   ($row - $self->{beg}) * $self->{term}->ncol + $col
+   ($row - $self->{beg}) * $self->{ncol} + $col
 }
 
 sub urxvt::line::coord_of {
@@ -746,8 +898,8 @@
    use integer;
 
    (
-      $offset / $self->{term}->ncol + $self->{beg},
-      $offset % $self->{term}->ncol
+      $offset / $self->{ncol} + $self->{beg},
+      $offset % $self->{ncol}
    )
 }