rxvtperl - rxvt-unicode's embedded perl interpreter
* 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;
()
}
1
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
.
- 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).
- ($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.
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.
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.
Marc Lehmann <pcg@goof.com>
http://software.schmorp.de/pkg/rxvt-unicode