--- /dev/null
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>rxvtperl - rxvt-unicode's embedded perl interpreter</title>
+<link rev="made" href="mailto:perl-binary@plan9.de" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <ul>
+
+ <li><a href="#hooks">Hooks</a></li>
+ <li><a href="#functions_in_the_urxvt_package">Functions in the <code>urxvt</code> Package</a></li>
+ <li><a href="#the_urxvt__term_class">The <code>urxvt::term</code> Class</a></li>
+ <li><a href="#the_urxvt__timer_class">The <code>urxvt::timer</code> Class</a></li>
+ <li><a href="#the_urxvt__iow_class">The <code>urxvt::iow</code> Class</a></li>
+ </ul>
+
+ <li><a href="#author">AUTHOR</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>rxvtperl - rxvt-unicode's embedded perl interpreter</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<p>* Put your scripts into <em>/opt/rxvt/lib/urxvt/perl-ext/</em>, they will be loaded automatically.</p>
+<p>* Each script will only be loaded once, even in urxvtd, and will be valid
+globally.</p>
+<p>* Scripts are evaluated in a 'use strict' and 'use utf8' environment, and
+thus must be encoded as UTF-8.</p>
+<pre>
+ sub on_sel_grab {
+ warn "you selected ", $_[0]->selection;
+ ()
+ }</pre>
+<pre>
+ 1</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>
+</p>
+<h2><a name="hooks">Hooks</a></h2>
+<p>The following subroutines can be declared in loaded scripts, and will be called
+whenever the relevant event happens.</p>
+<p>All of them must return a boolean value. If it is true, then the event
+counts as being <em>consumed</em>, and the invocation of other hooks is skipped,
+and the relevant action might not be carried out by the C++ code.</p>
+<p>When in doubt, return a false value (preferably <code>()</code>).</p>
+<dl>
+<dt><strong><a name="item_on_init__24term">on_init $term</a></strong><br />
+</dt>
+<dd>
+Called after a new terminal object has been initialized, but before
+windows are created or the command gets run.
+</dd>
+<p></p>
+<dt><strong><a name="item_on_reset__24term">on_reset $term</a></strong><br />
+</dt>
+<dd>
+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.
+</dd>
+<p></p>
+<dt><strong><a name="item_on_start__24term">on_start $term</a></strong><br />
+</dt>
+<dd>
+Called at the very end of initialisation of a new terminal, just before
+returning to the mainloop.
+</dd>
+<p></p>
+<dt><strong><a name="item_on_sel_make__24term_2c__24eventtime">on_sel_make $term, $eventtime</a></strong><br />
+</dt>
+<dd>
+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.
+</dd>
+<dd>
+<p>Returning a true value aborts selection making by urxvt, in which case you
+have to make a selection yourself by calling <a href="#item_selection_grab"><code>$term->selection_grab</code></a>.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_on_sel_grab__24term_2c__24eventtime">on_sel_grab $term, $eventtime</a></strong><br />
+</dt>
+<dd>
+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 <a href="#item_selection"><code>$term->selection</code></a>.
+</dd>
+<dd>
+<p>Returning a true value aborts selection grabbing. It will still be hilighted.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_on_focus_in__24term">on_focus_in $term</a></strong><br />
+</dt>
+<dd>
+Called whenever the window gets the keyboard focus, before urxvt does
+focus in processing.
+</dd>
+<p></p>
+<dt><strong><a name="item_on_focus_out__24term">on_focus_out $term</a></strong><br />
+</dt>
+<dd>
+Called wheneever the window loses keyboard focus, before urxvt does focus
+out processing.
+</dd>
+<p></p>
+<dt><strong><a name="item_on_view_change__24term_2c__24offset">on_view_change $term, $offset</a></strong><br />
+</dt>
+<dd>
+Called whenever the view offset changes, i..e the user or program
+scrolls. Offset <code>0</code> means display the normal terminal, positive values
+show this many lines of scrollback.
+</dd>
+<p></p>
+<dt><strong><a name="item_on_scroll_back__24term_2c__24lines_2c__24saved">on_scroll_back $term, $lines, $saved</a></strong><br />
+</dt>
+<dd>
+Called whenever lines scroll out of the terminal area into the scrollback
+buffer. <code>$lines</code> is the number of lines scrolled out and may be larger
+than the scroll back buffer or the terminal.
+</dd>
+<dd>
+<p>It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
+$nrow - 1) represent the lines to be scrolled out). <code>$saved</code> is the total
+number of lines that will be in the scrollback buffer.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_on_tty_activity__24term__2anyi_2a">on_tty_activity $term *NYI*</a></strong><br />
+</dt>
+<dd>
+Called whenever the <code>program(s)</code> running in the urxvt window send output.
+</dd>
+<p></p>
+<dt><strong><a name="item_on_refresh_begin__24term">on_refresh_begin $term</a></strong><br />
+</dt>
+<dd>
+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.
+</dd>
+<p></p>
+<dt><strong><a name="item_on_refresh_end__24term">on_refresh_end $term</a></strong><br />
+</dt>
+<dd>
+Called just after the screen gets redrawn. See <code>on_refresh_begin</code>.
+</dd>
+<p></p></dl>
+<p>
+</p>
+<h2><a name="functions_in_the_urxvt_package">Functions in the <code>urxvt</code> Package</a></h2>
+<dl>
+<dt><strong><a name="item_urxvt_3a_3afatal__24errormessage">urxvt::fatal $errormessage</a></strong><br />
+</dt>
+<dd>
+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.
+</dd>
+<p></p>
+<dt><strong><a name="item_urxvt_3a_3awarn__24string">urxvt::warn $string</a></strong><br />
+</dt>
+<dd>
+Calls <code>rxvt_warn</code> witht eh given string which should not include a
+newline. The module also overwrites the <code>warn</code> builtin with a function
+that calls this function.
+</dd>
+<dd>
+<p>Using this function has the advantage that its output ends up in the
+correct place, e.g. on stderr of the connecting urxvtc client.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item__24cellwidth__3d_urxvt_3a_3awcswidth__24string">$cellwidth = urxvt::wcswidth $string</a></strong><br />
+</dt>
+<dd>
+Returns the number of screen-cells this string would need. Correctly
+accounts for wide and combining characters.
+</dd>
+<p></p>
+<dt><strong><a name="item__24time__3d_urxvt_3a_3anow">$time = urxvt::NOW</a></strong><br />
+</dt>
+<dd>
+Returns the ``current time'' (as per the event loop).
+</dd>
+<p></p></dl>
+<p>
+</p>
+<h2><a name="the_urxvt__term_class">The <code>urxvt::term</code> Class</a></h2>
+<dl>
+<dt><strong><a name="item_selection_mark">($row, $col) = $term->selection_mark ([$row, $col])</a></strong><br />
+</dt>
+<dt><strong><a name="item_selection_beg">($row, $col) = $term->selection_beg ([$row, $col])</a></strong><br />
+</dt>
+<dt><strong><a name="item_selection_end">($row, $col) = $term->selection_end ([$row, $col])</a></strong><br />
+</dt>
+<dd>
+Return the current values of the selection mark, begin or end positions,
+and optionally set them to new values.
+</dd>
+<p></p>
+<dt><strong><a name="item_selection_grab">$success = $term->selection_grab ($eventtime)</a></strong><br />
+</dt>
+<dd>
+Try to request the primary selection from the server (for example, as set
+by the next method).
+</dd>
+<p></p>
+<dt><strong><a name="item_selection">$oldtext = $term->selection ([$newtext])</a></strong><br />
+</dt>
+<dd>
+Return the current selection text and optionally replace it by <code>$newtext</code>.
+</dd>
+<p></p>
+<dt><strong><a name="item_scr_overlay">$term->scr_overlay ($x, $y, $text)</a></strong><br />
+</dt>
+<dd>
+Create a simple multi-line overlay box. See the next method for details.
+</dd>
+<p></p>
+<dt><strong><a name="item_scr_overlay_new">$term->scr_overlay_new ($x, $y, $width, $height)</a></strong><br />
+</dt>
+<dd>
+Create a new (empty) overlay at the given position with the given
+width/height. A border will be put around the box. If either <code>$x</code> or
+<code>$y</code> is negative, then this is counted from the right/bottom side,
+respectively.
+</dd>
+<p></p>
+<dt><strong><a name="item_scr_overlay_off">$term->scr_overlay_off</a></strong><br />
+</dt>
+<dd>
+Switch the overlay off again.
+</dd>
+<p></p>
+<dt><strong><a name="item_scr_overlay_set_char">$term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE)</a></strong><br />
+</dt>
+<dd>
+Put a single character (specified numerically) at the given overlay
+position.
+</dd>
+<p></p>
+<dt><strong><a name="item_scr_overlay_set">$term->scr_overlay_set ($x, $y, $text)</a></strong><br />
+</dt>
+<dd>
+Write a string at the given position into the overlay.
+</dd>
+<p></p></dl>
+<p>
+</p>
+<h2><a name="the_urxvt__timer_class">The <code>urxvt::timer</code> Class</a></h2>
+<p>This class implements timer watchers/events. Time is represented as a
+fractional number of seconds since the epoch. Example:</p>
+<pre>
+ # 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);
+ });</pre>
+<dl>
+<dt><strong><a name="item__24timer__3d_new_urxvt_3a_3atimer">$timer = new urxvt::timer</a></strong><br />
+</dt>
+<dd>
+Create a new timer object in stopped state.
+</dd>
+<p></p>
+<dt><strong><a name="item_cb">$timer = $timer->cb (sub { my ($timer) = @_; ... })</a></strong><br />
+</dt>
+<dd>
+Set the callback to be called when the timer triggers.
+</dd>
+<p></p>
+<dt><strong><a name="item_at">$tstamp = $timer->at</a></strong><br />
+</dt>
+<dd>
+Return the time this watcher will fire next.
+</dd>
+<p></p>
+<dt><strong><a name="item_set">$timer = $timer->set ($tstamp)</a></strong><br />
+</dt>
+<dd>
+Set the time the event is generated to $tstamp.
+</dd>
+<p></p>
+<dt><strong><a name="item_start">$timer = $timer->start</a></strong><br />
+</dt>
+<dd>
+Start the timer.
+</dd>
+<p></p>
+<dt><strong>$timer = $timer->start ($tstamp)</strong><br />
+</dt>
+<dd>
+Set the event trigger time to <code>$tstamp</code> and start the timer.
+</dd>
+<p></p>
+<dt><strong><a name="item_stop">$timer = $timer->stop</a></strong><br />
+</dt>
+<dd>
+Stop the timer.
+</dd>
+<p></p></dl>
+<p>
+</p>
+<h2><a name="the_urxvt__iow_class">The <code>urxvt::iow</code> Class</a></h2>
+<p>This class implements io watchers/events. Example:</p>
+<pre>
+ $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;
+ });</pre>
+<dl>
+<dt><strong><a name="item__24iow__3d_new_urxvt_3a_3aiow">$iow = new urxvt::iow</a></strong><br />
+</dt>
+<dd>
+Create a new io watcher object in stopped state.
+</dd>
+<p></p>
+<dt><strong>$iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })</strong><br />
+</dt>
+<dd>
+Set the callback to be called when io events are triggered. <code>$reventmask</code>
+is a bitset as described in the <a href="#item_events"><code>events</code></a> method.
+</dd>
+<p></p>
+<dt><strong><a name="item_fd">$iow = $iow->fd ($fd)</a></strong><br />
+</dt>
+<dd>
+Set the filedescriptor (not handle) to watch.
+</dd>
+<p></p>
+<dt><strong><a name="item_events">$iow = $iow->events ($eventmask)</a></strong><br />
+</dt>
+<dd>
+Set the event mask to watch. Bit #0 (value <code>1</code>) enables watching for read
+data, Bit #1 (value <code>2</code>) enables watching for write data.
+</dd>
+<p></p>
+<dt><strong>$iow = $iow->start</strong><br />
+</dt>
+<dd>
+Start watching for requested events on the given handle.
+</dd>
+<p></p>
+<dt><strong>$iow = $iow->stop</strong><br />
+</dt>
+<dd>
+Stop watching for events on the given filehandle.
+</dd>
+<p></p></dl>
+<p>
+</p>
+<hr />
+<h1><a name="author">AUTHOR</a></h1>
+<pre>
+ Marc Lehmann <pcg@goof.com>
+ <a href="http://software.schmorp.de/pkg/rxvt-unicode">http://software.schmorp.de/pkg/rxvt-unicode</a></pre>
+
+</body>
+
+</html>
--- /dev/null
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sh \" Subsection heading
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings. \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote. | will give a
+.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
+.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
+.\" expand to `' in nroff, nothing in troff, for use with C<>.
+.tr \(*W-|\(bv\*(Tr
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+. ds -- \(*W-
+. ds PI pi
+. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+. ds L" ""
+. ds R" ""
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds -- \|\(em\|
+. ds PI \(*p
+. ds L" ``
+. ds R" ''
+'br\}
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.if \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.\"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.hy 0
+.if n .na
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "rxvt 3"
+.TH rxvt 3 "2006-01-02" "6.2" "RXVT-UNICODE"
+.SH "NAME"
+rxvtperl \- rxvt\-unicode's embedded perl interpreter
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+* Put your scripts into \fI@@RXVT_LIBDIR@@/urxvt/perl\-ext/\fR, they will be loaded automatically.
+.PP
+* Each script will only be loaded once, even in urxvtd, and will be valid
+globally.
+.PP
+* Scripts are evaluated in a 'use strict' and 'use utf8' environment, and
+thus must be encoded as \s-1UTF\-8\s0.
+.PP
+.Vb 4
+\& sub on_sel_grab {
+\& warn "you selected ", $_[0]->selection;
+\& ()
+\& }
+.Ve
+.PP
+.Vb 1
+\& 1
+.Ve
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+.Sh "Hooks"
+.IX Subsection "Hooks"
+The following subroutines can be declared in loaded scripts, and will be called
+whenever the relevant event happens.
+.PP
+All of them must return a boolean value. If it is true, then the event
+counts as being \fIconsumed\fR, and the invocation of other hooks is skipped,
+and the relevant action might not be carried out by the \*(C+ code.
+.PP
+When in doubt, return a false value (preferably \f(CW\*(C`()\*(C'\fR).
+.ie n .IP "on_init $term" 4
+.el .IP "on_init \f(CW$term\fR" 4
+.IX Item "on_init $term"
+Called after a new terminal object has been initialized, but before
+windows are created or the command gets run.
+.ie n .IP "on_reset $term" 4
+.el .IP "on_reset \f(CW$term\fR" 4
+.IX Item "on_reset $term"
+Called after the screen is \*(L"reset\*(R" for any reason, such as resizing or
+control sequences. Here is where you can react on changes to size-related
+variables.
+.ie n .IP "on_start $term" 4
+.el .IP "on_start \f(CW$term\fR" 4
+.IX Item "on_start $term"
+Called at the very end of initialisation of a new terminal, just before
+returning to the mainloop.
+.ie n .IP "on_sel_make $term\fR, \f(CW$eventtime" 4
+.el .IP "on_sel_make \f(CW$term\fR, \f(CW$eventtime\fR" 4
+.IX 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.
+.Sp
+Returning a true value aborts selection making by urxvt, in which case you
+have to make a selection yourself by calling \f(CW\*(C`$term\->selection_grab\*(C'\fR.
+.ie n .IP "on_sel_grab $term\fR, \f(CW$eventtime" 4
+.el .IP "on_sel_grab \f(CW$term\fR, \f(CW$eventtime\fR" 4
+.IX Item "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 \f(CW\*(C`$term\->selection\*(C'\fR.
+.Sp
+Returning a true value aborts selection grabbing. It will still be hilighted.
+.ie n .IP "on_focus_in $term" 4
+.el .IP "on_focus_in \f(CW$term\fR" 4
+.IX Item "on_focus_in $term"
+Called whenever the window gets the keyboard focus, before urxvt does
+focus in processing.
+.ie n .IP "on_focus_out $term" 4
+.el .IP "on_focus_out \f(CW$term\fR" 4
+.IX Item "on_focus_out $term"
+Called wheneever the window loses keyboard focus, before urxvt does focus
+out processing.
+.ie n .IP "on_view_change $term\fR, \f(CW$offset" 4
+.el .IP "on_view_change \f(CW$term\fR, \f(CW$offset\fR" 4
+.IX Item "on_view_change $term, $offset"
+Called whenever the view offset changes, i..e the user or program
+scrolls. Offset \f(CW0\fR means display the normal terminal, positive values
+show this many lines of scrollback.
+.ie n .IP "on_scroll_back $term\fR, \f(CW$lines\fR, \f(CW$saved" 4
+.el .IP "on_scroll_back \f(CW$term\fR, \f(CW$lines\fR, \f(CW$saved\fR" 4
+.IX Item "on_scroll_back $term, $lines, $saved"
+Called whenever lines scroll out of the terminal area into the scrollback
+buffer. \f(CW$lines\fR is the number of lines scrolled out and may be larger
+than the scroll back buffer or the terminal.
+.Sp
+It is called before lines are scrolled out (so rows 0 .. min ($lines \- 1,
+\&\f(CW$nrow\fR \- 1) represent the lines to be scrolled out). \f(CW$saved\fR is the total
+number of lines that will be in the scrollback buffer.
+.ie n .IP "on_tty_activity $term *NYI*" 4
+.el .IP "on_tty_activity \f(CW$term\fR *NYI*" 4
+.IX Item "on_tty_activity $term *NYI*"
+Called whenever the program(s) running in the urxvt window send output.
+.ie n .IP "on_refresh_begin $term" 4
+.el .IP "on_refresh_begin \f(CW$term\fR" 4
+.IX Item "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.
+.ie n .IP "on_refresh_end $term" 4
+.el .IP "on_refresh_end \f(CW$term\fR" 4
+.IX Item "on_refresh_end $term"
+Called just after the screen gets redrawn. See \f(CW\*(C`on_refresh_begin\*(C'\fR.
+.ie n .Sh "Functions in the ""urxvt"" Package"
+.el .Sh "Functions in the \f(CWurxvt\fP Package"
+.IX Subsection "Functions in the urxvt Package"
+.ie n .IP "urxvt::fatal $errormessage" 4
+.el .IP "urxvt::fatal \f(CW$errormessage\fR" 4
+.IX 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.
+.ie n .IP "urxvt::warn $string" 4
+.el .IP "urxvt::warn \f(CW$string\fR" 4
+.IX Item "urxvt::warn $string"
+Calls \f(CW\*(C`rxvt_warn\*(C'\fR witht eh given string which should not include a
+newline. The module also overwrites the \f(CW\*(C`warn\*(C'\fR builtin with a function
+that calls this function.
+.Sp
+Using this function has the advantage that its output ends up in the
+correct place, e.g. on stderr of the connecting urxvtc client.
+.ie n .IP "$cellwidth = urxvt::wcswidth $string" 4
+.el .IP "$cellwidth = urxvt::wcswidth \f(CW$string\fR" 4
+.IX Item "$cellwidth = urxvt::wcswidth $string"
+Returns the number of screen-cells this string would need. Correctly
+accounts for wide and combining characters.
+.IP "$time = urxvt::NOW" 4
+.IX Item "$time = urxvt::NOW"
+Returns the \*(L"current time\*(R" (as per the event loop).
+.ie n .Sh "The ""urxvt::term"" Class"
+.el .Sh "The \f(CWurxvt::term\fP Class"
+.IX Subsection "The urxvt::term Class"
+.ie n .IP "($row, $col\fR) = \f(CW$term\fR\->selection_mark ([$row, \f(CW$col])" 4
+.el .IP "($row, \f(CW$col\fR) = \f(CW$term\fR\->selection_mark ([$row, \f(CW$col\fR])" 4
+.IX Item "($row, $col) = $term->selection_mark ([$row, $col])"
+.PD 0
+.ie n .IP "($row, $col\fR) = \f(CW$term\fR\->selection_beg ([$row, \f(CW$col])" 4
+.el .IP "($row, \f(CW$col\fR) = \f(CW$term\fR\->selection_beg ([$row, \f(CW$col\fR])" 4
+.IX Item "($row, $col) = $term->selection_beg ([$row, $col])"
+.ie n .IP "($row, $col\fR) = \f(CW$term\fR\->selection_end ([$row, \f(CW$col])" 4
+.el .IP "($row, \f(CW$col\fR) = \f(CW$term\fR\->selection_end ([$row, \f(CW$col\fR])" 4
+.IX Item "($row, $col) = $term->selection_end ([$row, $col])"
+.PD
+Return the current values of the selection mark, begin or end positions,
+and optionally set them to new values.
+.ie n .IP "$success = $term\->selection_grab ($eventtime)" 4
+.el .IP "$success = \f(CW$term\fR\->selection_grab ($eventtime)" 4
+.IX Item "$success = $term->selection_grab ($eventtime)"
+Try to request the primary selection from the server (for example, as set
+by the next method).
+.ie n .IP "$oldtext = $term\->selection ([$newtext])" 4
+.el .IP "$oldtext = \f(CW$term\fR\->selection ([$newtext])" 4
+.IX Item "$oldtext = $term->selection ([$newtext])"
+Return the current selection text and optionally replace it by \f(CW$newtext\fR.
+.ie n .IP "$term\->scr_overlay ($x, $y\fR, \f(CW$text)" 4
+.el .IP "$term\->scr_overlay ($x, \f(CW$y\fR, \f(CW$text\fR)" 4
+.IX Item "$term->scr_overlay ($x, $y, $text)"
+Create a simple multi-line overlay box. See the next method for details.
+.ie n .IP "$term\->scr_overlay_new ($x, $y\fR, \f(CW$width\fR, \f(CW$height)" 4
+.el .IP "$term\->scr_overlay_new ($x, \f(CW$y\fR, \f(CW$width\fR, \f(CW$height\fR)" 4
+.IX Item "$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 \f(CW$x\fR or
+\&\f(CW$y\fR is negative, then this is counted from the right/bottom side,
+respectively.
+.IP "$term\->scr_overlay_off" 4
+.IX Item "$term->scr_overlay_off"
+Switch the overlay off again.
+.ie n .IP "$term\->scr_overlay_set_char ($x, $y\fR, \f(CW$char\fR, \f(CW$rend = \s-1OVERLAY_RSTYLE\s0)" 4
+.el .IP "$term\->scr_overlay_set_char ($x, \f(CW$y\fR, \f(CW$char\fR, \f(CW$rend\fR = \s-1OVERLAY_RSTYLE\s0)" 4
+.IX Item "$term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE)"
+Put a single character (specified numerically) at the given overlay
+position.
+.ie n .IP "$term\->scr_overlay_set ($x, $y\fR, \f(CW$text)" 4
+.el .IP "$term\->scr_overlay_set ($x, \f(CW$y\fR, \f(CW$text\fR)" 4
+.IX Item "$term->scr_overlay_set ($x, $y, $text)"
+Write a string at the given position into the overlay.
+.ie n .Sh "The ""urxvt::timer"" Class"
+.el .Sh "The \f(CWurxvt::timer\fP Class"
+.IX Subsection "The urxvt::timer Class"
+This class implements timer watchers/events. Time is represented as a
+fractional number of seconds since the epoch. Example:
+.PP
+.Vb 11
+\& # 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);
+\& });
+.Ve
+.IP "$timer = new urxvt::timer" 4
+.IX Item "$timer = new urxvt::timer"
+Create a new timer object in stopped state.
+.ie n .IP "$timer = $timer\fR\->cb (sub { my ($timer) = \f(CW@_; ... })" 4
+.el .IP "$timer = \f(CW$timer\fR\->cb (sub { my ($timer) = \f(CW@_\fR; ... })" 4
+.IX Item "$timer = $timer->cb (sub { my ($timer) = @_; ... })"
+Set the callback to be called when the timer triggers.
+.ie n .IP "$tstamp = $timer\->at" 4
+.el .IP "$tstamp = \f(CW$timer\fR\->at" 4
+.IX Item "$tstamp = $timer->at"
+Return the time this watcher will fire next.
+.ie n .IP "$timer = $timer\->set ($tstamp)" 4
+.el .IP "$timer = \f(CW$timer\fR\->set ($tstamp)" 4
+.IX Item "$timer = $timer->set ($tstamp)"
+Set the time the event is generated to \f(CW$tstamp\fR.
+.ie n .IP "$timer = $timer\->start" 4
+.el .IP "$timer = \f(CW$timer\fR\->start" 4
+.IX Item "$timer = $timer->start"
+Start the timer.
+.ie n .IP "$timer = $timer\->start ($tstamp)" 4
+.el .IP "$timer = \f(CW$timer\fR\->start ($tstamp)" 4
+.IX Item "$timer = $timer->start ($tstamp)"
+Set the event trigger time to \f(CW$tstamp\fR and start the timer.
+.ie n .IP "$timer = $timer\->stop" 4
+.el .IP "$timer = \f(CW$timer\fR\->stop" 4
+.IX Item "$timer = $timer->stop"
+Stop the timer.
+.ie n .Sh "The ""urxvt::iow"" Class"
+.el .Sh "The \f(CWurxvt::iow\fP Class"
+.IX Subsection "The urxvt::iow Class"
+This class implements io watchers/events. Example:
+.PP
+.Vb 12
+\& $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;
+\& });
+.Ve
+.IP "$iow = new urxvt::iow" 4
+.IX Item "$iow = new urxvt::iow"
+Create a new io watcher object in stopped state.
+.ie n .IP "$iow = $iow\fR\->cb (sub { my ($iow, \f(CW$reventmask\fR) = \f(CW@_; ... })" 4
+.el .IP "$iow = \f(CW$iow\fR\->cb (sub { my ($iow, \f(CW$reventmask\fR) = \f(CW@_\fR; ... })" 4
+.IX Item "$iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })"
+Set the callback to be called when io events are triggered. \f(CW$reventmask\fR
+is a bitset as described in the \f(CW\*(C`events\*(C'\fR method.
+.ie n .IP "$iow = $iow\->fd ($fd)" 4
+.el .IP "$iow = \f(CW$iow\fR\->fd ($fd)" 4
+.IX Item "$iow = $iow->fd ($fd)"
+Set the filedescriptor (not handle) to watch.
+.ie n .IP "$iow = $iow\->events ($eventmask)" 4
+.el .IP "$iow = \f(CW$iow\fR\->events ($eventmask)" 4
+.IX Item "$iow = $iow->events ($eventmask)"
+Set the event mask to watch. Bit #0 (value \f(CW1\fR) enables watching for read
+data, Bit #1 (value \f(CW2\fR) enables watching for write data.
+.ie n .IP "$iow = $iow\->start" 4
+.el .IP "$iow = \f(CW$iow\fR\->start" 4
+.IX Item "$iow = $iow->start"
+Start watching for requested events on the given handle.
+.ie n .IP "$iow = $iow\->stop" 4
+.el .IP "$iow = \f(CW$iow\fR\->stop" 4
+.IX Item "$iow = $iow->stop"
+Stop watching for events on the given filehandle.
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+.Vb 2
+\& Marc Lehmann <pcg@goof.com>
+\& http://software.schmorp.de/pkg/rxvt-unicode
+.Ve
projects / dana / urxvt.git / commitdiff