--- rxvt-unicode/src/urxvt.pm	2006/01/03 00:06:57	1.13
+++ rxvt-unicode/src/urxvt.pm	2006/01/03 19:10:54	1.22
@@ -1,3 +1,5 @@
+=encoding utf8
+
 =head1 NAME
 
 @@RXVT_NAME@@perl - rxvt-unicode's embedded perl interpreter
@@ -24,7 +26,47 @@
 thus must be encoded as UTF-8.
 
 Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where
-scripts will be shared (But not enabled) for all terminals.
+scripts will be shared (but not enabled) for all terminals.
+
+=head2 Prepackaged Extensions
+
+This section describes the extensiosn delivered with this version. You can
+find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>.
+
+You can activate them like this:
+
+  @@RXVT_NAME@@ -pe <extensionname>
+
+=over 4
+
+=item selection
+
+Intelligent selection. This etxension tries to be more intelligent when the user
+extends selections (double-click).
+
+It also offers the following bindable event:
+
+=over 4
+
+=item rot13
+
+Rot-13 the selection when activated. Used via keyboard trigger:
+
+   URxvt.keysym.C-M-r: perl:selection:rot13
+
+=back
+
+=item digital-clock
+
+Displays a digital clock using the built-in overlay.
+
+=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.
+
+=back
 
 =head2 General API Considerations
 
@@ -85,6 +127,15 @@
 
 Returning a true value aborts selection grabbing. It will still be hilighted.
 
+=item on_sel_extend $term
+
+Called whenever the user tries to extend the selection (e.g. with a double
+click) and is either supposed to return false (normal operation), or
+should extend the selection itelf and return true to suppress the built-in
+processing.
+
+See the F<selection> example extension.
+
 =item on_focus_in $term
 
 Called whenever the window gets the keyboard focus, before urxvt does
@@ -157,6 +208,60 @@
 
 Returns the "current time" (as per the event loop).
 
+=back
+
+=head2 RENDITION
+
+Rendition bitsets contain information about colour, font, font styles and
+similar information for each screen cell.
+
+The following "macros" deal with changes in rendition sets. You should
+never just create a bitset, you should always modify an existing one,
+as they contain important information required for correct operation of
+rxvt-unicode.
+
+=over 4
+
+=item $rend = urxvt::DEFAULT_RSTYLE
+
+Returns the default rendition, as used when the terminal is starting up or
+being reset. Useful as a base to start when creating renditions.
+
+=item $rend = urxvt::OVERLAY_RSTYLE
+
+Return the rendition mask used for overlays by default.
+
+=item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
+
+Return the bit that enabled bold, italic, blink, reverse-video and
+underline, respectively. To enable such a style, just logically OR it into
+the bitset.
+
+=item $foreground = urxvt::GET_BASEFG $rend
+
+=item $background = urxvt::GET_BASEBG $rend
+
+Return the foreground/background colour index, respectively.
+
+=item $rend = urxvt::SET_FGCOLOR ($rend, $new_colour)
+
+=item $rend = urxvt::SET_BGCOLOR ($rend, $new_colour)
+
+Replace the foreground/background colour in the rendition mask with the
+specified one.
+
+=item $value = urxvt::GET_CUSTOM ($rend)
+
+Return the "custom" value: Every rendition has 5 bits for use by
+extensions. They can be set and changed as you like and are initially
+zero.
+
+=item $rend = urxvt::SET_CUSTOM ($rend, $new_value)
+
+Change the custom value.
+
+=back
+
 =cut
 
 package urxvt;
@@ -270,8 +375,6 @@
    0
 }
 
-=back
-
 =head2 The C<urxvt::term> Class
 
 =over 4
@@ -336,13 +439,14 @@
 
 Return the current selection text and optionally replace it by C<$newtext>.
 
-=item $term->scr_overlay ($x, $y, $text)
-
-Create a simple multi-line overlay box. See the next method for details.
-
-=cut
+#=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;
@@ -356,25 +460,40 @@
    $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
 }
 
-=item $term->scr_overlay_new ($x, $y, $width, $height)
+=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
 
 Create a new (empty) overlay at the given position with the given
-width/height. A border will be put around the box. If either C<$x> or
-C<$y> is negative, then this is counted from the right/bottom side,
-respectively.
+width/height. C<$rstyle> defines the initial rendition style
+(default: C<OVERLAY_RSTYLE>).
+
+If C<$border> is C<2> (default), then a decorative border will be put
+around the box.
+
+If either C<$x> or C<$y> is negative, then this is counted from the
+right/bottom side, respectively.
+
+This method returns an urxvt::overlay object. The overlay will be visible
+as long as the perl object is referenced.
 
-=item $term->scr_overlay_off
+The methods currently supported on C<urxvt::overlay> objects are:
 
-Switch the overlay off again.
+=over 4
+
+=item $overlay->set ($x, $y, $text, $rend)
+
+Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts
+text in rxvt-unicode's special encoding and an array of rendition values
+at a specific position inside the overlay.
 
-=item $term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE)
+=item $overlay->hide
 
-Put a single character (specified numerically) at the given overlay
-position.
+If visible, hide the overlay, but do not destroy it.
 
-=item $term->scr_overlay_set ($x, $y, $text)
+=item $overlay->show
 
-Write a string at the given position into the overlay.
+If hidden, display the overlay again.
+
+=back
 
 =item $cellwidth = $term->strwidth $string
 
@@ -412,6 +531,14 @@
 C<0>, which displays the normal terminal contents. Larger values scroll
 this many lines into the scrollback buffer.
 
+=item $term->want_refresh
+
+Requests a screen refresh. At the next opportunity, rxvt-unicode will
+compare the on-screen display with its stored representation. If they
+differ, it redraws the differences.
+
+Used after changing terminal contents to display them.
+
 =item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
 
 Returns the text of the entire row with number C<$row_number>. Row C<0>
@@ -421,7 +548,7 @@
 
 If C<$new_text> is specified, it will replace characters in the current
 line, starting at column C<$start_col> (default C<0>), which is useful
-to replace only parts of a line. The font iindex in the rendition will
+to replace only parts of a line. The font index in the rendition will
 automatically be updated.
 
 C<$text> is in a special encoding: tabs and wide characters that use more
@@ -445,7 +572,7 @@
 
 When setting rendition, the font mask will be ignored.
 
-See the section on RENDITION, below.
+See the section on RENDITION, above.
 
 =item $length = $term->ROW_l ($row_number[, $new_length])
 
@@ -466,49 +593,26 @@
 
 =back
 
-=head2 RENDITION
-
-Rendition bitsets contain information about colour, font, font styles and
-similar information for each screen cell.
-
-The following "macros" deal with changes in rendition sets. You should
-never just create a bitset, you should always modify an existing one,
-as they contain important information required for correct operation of
-rxvt-unicode.
-
-=over 4
-
-=item $rend = urxvt::DEFAULT_RSTYLE
-
-Returns the default rendition, as used when the terminal is starting up or
-being reset. Useful as a base
-
-=back
-
-=cut
-
 =head2 The C<urxvt::timer> Class
 
 This class implements timer watchers/events. Time is represented as a
 fractional number of seconds since the epoch. Example:
 
-   # create a digital clock display in upper right corner
+   $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
    $term->{timer} = urxvt::timer
                     ->new
-                    ->start (urxvt::NOW)
+                    ->interval (1)
                     ->cb (sub {
-                       my ($timer) = @_;
-                       my $time = $timer->at;
-                       $timer->start ($time + 1);
-                       $self->scr_overlay (-1, 0, 
-                          POSIX::strftime "%H:%M:%S", localtime $time);
-                    });
+                       $term->{overlay}->set (0, 0,
+                          sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
+                    });                                                                                                                                      
 
 =over 4
 
 =item $timer = new urxvt::timer
 
-Create a new timer object in stopped state.
+Create a new timer object in started state. It is scheduled to fire
+immediately.
 
 =item $timer = $timer->cb (sub { my ($timer) = @_; ... })
 
@@ -522,6 +626,12 @@
 
 Set the time the event is generated to $tstamp.
 
+=item $timer = $timer->interval ($interval)
+
+Normally (and when C<$interval> is C<0>), the timer will automatically
+stop after it has fired once. If C<$interval> is non-zero, then the timer
+is automatically rescheduled at the given intervals.
+
 =item $timer = $timer->start
 
 Start the timer.