--- rxvt-unicode/src/urxvt.pm	2006/01/03 04:18:47	1.20
+++ rxvt-unicode/src/urxvt.pm	2006/01/03 19:42:53	1.23
@@ -41,7 +41,10 @@
 
 =item selection
 
-Miscellaneous selection modifications.
+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
 
@@ -70,7 +73,7 @@
 All objects (such as terminals, time watchers etc.) are typical
 reference-to-hash objects. The hash can be used to store anything you
 like. All members starting with an underscore (such as C<_ptr> or
-C<_hook>) are reserved for internal uses and must not be accessed or
+C<_hook>) are reserved for internal uses and B<MUST NOT> be accessed or
 modified).
 
 When objects are destroyed on the C++ side, the perl object hashes are
@@ -80,8 +83,14 @@
 
 =head2 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 loaded scripts, 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 C<urxvt::term> methods on it, but
+its not a real C<urxvt::term> object. Instead, the real C<urxvt::term>
+object that is shared between all packages is stored in the C<term>
+member.
 
 All of them must return a boolean value. If it is true, then the event
 counts as being I<consumed>, and the invocation of other hooks is skipped,
@@ -124,6 +133,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
@@ -173,6 +191,17 @@
 
 =back
 
+=head2 Variables in the C<urxvt> Package
+
+=over 4
+
+=item $urxvt::TERM
+
+The current terminal. Whenever a callback/Hook is bein executed, this
+variable stores the current C<urxvt::term> object.
+
+=back
+
 =head2 Functions in the C<urxvt> Package
 
 =over 4
@@ -196,6 +225,8 @@
 
 Returns the "current time" (as per the event loop).
 
+=back
+
 =head2 RENDITION
 
 Rendition bitsets contain information about colour, font, font styles and
@@ -253,8 +284,9 @@
 package urxvt;
 
 use strict;
+use Scalar::Util ();
 
-our $term;
+our $TERM;
 our @HOOKNAME;
 our $LIBDIR;
 
@@ -289,7 +321,7 @@
       my $ref = $pkg->can ("on_" . lc $name)
          or next;
 
-      $term->{_hook}[$htype]{$ref*1} = $ref;
+      $TERM->{_hook}[$htype]{$pkg} = $ref;
       $hook_count[$htype]++
          or set_should_invoke $htype, 1;
    }
@@ -323,13 +355,13 @@
 
 # called by the rxvt core
 sub invoke {
-   local $term = shift;
+   local $TERM = shift;
    my $htype = shift;
 
    if ($htype == 0) { # INIT
-      my @dirs = ((split /:/, $term->resource ("perl_lib")), "$LIBDIR/perl");
+      my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
 
-      for my $ext (split /:/, $term->resource ("perl_ext")) {
+      for my $ext (split /:/, $TERM->resource ("perl_ext")) {
          my @files = grep -f $_, map "$_/$ext", @dirs;
 
          if (@files) {
@@ -340,7 +372,7 @@
       }
 
    } elsif ($htype == 1) { # DESTROY
-      if (my $hook = $term->{_hook}) {
+      if (my $hook = $TERM->{_hook}) {
          for my $htype (0..$#$hook) {
             $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
                or set_should_invoke $htype, 0;
@@ -348,20 +380,41 @@
       }
    }
 
-   my $cb = $term->{_hook}[$htype]
+   my $cb = $TERM->{_hook}[$htype]
       or return;
 
-   verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $term, @_) . ")"
+   verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
       if $verbosity >= 10;
 
-   while (my ($k, $v) = each %$cb) {
-      return 1 if $v->($term, @_);
+   while (my ($pkg, $cb) = each %$cb) {
+      return 1
+         if $cb->(
+               $TERM->{$pkg} ||= do {
+                  my $proxy = bless { }, urxvt::term::proxy::;
+                  Scalar::Util::weaken ($proxy->{term} = $TERM);
+                  $proxy
+               },
+               @_,
+            );
    }
 
    0
 }
 
-=back
+sub urxvt::term::proxy::AUTOLOAD {
+   $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/
+      or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable";
+
+   eval qq{
+      sub $urxvt::term::proxy::AUTOLOAD {
+         unshift \@_, shift->{term};
+         goto &urxvt::term::$1;
+      }
+      1
+   } or die "FATAL: unable to compile method forwarder: $@";
+
+   goto &$urxvt::term::proxy::AUTOLOAD;
+}
 
 =head2 The C<urxvt::term> Class
 
@@ -463,7 +516,9 @@
 This method returns an urxvt::overlay object. The overlay will be visible
 as long as the perl object is referenced.
 
-Currently, the only method on the C<urxvt::overlay> object is C<set>:
+The methods currently supported on C<urxvt::overlay> objects are:
+
+=over 4
 
 =item $overlay->set ($x, $y, $text, $rend)
 
@@ -471,6 +526,16 @@
 text in rxvt-unicode's special encoding and an array of rendition values
 at a specific position inside the overlay.
 
+=item $overlay->hide
+
+If visible, hide the overlay, but do not destroy it.
+
+=item $overlay->show
+
+If hidden, display the overlay again.
+
+=back
+
 =item $cellwidth = $term->strwidth $string
 
 Returns the number of screen-cells this string would need. Correctly