[ViewVC] Diff of: cvs/rxvt-unicode/src/urxvt.pm

Comparing rxvt-unicode/src/urxvt.pm (file contents):
Revision 1.76 by root, Tue Jan 10 19:46:28 2006 UTC vs.
Revision 1.111 by root, Thu Jan 19 19:52:54 2006 UTC

 You can activate them like this:
   @@RXVT_NAME@@ -pe <extensionname>
+Or by adding them to the resource for extensions loaded by default:
+  URxvt.perl-ext-common: default,automove-background,selection-autotransform
 =over 4
 =item selection (enabled by default)
 (More) intelligent selection. This extension tries to be more intelligent
-when the user extends selections (double-click). Right now, it tries to
+when the user extends selections (double-click and further clicks). Right
-select urls and complete shell-quoted arguments, which is very convenient,
+now, it tries to select words, urls and complete shell-quoted
-too, if your F<ls> supports C<--quoting-style=shell>.
+arguments, which is very convenient, too, if your F<ls> supports
+C<--quoting-style=shell>.
+A double-click usually selects the word under the cursor, further clicks
+will enlarge the selection.
+The selection works by trying to match a number of regexes and displaying
+them in increasing order of length. You can add your own regexes by
+specifying resources of the form:
+   URxvt.selection.pattern-0: perl-regex
+   URxvt.selection.pattern-1: perl-regex
+   ...
+The index number (0, 1...) must not have any holes, and each regex must
+contain at least one pair of capturing parentheses, which will be used for
+the match. For example, the followign adds a regex that matches everything
+between two vertical bars:
+   URxvt.selection.pattern-0: \\|([^|]+)\\|
+You can look at the source of the selection extension to see more
+interesting uses, such as parsing a line from beginning to end.
-It also offers the following bindable keyboard command:
+This extension also offers following bindable keyboard commands:
 =over 4
 =item rot13
 Binds a popup menu to Ctrl-Button3 that lets you convert the selection
 text into various other formats/action (such as uri unescaping, perl
 evalution, web-browser starting etc.), depending on content.
+Other extensions can extend this popup menu by pushing a code reference
+onto C<@{ $term->{selection_popup_hook} }>, that is called whenever the
+popup is displayed.
+It's sole argument is the popup menu, which can be modified. The selection
+is in C<$_>, which can be used to decide wether to add something or not.
+It should either return nothing or a string and a code reference. The
+string will be used as button text and the code reference will be called
+when the button gets activated and should transform C<$_>.
+The following will add an entry C<a to b> that transforms all C<a>s in
+the selection to C<b>s, but only if the selection currently contains any
+C<a>s:
+   push @{ $self->{term}{selection_popup_hook} }, sub {
+      /a/ ? ("a to be" => sub { s/a/b/g }
+          : ()
+   };
 =item searchable-scrollback<hotkey> (enabled by default)
 Adds regex search functionality to the scrollback buffer, triggered
-by a hotkey (default: C<M-s>). When in search mode, normal terminal
+by a hotkey (default: C<M-s>). While in search mode, normal terminal
-input/output is suspended.
+input/output is suspended and a regex is displayed at the bottom of the
+screen.
-C</> starts an incremental regex search, C<n> searches further, C<p> or
+Inputting characters appends them to the regex and continues incremental
-C<N> jump to the previous match, C<G> jumps to the bottom and clears the
+search. C<BackSpace> removes a character from the regex, C<Up> and C<Down>
-history, C<enter> leaves search mode at the current position and C<escape>
+search upwards/downwards in the scrollback buffer, C<End> jumps to the
-returns to the original position.
+bottom. C<Escape> leaves search mode and returns to the point where search
+was started, while C<Enter> or C<Return> stay at the current position and
+additionally stores the first match in the current line into the primary
+selection.
-=item digital-clock
+=item selection-autotransform
-Displays a digital clock using the built-in overlay.
+This selection allows you to do automatic transforms on a selection
+whenever a selection is made.
+It works by specifying perl snippets (most useful is a single C<s///>
+operator) that modify C<$_> as resources:
+   URxvt.selection-autotransform.0: transform
+   URxvt.selection-autotransform.1: transform
+   ...
+For example, the following will transform selections of the form
+C<filename:number>, often seen in compiler messages, into C<vi +$filename
+$word>:
+   URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
+And this example matches the same,but replaces it with vi-commands you can
+paste directly into your (vi :) editor:
+   URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/
+Of course, this can be modified to suit your needs and your editor :)
+To expand the example above to typical perl error messages ("XXX at
+FILENAME line YYY."), you need a slightly more elaborate solution:
+   URxvt.selection.pattern-0: ( at .*? line \\d+[,.])
+   URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/
+The first line tells the selection code to treat the unchanging part of
+every error message as a selection pattern, and the second line transforms
+the message into vi commands to load the file.
 =item mark-urls
-Uses per-line display filtering (C<on_line_update>) to underline urls.
+Uses per-line display filtering (C<on_line_update>) to underline urls and
+make them clickable. When middle-clicked, the program specified in the
+resource C<urlLauncher> (default C<x-www-browser>) will be started with
+the URL as first argument.
+=item automove-background
+This is basically a one-line extension that dynamically changes the background pixmap offset
+to the window position, in effect creating the same effect as pseudo transparency with
+a custom pixmap. No scaling is supported in this mode. Exmaple:
+   @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background
 =item 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.
+=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.
+=item selection-pastebin
+This is a little rarely useful extension that Uploads the selection as
+textfile to a remote site (or does other things). (The implementation is
+not currently secure for use in a multiuser environment as it writes to
+F</tmp> directly.).
+It listens to the C<selection-pastebin:remote-pastebin> keyboard command,
+i.e.
+   URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin
+Pressing this combination runs a command with C<%> replaced by the name of
+the textfile. This command can be set via a resource:
+   URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
+And the default is likely not useful to anybody but the few people around
+here :)
+The name of the textfile is the hex encoded md5 sum of the selection, so
+the same content should lead to the same filename.
+After a successful upload the selection will be replaced by the text given
+in the C<selection-pastebin-url> resource (again, the % is the placeholder
+for the filename):
+   URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
 =back
 =head1 API DOCUMENTATION
 =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.
+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
 =item on_start $term
 Called at the very end of initialisation of a new terminal, just before
 returning to the mainloop.
+=item on_child_start $term, $pid
+Called just after the child process has been C<fork>ed.
+=item on_child_exit $term, $status
+Called just after the child process has exited. C<$status> is the status
+from C<waitpid>.
 =item on_sel_make $term, $eventtime
 Called whenever a selection has been made by the user, but before the
 selection text is copied, so changes to the beginning, end or type of the
 selection will be honored.
 =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.
+processing. This can happen multiple times, as long as the callback
+returns true, it will be called on every further click by the user and is
+supposed to enlarge the selection more and more, if possible.
 See the F<selection> example extension.
 =item on_view_change $term, $offset
 Called whenever the user presses a key combination that has a
 C<perl:string> action bound to it (see description of the B<keysym>
 resource in the @@RXVT_NAME@@(1) manpage).
+=item on_x_event $term, $event
+Called on every X event received on the vt window (and possibly other
+windows). Should only be used as a last resort. Most event structure
+members are not passed.
 =item on_focus_in $term
 Called whenever the window gets the keyboard focus, before rxvt-unicode
 does focus in processing.
 =item on_focus_out $term
 Called wheneever the window loses keyboard focus, before rxvt-unicode does
 focus out processing.
+=item on_configure_notify $term, $event
 =item on_key_press $term, $event, $keysym, $octets
 =item on_key_release $term, $event, $keysym
 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
-=over 4
-=item $urxvt::LIBDIR
-The rxvt-unicode library directory, where, among other things, the perl
-modules and scripts are stored.
-=item $urxvt::RESCLASS, $urxvt::RESCLASS
-The resource class and name rxvt-unicode uses to look up X resources.
-=item $urxvt::RXVTNAME
-The basename of the installed binaries, usually C<urxvt>.
-=item $urxvt::TERM
-The current terminal. This variable stores the current C<urxvt::term>
-object, whenever a callback/hook is executing.
-=item
-=back
-=head2 Functions in the C<urxvt> Package
-=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
-costs! The only time this is acceptable is when the terminal process
-starts up.
-=item urxvt::warn $string
-Calls C<rxvt_warn> with the given string which should not include a
-newline. The module also overwrites the C<warn> builtin with a function
-that calls this function.
-Using this function has the advantage that its output ends up in the
-correct place, e.g. on stderr of the connecting urxvtc client.
-=item $is_safe = urxvt::safe
-Returns true when it is safe to do potentially unsafe things, such as
-evaluating perl code specified by the user. This is true when urxvt was
-started setuid or setgid.
-=item $time = urxvt::NOW
-Returns the "current time" (as per the event loop).
-=item urxvt::CurrentTime
-=item 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.
-=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
 our $LIBDIR;
 our $RESNAME;
 our $RESCLASS;
 our $RXVTNAME;
+=head2 Variables in the C<urxvt> Package
+=over 4
+=item $urxvt::LIBDIR
+The rxvt-unicode library directory, where, among other things, the perl
+modules and scripts are stored.
+=item $urxvt::RESCLASS, $urxvt::RESCLASS
+The resource class and name rxvt-unicode uses to look up X resources.
+=item $urxvt::RXVTNAME
+The basename of the installed binaries, usually C<urxvt>.
+=item $urxvt::TERM
+The current terminal. This variable stores the current C<urxvt::term>
+object, whenever a callback/hook is executing.
+=back
+=head2 Functions in the C<urxvt> Package
+=over 4
+=item 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
+starts up.
+=item urxvt::warn $string
+Calls C<rxvt_warn> with the given string which should not include a
+newline. The module also overwrites the C<warn> builtin with a function
+that calls this function.
+Using this function has the advantage that its output ends up in the
+correct place, e.g. on stderr of the connecting urxvtc client.
+Messages have a size limit of 1023 bytes currently.
+=item $time = urxvt::NOW
+Returns the "current time" (as per the event loop).
+=item urxvt::CurrentTime
+=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
+Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
+Button4Mask, Button5Mask, AnyModifier
+=item urxvt::NoEventMask, KeyPressMask, KeyReleaseMask,
+ButtonPressMask, ButtonReleaseMask, EnterWindowMask, LeaveWindowMask,
+PointerMotionMask, PointerMotionHintMask, Button1MotionMask, Button2MotionMask,
+Button3MotionMask, Button4MotionMask, Button5MotionMask, ButtonMotionMask,
+KeymapStateMask, ExposureMask, VisibilityChangeMask, StructureNotifyMask,
+ResizeRedirectMask, SubstructureNotifyMask, SubstructureRedirectMask,
+FocusChangeMask, PropertyChangeMask, ColormapChangeMask, OwnerGrabButtonMask
+=item urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify,
+EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose,
+GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify, DestroyNotify,
+UnmapNotify, MapNotify, MapRequest, ReparentNotify, ConfigureNotify,
+ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify,
+CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest,
+SelectionNotify, ColormapNotify, ClientMessage, MappingNotify
+Various constants for use in X calls and event processing.
+=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
 BEGIN {
-   urxvt->bootstrap;
    # overwrite perl's warn
    *CORE::GLOBAL::warn = sub {
       my $msg = join "", @_;
       $msg .= "\n"
          unless $msg =~ /\n$/;
       urxvt::warn ($msg);
    };
-   delete $ENV{IFS};
-   delete $ENV{CDPATH};
-   delete $ENV{BASH_ENV};
-   $ENV{PATH} = "/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/opt/bin:/opt/sbin";
 }
-my @hook_count;
 my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
 sub verbose {
    my ($level, $msg) = @_;
    warn "$msg\n" if $level <= $verbosity;
 }
-my $extension_pkg = "extension0000";
 my %extension_pkg;
 # load a single script into its own package, once only
 sub extension_package($) {
    my ($path) = @_;
+   no strict 'refs';
    $extension_pkg{$path} ||= do {
-      my $pkg = "urxvt::" . ($extension_pkg++);
+      $path =~ /([^\/\\]+)$/;
+      my $pkg = $1;
+      $pkg =~ s/[^[:word:]]/_/g;
+      $pkg = "urxvt::ext::$pkg";
       verbose 3, "loading extension '$path' into package '$pkg'";
       open my $fh, "<:raw", $path
          or die "$path: $!";
+      @{"$pkg\::ISA"} = urxvt::term::extension::;
-      my $source = untaint
+      my $source =
          "package $pkg; use strict; use utf8;\n"
-         . "use base urxvt::term::extension::;\n"
          . "#line 1 \"$path\"\n{\n"
          . (do { local $/; <$fh> })
          . "\n};\n1";
       eval $source
          if ($@) {
             $TERM->ungrab; # better to lose the grab than the session
             warn $@;
          }
       }
+      verbose 11, "$HOOKNAME[$htype] returning <$retval>"
+         if $verbosity >= 11;
    }
    if ($htype == 1) { # DESTROY
-      if (my $hook = delete $TERM->{_hook}) {
-         for my $htype (0..$#$hook) {
-            $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
-               or set_should_invoke $htype, 0;
-         }
-      }
       # clear package objects
       %$_ = () for values %{ $TERM->{_pkg} };
       # clear package
       %$TERM = ();
    while (my ($name, $cb) = each %hook) {
       my $htype = $HOOKTYPE{uc $name};
       defined $htype
          or Carp::croak "unsupported hook type '$name'";
+      $self->set_should_invoke ($htype, +1)
-      unless (exists $self->{term}{_hook}[$htype]{$pkg}) {
+         unless exists $self->{term}{_hook}[$htype]{$pkg};
-         $hook_count[$htype]++
-            or urxvt::set_should_invoke $htype, 1;
-      }
       $self->{term}{_hook}[$htype]{$pkg} = $cb;
    }
 }
    for my $name (@hook) {
       my $htype = $HOOKTYPE{uc $name};
       defined $htype
          or Carp::croak "unsupported hook type '$name'";
+      $self->set_should_invoke ($htype, -1)
-      if (delete $self->{term}{_hook}[$htype]{$pkg}) {
+         if delete $self->{term}{_hook}[$htype]{$pkg};
-         --$hook_count[$htype]
-            or urxvt::set_should_invoke $htype, 0;
-      }
    }
 }
 our $AUTOLOAD;
          $proxy->enable ($name => $ref);
       }
    }
 }
+=item $term = new urxvt::term $envhashref, $rxvtname, [arg...]
+Creates a new terminal, very similar as if you had started it with system
+C<$rxvtname, arg...>. C<$envhashref> must be a reference to a C<%ENV>-like
+hash which defines the environment of the new terminal.
+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 this call.
+=cut
+sub new {
+   my ($class, $env, @args) = @_;
+   _new ([ map "$_=$env->{$_}", keys %$env ], @args);
+}
 =item $term->destroy
 Destroy the terminal object (close the window, free resources
 etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event
 watchers (timers, io watchers) are still active.
+=item $term->exec_async ($cmd[, @args])
+Works like the combination of the C<fork>/C<exec> builtins, which executes
+("starts") programs in the background. This function takes care of setting
+the user environment before exec'ing the command (e.g. C<PATH>) and should
+be preferred over explicit calls to C<exec> or C<system>.
+Returns the pid of the subprocess or C<undef> on error.
+=cut
+sub exec_async {
+   my $self = shift;
+   my $pid = fork;
+   return $pid
+      if !defined $pid or $pid;
+   %ENV = %{ $self->env };
+   exec @_;
+   urxvt::_exit 255;
+}
 =item $isset = $term->option ($optval[, $set])
 Returns true if the option specified by C<$optval> is enabled, and
 optionally change it. All option values are stored by name in the hash
 C<%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 F</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
+ override-redirect pastableTabs pointerBlank reverseVideo scrollBar
- scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer
+ scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput
- secondaryScreen secondaryScroll skipBuiltinGlyphs transparent
+ scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs
- tripleclickwords utmpInhibit visualBell
+ transparent tripleclickwords utmpInhibit visualBell
 =item $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 C<init>
   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
+  italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier
-  mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2
+  mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
-  perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
+  perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
-  reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
+  preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
-  scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
+  scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
-  scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
+  scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
-  shade term_name title transparent transparent_all tripleclickwords
+  secondaryScreen secondaryScroll selectstyle shade term_name title
-  utmpInhibit visualBell
+  transient_for transparent transparent_all tripleclickwords utmpInhibit
+  visualBell
 =cut
 sub resource($$;$) {
    my ($self, $name) = (shift, shift);
    unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
    &urxvt::term::_resource
 }
+=item $value = $term->x_resource ($pattern)
+Returns the X-Resource for the given pattern, excluding the program or
+class name, i.e.  C<< $term->x_resource ("boldFont") >> should return the
+same value as used by this instance of rxvt-unicode. Returns C<undef> if no
+resource with that pattern exists.
+This method should only be called during the C<on_start> hook, as there is
+only one resource database per display, and later invocations might return
+the wrong resources.
 =item $success = $term->parse_keysym ($keysym_spec, $command_string)
 Adds a keymap translation exactly as specified via a resource. See the
 C<keysym> resource in the @@RXVT_NAME@@(1) manpage.
 =item ($row, $col) = $term->selection_end ([$row, $col])
 Return the current values of the selection mark, begin or end positions,
 and optionally set them to new values.
+=item $term->selection_make ($eventtime[, $rectangular])
+Tries to make a selection as set by C<selection_beg> and
+C<selection_end>. If C<$rectangular> is true (default: false), a
+rectangular selection will be made. This is the prefered function to make
+a selection.
 =item $success = $term->selection_grab ($eventtime)
-Try to request the primary selection from the server (for example, as set
+Try to request the primary selection text from the server (for example, as
-by the next method).
+set by the next method). No visual feedback will be given. This function
+is mostly useful from within C<on_sel_grab> hooks.
 =item $oldtext = $term->selection ([$newtext])
 Return the current selection text and optionally replace it by C<$newtext>.
 Convert the given locale-encoded octets into a perl string.
 =item $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
 XORs the rendition values in the given span with the provided value
-(default: C<RS_RVid>). Useful in refresh hooks to provide effects similar
+(default: C<RS_RVid>), which I<MUST NOT> contain font styles. Useful in
-to the selection.
+refresh hooks to provide effects similar to the selection.
 =item $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, $rstyle2]])
 Similar to C<scr_xor_span>, but xors a rectangle instead. Trailing
 whitespace will additionally be xored with the C<$rstyle2>, which defaults
 to C<RS_RVid | RS_Uline>, which removes reverse video again and underlines
-it instead.
+it instead. Both styles I<MUST NOT> contain font styles.
 =item $term->scr_bell
 Ring the bell!
 =item $windowid = $term->vt
 Return the window id of the terminal window.
+=item $term->vt_emask_add ($x_event_mask)
+Adds the specified events to the vt event mask. Useful e.g. when you want
+to receive pointer events all the times:
+   $term->vt_emask_add (urxvt::PointerMotionMask);
 =item $window_width = $term->width
 =item $window_height = $term->height
 =item $font_width = $term->fwidth
 =item $max_scrollback = $term->saveLines
 =item $nrow_plus_saveLines = $term->total_rows
-=item $lines_in_scrollback = $term->nsaved
+=item $topmost_scrollback_row = $term->top_row
 Return various integers describing terminal characteristics.
+=item $x_display = $term->display_id
+Return the DISPLAY used by rxvt-unicode.
 =item $lc_ctype = $term->locale
 Returns the LC_CTYPE category string used by this rxvt-unicode.
-=item $x_display = $term->display_id
+=item $env = $term->env
-Return the DISPLAY used by rxvt-unicode.
+Returns a copy of the environment in effect for the terminal as a hashref
+similar to C<\%ENV>.
+=cut
+sub env {
+   if (my $env = $_[0]->_env) {
+      +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env }
+   } else {
+      +{ %ENV }
+   }
+}
 =item $modifiermask = $term->ModLevel3Mask
 =item $modifiermask = $term->ModMetaMask
 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.
 =item $view_start = $term->view_start ([$newvalue])
-Returns the negative row number of the topmost line. Minimum value is
+Returns the row number of the topmost displayed line. Maximum value is
-C<0>, which displays the normal terminal contents. Larger values scroll
+C<0>, which displays the normal terminal contents. Lower values scroll
 this many lines into the scrollback buffer.
 =item $term->want_refresh
 Requests a screen refresh. At the next opportunity, rxvt-unicode will
 Return the row number of the first/last row of the line, respectively.
 =item $offset = $line->offset_of ($row, $col)
 Returns the character offset of the given row|col pair within the logical
-line.
+line. Works for rows outside the line, too, and returns corresponding
+offsets outside the string.
 =item ($row, $col) = $line->coord_of ($offset)
 Translates a string offset into terminal coordinates again.
 sub show {
    my ($self) = @_;
    local $urxvt::popup::self = $self;
+   my $env = $self->{term}->env;
+   # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
+   delete $env->{LC_ALL};
-   local $ENV{LC_ALL} = $self->{term}->locale;
+   $env->{LC_CTYPE} = $self->{term}->locale;
-   urxvt->new ("--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0,
+   urxvt::term->new ($env, "popup",
+                     "--perl-lib" => "", "--perl-ext-common" => "",
+                     "-pty-fd" => -1, "-sl" => 0,
+                     "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect",
-               "--transient-for" => $self->{term}->parent,
+                     "--transient-for" => $self->{term}->parent,
-               "-display" => $self->{term}->display_id,
+                     "-display" => $self->{term}->display_id,
-               "-pe" => "urxvt-popup")
+                     "-pe" => "urxvt-popup")
       or die "unable to create popup window\n";
 }
 sub DESTROY {
    my ($self) = @_;
    delete $self->{term}{_destroy}{$self};
    $self->{term}->ungrab;
 }
+=back
 =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:
 Start the timer.
 =item $timer = $timer->start ($tstamp)
 Set the event trigger time to C<$tstamp> and start the timer.
+=item $timer = $timer->after ($delay)
+Like C<start>, but sets the expiry timer to c<urxvt::NOW + $delay>.
 =item $timer = $timer->stop
 Stop the timer.
 =item == 0 - fatal messages
 =item >= 3 - script loading and management
-=item >=10 - all events received
+=item >=10 - all called hooks
+=item >=11 - hook reutrn values
 =back
 =head1 AUTHOR

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing rxvt-unicode/src/urxvt.pm (file contents): Revision 1.76 by root, Tue Jan 10 19:46:28 2006 UTC vs. Revision 1.111 by root, Thu Jan 19 19:52:54 2006 UTC

Diff Legend

Comparing rxvt-unicode/src/urxvt.pm (file contents):
Revision 1.76 by root, Tue Jan 10 19:46:28 2006 UTC vs.
Revision 1.111 by root, Thu Jan 19 19:52:54 2006 UTC