AUTHOR

NAME

rxvtperl - rxvt-unicode's embedded perl interpreter

SYNOPSIS

* Put your scripts into /opt/rxvt/lib/urxvt/perl-ext/, they will be loaded automatically.

* Each script will only be loaded once, even in urxvtd, and will be valid globally.

* Scripts are evaluated in a 'use strict' and 'use utf8' environment, and thus must be encoded as UTF-8.

   sub on_sel_grab {
      warn "you selected ", $_[0]->selection;
      ()
   }

DESCRIPTION

Hooks

The following subroutines can be declared in loaded scripts, and will be called whenever the relevant event happens.

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 skipped, and the relevant action might not be carried out by the C++ code.

When in doubt, return a false value (preferably ()).

on_init $term: Called after a new terminal object has been initialized, but before windows are created or the command gets run.
on_reset $term: Called after the screen is ``reset'' for any reason, such as resizing or control sequences. Here is where you can react on changes to size-related variables.
on_start $term: Called at the very end of initialisation of a new terminal, just before returning to the mainloop.
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.; Returning a true value aborts selection making by urxvt, in which case you have to make a selection yourself by calling $term->selection_grab.
on_sel_grab $term, $eventtime: Called whenever a selection has been copied, but before the selection is requested from the server. The selection text can be queried and changed by calling $term->selection.; Returning a true value aborts selection grabbing. It will still be hilighted.
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 show this many lines of scrollback.
on_scroll_back $term, $lines, $saved: Called whenever lines scroll out of the terminal area into the scrollback buffer. $lines is the number of lines scrolled out and may be larger than the scroll back buffer or the terminal.; It is called before lines are scrolled out (so rows 0 .. min ($lines - 1, $nrow - 1) represent the lines to be scrolled out). $saved is the total number of lines that will be in the scrollback buffer.
on_tty_activity $term *NYI*: Called whenever the program(s) running in the urxvt window send output.
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 restoring them in refresh_end. The built-in overlay and selection display code is run after this hook, and takes precedence.
on_refresh_end $term: Called just after the screen gets redrawn. See on_refresh_begin.

Functions in the `urxvt` Package

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.
urxvt::warn $string: Calls rxvt_warn witht eh given string which should not include a newline. The module also overwrites the 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.
$cellwidth = urxvt::wcswidth $string: Returns the number of screen-cells this string would need. Correctly accounts for wide and combining characters.
$time = urxvt::NOW: Returns the ``current time'' (as per the event loop).

The `urxvt::term` Class

($row, $col) = $term->selection_mark ([$row, $col])
($row, $col) = $term->selection_beg ([$row, $col])
($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.
$success = $term->selection_grab ($eventtime): Try to request the primary selection from the server (for example, as set by the next method).
$oldtext = $term->selection ([$newtext]): Return the current selection text and optionally replace it by $newtext.
$term->scr_overlay ($x, $y, $text): Create a simple multi-line overlay box. See the next method for details.
$term->scr_overlay_new ($x, $y, $width, $height): Create a new (empty) overlay at the given position with the given width/height. A border will be put around the box. If either $x or $y is negative, then this is counted from the right/bottom side, respectively.
$term->scr_overlay_off: Switch the overlay off again.
$term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE): Put a single character (specified numerically) at the given overlay position.
$term->scr_overlay_set ($x, $y, $text): Write a string at the given position into the overlay.

The `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->{timer} = urxvt::timer
                    ->new
                    ->start (urxvt::NOW)
                    ->cb (sub {
                       my ($timer) = @_;
                       my $time = $timer->at;
                       $timer->start ($time + 1);
                       $self->scr_overlay (-1, 0, 
                          POSIX::strftime "%H:%M:%S", localtime $time);
                    });

$timer = new urxvt::timer: Create a new timer object in stopped state.
$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->start: Start the timer.
$timer = $timer->start ($tstamp): Set the event trigger time to $tstamp and start the timer.
$timer = $timer->stop: Stop the timer.

The `urxvt::iow` Class

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.
$iow = $iow->start: Start watching for requested events on the given handle.
$iow = $iow->stop: Stop watching for events on the given filehandle.

AUTHOR

 Marc Lehmann <pcg@goof.com>
 http://software.schmorp.de/pkg/rxvt-unicode