this still fares rather well. And compared to some monsters like
gnome-terminal (21152k + extra 4204k in separate processes) or
konsole (22200k + extra 43180k in daemons that stay around after
- exit, plus half aminute of startup time, including the hundreds of
+ exit, plus half a minute of startup time, including the hundreds of
warnings it spits out), it fares extremely well *g*.
Why C++, isn't that unportable/bloated/uncool?
</dd>
<dd>
<p>Extension names can be prefixed with a <code>-</code> sign to prohibit using
-it. This can be useful to selectively disable some extensions loaded
+them. This can be useful to selectively disable some extensions loaded
by default, or specified via the <code>perl-ext-common</code> resource. For
example, <code>default,-selection</code> will use all the default extension except
<code>selection</code>.</p>
</dd>
<dd>
+<p>Extension names can also be followed by an argument in angle brackets
+(e.g. <code>searchable-scrollback<M-s></code>, which binds the hotkey for
+searchable scorllback to Alt/Meta-s). Mentioning the same extension
+multiple times with different arguments will pass multiple arguments to
+the extension.</p>
+</dd>
+<dd>
<p>Each extension is looked up in the library directories, loaded if
necessary, and bound to the current terminal instance.</p>
</dd>
.\" ========================================================================
.\"
.IX Title "rxvt 1"
-.TH rxvt 1 "2006-01-09" "6.3" "RXVT-UNICODE"
+.TH rxvt 1 "2006-01-10" "6.3" "RXVT-UNICODE"
.SH "NAME"
rxvt\-unicode (ouR XVT, unicode) \- (a VT102 emulator for the X window system)
.SH "SYNOPSIS"
use in this terminal instance; option \fB\-pe\fR.
.Sp
Extension names can be prefixed with a \f(CW\*(C`\-\*(C'\fR sign to prohibit using
-it. This can be useful to selectively disable some extensions loaded
+them. This can be useful to selectively disable some extensions loaded
by default, or specified via the \f(CW\*(C`perl\-ext\-common\*(C'\fR resource. For
example, \f(CW\*(C`default,\-selection\*(C'\fR will use all the default extension except
\&\f(CW\*(C`selection\*(C'\fR.
.Sp
+Extension names can also be followed by an argument in angle brackets
+(e.g. \f(CW\*(C`searchable\-scrollback<M\-s>\*(C'\fR, which binds the hotkey for
+searchable scorllback to Alt/Meta\-s). Mentioning the same extension
+multiple times with different arguments will pass multiple arguments to
+the extension.
+.Sp
Each extension is looked up in the library directories, loaded if
necessary, and bound to the current terminal instance.
.Sp
"default") to use in this terminal instance; option -pe.
Extension names can be prefixed with a "-" sign to prohibit using
- it. This can be useful to selectively disable some extensions loaded
- by default, or specified via the "perl-ext-common" resource. For
- example, "default,-selection" will use all the default extension
+ them. This can be useful to selectively disable some extensions
+ loaded by default, or specified via the "perl-ext-common" resource.
+ For example, "default,-selection" will use all the default extension
except "selection".
+ Extension names can also be followed by an argument in angle
+ brackets (e.g. "searchable-scrollback<M-s>", which binds the hotkey
+ for searchable scorllback to Alt/Meta-s). Mentioning the same
+ extension multiple times with different arguments will pass multiple
+ arguments to the extension.
+
Each extension is looked up in the library directories, loaded if
necessary, and bound to the current terminal instance.
<p>Compared to e.g. Eterm (5112k), aterm (3132k) and xterm (4680k), this
still fares rather well. And compared to some monsters like gnome-terminal
(21152k + extra 4204k in separate processes) or konsole (22200k + extra
-43180k in daemons that stay around after exit, plus half aminute of
+43180k in daemons that stay around after exit, plus half a minute of
startup time, including the hundreds of warnings it spits out), it fares
extremely well *g*.</p>
</dd>
.\" ========================================================================
.\"
.IX Title "rxvt 7"
-.TH rxvt 7 "2006-01-09" "6.3" "RXVT-UNICODE"
+.TH rxvt 7 "2006-01-10" "6.3" "RXVT-UNICODE"
.SH "NAME"
RXVT REFERENCE \- FAQ, command sequences and other background information
.SH "SYNOPSIS"
Compared to e.g. Eterm (5112k), aterm (3132k) and xterm (4680k), this
still fares rather well. And compared to some monsters like gnome-terminal
(21152k + extra 4204k in separate processes) or konsole (22200k + extra
-43180k in daemons that stay around after exit, plus half aminute of
+43180k in daemons that stay around after exit, plus half a minute of
startup time, including the hundreds of warnings it spits out), it fares
extremely well *g*.
.IP "Why \*(C+, isn't that unportable/bloated/uncool?" 4
this still fares rather well. And compared to some monsters like
gnome-terminal (21152k + extra 4204k in separate processes) or
konsole (22200k + extra 43180k in daemons that stay around after
- exit, plus half aminute of startup time, including the hundreds of
+ exit, plus half a minute of startup time, including the hundreds of
warnings it spits out), it fares extremely well *g*.
Why C++, isn't that unportable/bloated/uncool?
<li><a href="#prepackaged_extensions">Prepackaged Extensions</a></li>
<li><a href="#general_api_considerations">General API Considerations</a></li>
+ <li><a href="#extension_objects">Extension Objects</a></li>
<li><a href="#hooks">Hooks</a></li>
<li><a href="#variables_in_the_urxvt_package">Variables in the <code>urxvt</code> Package</a></li>
<li><a href="#functions_in_the_urxvt_package">Functions in the <code>urxvt</code> Package</a></li>
text into various other formats/action.
</dd>
<p></p>
+<dt><strong><a name="item_searchable_2dscrollback_3chotkey_3e__28enabled_by_">searchable-scrollback<hotkey> (enabled by default)</a></strong><br />
+</dt>
+<dd>
+Adds regex search functionality to the scrollback buffer, triggered
+by a hotkey (default: <code>M-s</code>). When in search mode, normal terminal
+input/output is suspended.
+</dd>
+<dd>
+<p><code>/</code> starts an incremental regex search, <code>n</code> searches further, <code>p</code> or
+<code>N</code> jump to the previous match, <code>G</code> jumps to the bottom and clears the
+history, <code>enter</code> leaves search mode at the current position and <code>escape</code>
+returns to the original position.</p>
+</dd>
+<p></p>
<dt><strong><a name="item_digital_2dclock">digital-clock</a></strong><br />
</dt>
<dd>
<p></p></dl>
<p>
</p>
+<h2><a name="extension_objects">Extension Objects</a></h2>
+<p>Very perl extension is a perl class. A separate perl object is created
+for each terminal and each extension and passed as the first parameter to
+hooks. So extensions can use their <code>$self</code> object without having to think
+about other extensions, with the exception of methods and members that
+begin with an underscore character <code>_</code>: these are reserved for internal
+use.</p>
+<p>Although it isn't a <code>urxvt::term</code> object, you can call all methods of the
+<code>urxvt::term</code> class on this object.</p>
+<p>It has the following methods and data members:</p>
+<dl>
+<dt><strong><a name="item__24urxvt_term__3d__24self_2d_3e_7bterm_7d">$urxvt_term = $self->{term}</a></strong><br />
+</dt>
+<dd>
+Returns the <code>urxvt::term</code> object associated with this instance of the
+extension. This member <em>must not</em> be changed in any way.
+</dd>
+<p></p>
+<dt><strong><a name="item_enable">$self->enable ($hook_name => $cb, [$hook_name => $cb..])</a></strong><br />
+</dt>
+<dd>
+Dynamically enable the given hooks (named without the <code>on_</code> prefix) for
+this extension, replacing any previous hook. This is useful when you want
+to overwrite time-critical hooks only temporarily.
+</dd>
+<p></p>
+<dt><strong><a name="item_disable">$self->disable ($hook_name[, $hook_name..])</a></strong><br />
+</dt>
+<dd>
+Dynamically disable the given hooks.
+</dd>
+<p></p></dl>
+<p>
+</p>
<h2><a name="hooks">Hooks</a></h2>
<p>The following subroutines can be declared in extension files, and will be
called whenever the relevant event happens.</p>
-<p>The first argument passed to them is an object private to each terminal
-and extension package. You can call all <code>urxvt::term</code> methods on it, but
-its not a real <code>urxvt::term</code> object. Instead, the real <code>urxvt::term</code>
-object that is shared between all packages is stored in the <code>term</code>
-member. It is, however, blessed intot he package of the extension script,
-so for all practical purposes you can treat an extension script as a class.</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>
+<p>The first argument passed to them is an extension oject as described in
+the in the <code>Extension Objects</code> section.</p>
+<p><strong>All</strong> of these hooks 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><em>When in doubt, return a false value (preferably <code>()</code>). </em>></p>
<dl>
<dt><strong><a name="item_on_init__24term">on_init $term</a></strong><br />
</dt>
output.
</dd>
<p></p>
+<dt><strong><a name="item_on_tt_write__24term_2c__24octets">on_tt_write $term, $octets</a></strong><br />
+</dt>
+<dd>
+Called whenever some data is written to the tty/pty and can be used to
+suppress or filter tty input.
+</dd>
+<p></p>
<dt><strong><a name="item_on_line_update__24term_2c__24row">on_line_update $term, $row</a></strong><br />
</dt>
<dd>
focus out processing.
</dd>
<p></p>
-<dt><strong><a name="item_on_key_press__24term_2c__24event_2c__24octets">on_key_press $term, $event, $octets</a></strong><br />
+<dt><strong><a name="item_on_key_press__24term_2c__24event_2c__24keysym_2c__">on_key_press $term, $event, $keysym, $octets</a></strong><br />
</dt>
-<dt><strong><a name="item_on_key_release__24term_2c__24event">on_key_release $term, $event</a></strong><br />
+<dt><strong><a name="item_on_key_release__24term_2c__24event_2c__24keysym">on_key_release $term, $event, $keysym</a></strong><br />
</dt>
<dt><strong><a name="item_on_button_press__24term_2c__24event">on_button_press $term, $event</a></strong><br />
</dt>
utmpInhibit visualBell</pre>
</dd>
<p></p>
+<dt><strong><a name="item_parse_keysym">$success = $term->parse_keysym ($keysym_spec, $command_string)</a></strong><br />
+</dt>
+<dd>
+Adds a keymap translation exactly as specified via a resource. See the
+<code>keysym</code> resource in the <code>rxvt(1)</code> manpage.
+</dd>
+<p></p>
<dt><strong><a name="item_rstyle">$rend = $term->rstyle ([$new_rstyle])</a></strong><br />
</dt>
<dd>
<dd>
Return the current selection text and optionally replace it by <code>$newtext</code>.
</dd>
+<p></p>
+<dt><strong><a name="item_overlay_simple">$term->overlay_simple ($x, $y, $text)</a></strong><br />
+</dt>
<dd>
-<p>#=item $term->overlay ($x, $y, $text)
-#
-#Create a simple multi-line overlay box. See the next method for details.
-#
-#=cut
-#
-#sub urxvt::term::scr_overlay {
-# my ($self, $x, $y, $text) = @_;
-#
-# my @lines = split /\n/, $text;
-#
-# my $w = 0;
-# for (map $self->strwidth ($_), @lines) {
-# $w = $_ if $w < $_;
-# }
-#
-# $self->scr_overlay_new ($x, $y, $w, scalar @lines);
-# $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
-#}</p>
+Create a simple multi-line overlay box. See the next method for details.
</dd>
<p></p>
<dt><strong><a name="item_overlay">$term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])</a></strong><br />
Convert the given locale-encoded octets into a perl string.
</dd>
<p></p>
+<dt><strong><a name="item_scr_xor_span">$term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])</a></strong><br />
+</dt>
+<dd>
+XORs the rendition values in the given span with the provided value
+(default: <code>RS_RVid</code>). Useful in refresh hooks to provide effects similar
+to the selection.
+</dd>
+<p></p>
+<dt><strong><a name="item_scr_xor_rect">$term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, $rstyle2]])</a></strong><br />
+</dt>
+<dd>
+Similar to <a href="#item_scr_xor_span"><code>scr_xor_span</code></a>, but xors a rectangle instead. Trailing
+whitespace will additionally be xored with the <code>$rstyle2</code>, which defaults
+to <code>RS_RVid | RS_Uline</code>, which removes reverse video again and underlines
+it instead.
+</dd>
+<p></p>
+<dt><strong><a name="item_scr_bell">$term->scr_bell</a></strong><br />
+</dt>
+<dd>
+Ring the bell!
+</dd>
+<p></p>
<dt><strong><a name="item_scr_add_lines">$term->scr_add_lines ($string)</a></strong><br />
</dt>
<dd>
to the locale-specific encoding using <a href="#item_locale_encode"><code>$term->locale_encode</code></a>.
</dd>
<p></p>
+<dt><strong><a name="item_pty_ev_events">$old_events = $term->pty_ev_events ([$new_events])</a></strong><br />
+</dt>
+<dd>
+Replaces the event mask of the pty watcher by the given event mask. Can
+be used to suppress input and output handling to the pty/tty. See the
+description of <a href="#item_events"><code>urxvt::timer->events</code></a>. Make sure to always restore
+the previous value.
+</dd>
+<p></p>
<dt><strong><a name="item_parent">$windowid = $term->parent</a></strong><br />
</dt>
<dd>
Return various integers describing terminal characteristics.
</dd>
<p></p>
+<dt><strong><a name="item_locale">$lc_ctype = $term->locale</a></strong><br />
+</dt>
+<dd>
+Returns the LC_CTYPE category string used by this rxvt-unicode.
+</dd>
+<p></p>
+<dt><strong><a name="item_display_id">$x_display = $term->display_id</a></strong><br />
+</dt>
+<dd>
+Return the DISPLAY used by rxvt-unicode.
+</dd>
+<p></p>
<dt><strong><a name="item_modlevel3mask">$modifiermask = $term->ModLevel3Mask</a></strong><br />
</dt>
<dt><strong><a name="item_modmetamask">$modifiermask = $term->ModMetaMask</a></strong><br />
$term->{iow} = urxvt::iow
->new
->fd (fileno $term->{socket})
- ->events (1) # wait for read data
+ ->events (urxvt::EVENT_READ)
->start
->cb (sub {
my ($iow, $revents) = @_;
<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.
+Set the event mask to watch. The only allowed values are
+<code>urxvt::EVENT_READ</code> and <code>urxvt::EVENT_WRITE</code>, which might be ORed
+together, or <code>urxvt::EVENT_NONE</code>.
</dd>
<p></p>
<dt><strong>$iow = $iow->start</strong><br />
.\" ========================================================================
.\"
.IX Title "rxvt 3"
-.TH rxvt 3 "2006-01-09" "6.3" "RXVT-UNICODE"
+.TH rxvt 3 "2006-01-10" "6.3" "RXVT-UNICODE"
.SH "NAME"
@@RXVT_NAME@@perl \- rxvt\-unicode's embedded perl interpreter
.SH "SYNOPSIS"
.IX Item "selection-popup (enabled by default)"
Binds a popup menu to Ctrl\-Button3 that lets you convert the selection
text into various other formats/action.
+.IP "searchable\-scrollback<hotkey> (enabled by default)" 4
+.IX Item "searchable-scrollback<hotkey> (enabled by default)"
+Adds regex search functionality to the scrollback buffer, triggered
+by a hotkey (default: \f(CW\*(C`M\-s\*(C'\fR). When in search mode, normal terminal
+input/output is suspended.
+.Sp
+\&\f(CW\*(C`/\*(C'\fR starts an incremental regex search, \f(CW\*(C`n\*(C'\fR searches further, \f(CW\*(C`p\*(C'\fR or
+\&\f(CW\*(C`N\*(C'\fR jump to the previous match, \f(CW\*(C`G\*(C'\fR jumps to the bottom and clears the
+history, \f(CW\*(C`enter\*(C'\fR leaves search mode at the current position and \f(CW\*(C`escape\*(C'\fR
+returns to the original position.
.IP "digital-clock" 4
.IX Item "digital-clock"
Displays a digital clock using the built-in overlay.
.IX Item "$octets"
Either binary data or \- more common \- a text string encoded in a
locale-specific way.
+.Sh "Extension Objects"
+.IX Subsection "Extension Objects"
+Very perl extension is a perl class. A separate perl object is created
+for each terminal and each extension and passed as the first parameter to
+hooks. So extensions can use their \f(CW$self\fR object without having to think
+about other extensions, with the exception of methods and members that
+begin with an underscore character \f(CW\*(C`_\*(C'\fR: these are reserved for internal
+use.
+.PP
+Although it isn't a \f(CW\*(C`urxvt::term\*(C'\fR object, you can call all methods of the
+\&\f(CW\*(C`urxvt::term\*(C'\fR class on this object.
+.PP
+It has the following methods and data members:
+.ie n .IP "$urxvt_term = $self\->{term}" 4
+.el .IP "$urxvt_term = \f(CW$self\fR\->{term}" 4
+.IX Item "$urxvt_term = $self->{term}"
+Returns the \f(CW\*(C`urxvt::term\*(C'\fR object associated with this instance of the
+extension. This member \fImust not\fR be changed in any way.
+.ie n .IP "$self\->enable ($hook_name => $cb\fR, [$hook_name => \f(CW$cb..])" 4
+.el .IP "$self\->enable ($hook_name => \f(CW$cb\fR, [$hook_name => \f(CW$cb\fR..])" 4
+.IX Item "$self->enable ($hook_name => $cb, [$hook_name => $cb..])"
+Dynamically enable the given hooks (named without the \f(CW\*(C`on_\*(C'\fR prefix) for
+this extension, replacing any previous hook. This is useful when you want
+to overwrite time-critical hooks only temporarily.
+.ie n .IP "$self\->disable ($hook_name[, $hook_name..])" 4
+.el .IP "$self\->disable ($hook_name[, \f(CW$hook_name\fR..])" 4
+.IX Item "$self->disable ($hook_name[, $hook_name..])"
+Dynamically disable the given hooks.
.Sh "Hooks"
.IX Subsection "Hooks"
The following subroutines can be declared in extension files, and will be
called whenever the relevant event happens.
.PP
-The first argument passed to them is an object private to each terminal
-and extension package. You can call all \f(CW\*(C`urxvt::term\*(C'\fR methods on it, but
-its not a real \f(CW\*(C`urxvt::term\*(C'\fR object. Instead, the real \f(CW\*(C`urxvt::term\*(C'\fR
-object that is shared between all packages is stored in the \f(CW\*(C`term\*(C'\fR
-member. It is, however, blessed intot he package of the extension script,
-so for all practical purposes you can treat an extension script as a class.
+The first argument passed to them is an extension oject as described in
+the in the \f(CW\*(C`Extension Objects\*(C'\fR section.
.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.
+\&\fBAll\fR of these hooks 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).
+\&\fIWhen in doubt, return a false value (preferably \f(CI\*(C`()\*(C'\fI).\fR
.ie n .IP "on_init $term" 4
.el .IP "on_init \f(CW$term\fR" 4
.IX Item "on_init $term"
and calling \f(CW\*(C`$term\->scr_add_lines\*(C'\fR yourself. Please note that this
might be very slow, however, as your hook is called for \fBall\fR text being
output.
+.ie n .IP "on_tt_write $term\fR, \f(CW$octets" 4
+.el .IP "on_tt_write \f(CW$term\fR, \f(CW$octets\fR" 4
+.IX Item "on_tt_write $term, $octets"
+Called whenever some data is written to the tty/pty and can be used to
+suppress or filter tty input.
.ie n .IP "on_line_update $term\fR, \f(CW$row" 4
.el .IP "on_line_update \f(CW$term\fR, \f(CW$row\fR" 4
.IX Item "on_line_update $term, $row"
.IX Item "on_focus_out $term"
Called wheneever the window loses keyboard focus, before rxvt-unicode does
focus out processing.
-.ie n .IP "on_key_press $term\fR, \f(CW$event\fR, \f(CW$octets" 4
-.el .IP "on_key_press \f(CW$term\fR, \f(CW$event\fR, \f(CW$octets\fR" 4
-.IX Item "on_key_press $term, $event, $octets"
+.ie n .IP "on_key_press $term\fR, \f(CW$event\fR, \f(CW$keysym\fR, \f(CW$octets" 4
+.el .IP "on_key_press \f(CW$term\fR, \f(CW$event\fR, \f(CW$keysym\fR, \f(CW$octets\fR" 4
+.IX Item "on_key_press $term, $event, $keysym, $octets"
.PD 0
-.ie n .IP "on_key_release $term\fR, \f(CW$event" 4
-.el .IP "on_key_release \f(CW$term\fR, \f(CW$event\fR" 4
-.IX Item "on_key_release $term, $event"
+.ie n .IP "on_key_release $term\fR, \f(CW$event\fR, \f(CW$keysym" 4
+.el .IP "on_key_release \f(CW$term\fR, \f(CW$event\fR, \f(CW$keysym\fR" 4
+.IX Item "on_key_release $term, $event, $keysym"
.ie n .IP "on_button_press $term\fR, \f(CW$event" 4
.el .IP "on_button_press \f(CW$term\fR, \f(CW$event\fR" 4
.IX Item "on_button_press $term, $event"
\& shade term_name title transparent transparent_all tripleclickwords
\& utmpInhibit visualBell
.Ve
+.ie n .IP "$success = $term\fR\->parse_keysym ($keysym_spec, \f(CW$command_string)" 4
+.el .IP "$success = \f(CW$term\fR\->parse_keysym ($keysym_spec, \f(CW$command_string\fR)" 4
+.IX Item "$success = $term->parse_keysym ($keysym_spec, $command_string)"
+Adds a keymap translation exactly as specified via a resource. See the
+\&\f(CW\*(C`keysym\*(C'\fR resource in the @@RXVT_NAME@@(1) manpage.
.ie n .IP "$rend = $term\->rstyle ([$new_rstyle])" 4
.el .IP "$rend = \f(CW$term\fR\->rstyle ([$new_rstyle])" 4
.IX Item "$rend = $term->rstyle ([$new_rstyle])"
.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.
-.Sp
-#=item \f(CW$term\fR\->overlay ($x, \f(CW$y\fR, \f(CW$text\fR)
-#
-#Create a simple multi-line overlay box. See the next method for details.
-#
-#=cut
-#
-#sub urxvt::term::scr_overlay {
-# my ($self, \f(CW$x\fR, \f(CW$y\fR, \f(CW$text\fR) = \f(CW@_\fR;
-#
-# my \f(CW@lines\fR = split /\en/, \f(CW$text\fR;
-#
-# my \f(CW$w\fR = 0;
-# for (map \f(CW$self\fR\->strwidth ($_), \f(CW@lines\fR) {
-# \f(CW$w\fR = \f(CW$_\fR if \f(CW$w\fR < \f(CW$_\fR;
-# }
-#
-# \f(CW$self\fR\->scr_overlay_new ($x, \f(CW$y\fR, \f(CW$w\fR, scalar \f(CW@lines\fR);
-# \f(CW$self\fR\->scr_overlay_set (0, \f(CW$_\fR, \f(CW$lines\fR[$_]) for 0.. $#lines;
-#}
+.ie n .IP "$term\->overlay_simple ($x, $y\fR, \f(CW$text)" 4
+.el .IP "$term\->overlay_simple ($x, \f(CW$y\fR, \f(CW$text\fR)" 4
+.IX Item "$term->overlay_simple ($x, $y, $text)"
+Create a simple multi-line overlay box. See the next method for details.
.ie n .IP "$term\->overlay ($x, $y\fR, \f(CW$width\fR, \f(CW$height\fR[, \f(CW$rstyle\fR[, \f(CW$border]])" 4
.el .IP "$term\->overlay ($x, \f(CW$y\fR, \f(CW$width\fR, \f(CW$height\fR[, \f(CW$rstyle\fR[, \f(CW$border\fR]])" 4
.IX Item "$term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])"
.el .IP "$string = \f(CW$term\fR\->locale_decode ($octets)" 4
.IX Item "$string = $term->locale_decode ($octets)"
Convert the given locale-encoded octets into a perl string.
+.ie n .IP "$term\->scr_xor_span ($beg_row, $beg_col\fR, \f(CW$end_row\fR, \f(CW$end_col\fR[, \f(CW$rstyle])" 4
+.el .IP "$term\->scr_xor_span ($beg_row, \f(CW$beg_col\fR, \f(CW$end_row\fR, \f(CW$end_col\fR[, \f(CW$rstyle\fR])" 4
+.IX 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: \f(CW\*(C`RS_RVid\*(C'\fR). Useful in refresh hooks to provide effects similar
+to the selection.
+.ie n .IP "$term\->scr_xor_rect ($beg_row, $beg_col\fR, \f(CW$end_row\fR, \f(CW$end_col\fR[, \f(CW$rstyle1\fR[, \f(CW$rstyle2]])" 4
+.el .IP "$term\->scr_xor_rect ($beg_row, \f(CW$beg_col\fR, \f(CW$end_row\fR, \f(CW$end_col\fR[, \f(CW$rstyle1\fR[, \f(CW$rstyle2\fR]])" 4
+.IX Item "$term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, $rstyle2]])"
+Similar to \f(CW\*(C`scr_xor_span\*(C'\fR, but xors a rectangle instead. Trailing
+whitespace will additionally be xored with the \f(CW$rstyle2\fR, which defaults
+to \f(CW\*(C`RS_RVid | RS_Uline\*(C'\fR, which removes reverse video again and underlines
+it instead.
+.IP "$term\->scr_bell" 4
+.IX Item "$term->scr_bell"
+Ring the bell!
.IP "$term\->scr_add_lines ($string)" 4
.IX Item "$term->scr_add_lines ($string)"
Write the given text string to the screen, as if output by the application
Write the octets given in \f(CW$data\fR to the tty (i.e. as program input). To
pass characters instead of octets, you should convert your strings first
to the locale-specific encoding using \f(CW\*(C`$term\->locale_encode\*(C'\fR.
+.ie n .IP "$old_events = $term\->pty_ev_events ([$new_events])" 4
+.el .IP "$old_events = \f(CW$term\fR\->pty_ev_events ([$new_events])" 4
+.IX Item "$old_events = $term->pty_ev_events ([$new_events])"
+Replaces the event mask of the pty watcher by the given event mask. Can
+be used to suppress input and output handling to the pty/tty. See the
+description of \f(CW\*(C`urxvt::timer\->events\*(C'\fR. Make sure to always restore
+the previous value.
.ie n .IP "$windowid = $term\->parent" 4
.el .IP "$windowid = \f(CW$term\fR\->parent" 4
.IX Item "$windowid = $term->parent"
.IX Item "$lines_in_scrollback = $term->nsaved"
.PD
Return various integers describing terminal characteristics.
+.ie n .IP "$lc_ctype = $term\->locale" 4
+.el .IP "$lc_ctype = \f(CW$term\fR\->locale" 4
+.IX Item "$lc_ctype = $term->locale"
+Returns the \s-1LC_CTYPE\s0 category string used by this rxvt\-unicode.
+.ie n .IP "$x_display = $term\->display_id" 4
+.el .IP "$x_display = \f(CW$term\fR\->display_id" 4
+.IX Item "$x_display = $term->display_id"
+Return the \s-1DISPLAY\s0 used by rxvt\-unicode.
.ie n .IP "$modifiermask = $term\->ModLevel3Mask" 4
.el .IP "$modifiermask = \f(CW$term\fR\->ModLevel3Mask" 4
.IX Item "$modifiermask = $term->ModLevel3Mask"
\& $term->{iow} = urxvt::iow
\& ->new
\& ->fd (fileno $term->{socket})
-\& ->events (1) # wait for read data
+\& ->events (urxvt::EVENT_READ)
\& ->start
\& ->cb (sub {
\& my ($iow, $revents) = @_;
.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.
+Set the event mask to watch. The only allowed values are
+\&\f(CW\*(C`urxvt::EVENT_READ\*(C'\fR and \f(CW\*(C`urxvt::EVENT_WRITE\*(C'\fR, which might be ORed
+together, or \f(CW\*(C`urxvt::EVENT_NONE\*(C'\fR.
.ie n .IP "$iow = $iow\->start" 4
.el .IP "$iow = \f(CW$iow\fR\->start" 4
.IX Item "$iow = $iow->start"
Binds a popup menu to Ctrl-Button3 that lets you convert the
selection text into various other formats/action.
+ searchable-scrollback<hotkey> (enabled by default)
+ Adds regex search functionality to the scrollback buffer, triggered
+ by a hotkey (default: "M-s"). When in search mode, normal terminal
+ input/output is suspended.
+
+ "/" starts an incremental regex search, "n" searches further, "p" or
+ "N" jump to the previous match, "G" jumps to the bottom and clears
+ the history, "enter" leaves search mode at the current position and
+ "escape" returns to the original position.
+
digital-clock
Displays a digital clock using the built-in overlay.
Either binary data or - more common - a text string encoded in a
locale-specific way.
+ Extension Objects
+ Very perl extension is a perl class. A separate perl object is created
+ for each terminal and each extension and passed as the first parameter
+ to hooks. So extensions can use their $self object without having to
+ think about other extensions, with the exception of methods and members
+ that begin with an underscore character "_": these are reserved for
+ internal use.
+
+ Although it isn't a "urxvt::term" object, you can call all methods of
+ the "urxvt::term" class on this object.
+
+ It has the following methods and data members:
+
+ $urxvt_term = $self->{term}
+ Returns the "urxvt::term" object associated with this instance of
+ the extension. This member *must not* be changed in any way.
+
+ $self->enable ($hook_name => $cb, [$hook_name => $cb..])
+ Dynamically enable the given hooks (named without the "on_" prefix)
+ for this extension, replacing any previous hook. This is useful when
+ you want to overwrite time-critical hooks only temporarily.
+
+ $self->disable ($hook_name[, $hook_name..])
+ Dynamically disable the given hooks.
+
Hooks
The following subroutines can be declared in extension files, 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 "urxvt::term" methods on it, but
- its not a real "urxvt::term" object. Instead, the real "urxvt::term"
- object that is shared between all packages is stored in the "term"
- member. It is, however, blessed intot he package of the extension
- script, so for all practical purposes you can treat an extension script
- as a class.
+ The first argument passed to them is an extension oject as described in
+ the in the "Extension Objects" section.
- 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
+ All of these hooks 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 "()").
+ *When in doubt, return a false value (preferably "()").*
on_init $term
Called after a new terminal object has been initialized, but before
Please note that this might be very slow, however, as your hook is
called for all text being output.
+ on_tt_write $term, $octets
+ Called whenever some data is written to the tty/pty and can be used
+ to suppress or filter tty input.
+
on_line_update $term, $row
Called whenever a line was updated or changed. Can be used to filter
screen output (e.g. underline urls or other useless stuff). Only
Called wheneever the window loses keyboard focus, before
rxvt-unicode does focus out processing.
- on_key_press $term, $event, $octets
- on_key_release $term, $event
+ on_key_press $term, $event, $keysym, $octets
+ on_key_release $term, $event, $keysym
on_button_press $term, $event
on_button_release $term, $event
on_motion_notify $term, $event
shade term_name title transparent transparent_all tripleclickwords
utmpInhibit visualBell
+ $success = $term->parse_keysym ($keysym_spec, $command_string)
+ Adds a keymap translation exactly as specified via a resource. See
+ the "keysym" resource in the rxvt(1) manpage.
+
$rend = $term->rstyle ([$new_rstyle])
Return and optionally change the current rendition. Text that is
output by the terminal application will use this style.
Return the current selection text and optionally replace it by
$newtext.
- #=item $term->overlay ($x, $y, $text) # #Create a simple multi-line
- overlay box. See the next method for details. # #=cut # #sub
- urxvt::term::scr_overlay { # my ($self, $x, $y, $text) = @_; # # my
- @lines = split /\n/, $text; # # my $w = 0; # for (map
- $self->strwidth ($_), @lines) { # $w = $_ if $w < $_; # } # #
- $self->scr_overlay_new ($x, $y, $w, scalar @lines); #
- $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; #}
+ $term->overlay_simple ($x, $y, $text)
+ Create a simple multi-line overlay box. See the next method for
+ details.
$term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
Create a new (empty) overlay at the given position with the given
$string = $term->locale_decode ($octets)
Convert the given locale-encoded octets into a perl string.
+ $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: "RS_RVid"). Useful in refresh hooks to provide effects
+ similar to the selection.
+
+ $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[,
+ $rstyle2]])
+ Similar to "scr_xor_span", but xors a rectangle instead. Trailing
+ whitespace will additionally be xored with the $rstyle2, which
+ defaults to "RS_RVid | RS_Uline", which removes reverse video again
+ and underlines it instead.
+
+ $term->scr_bell
+ Ring the bell!
+
$term->scr_add_lines ($string)
Write the given text string to the screen, as if output by the
application running inside the terminal. It may not contain command
strings first to the locale-specific encoding using
"$term->locale_encode".
+ $old_events = $term->pty_ev_events ([$new_events])
+ Replaces the event mask of the pty watcher by the given event mask.
+ Can be used to suppress input and output handling to the pty/tty.
+ See the description of "urxvt::timer->events". Make sure to always
+ restore the previous value.
+
$windowid = $term->parent
Return the window id of the toplevel window.
$lines_in_scrollback = $term->nsaved
Return various integers describing terminal characteristics.
+ $lc_ctype = $term->locale
+ Returns the LC_CTYPE category string used by this rxvt-unicode.
+
+ $x_display = $term->display_id
+ Return the DISPLAY used by rxvt-unicode.
+
$modifiermask = $term->ModLevel3Mask
$modifiermask = $term->ModMetaMask
$modifiermask = $term->ModNumLockMask
$term->{iow} = urxvt::iow
->new
->fd (fileno $term->{socket})
- ->events (1) # wait for read data
+ ->events (urxvt::EVENT_READ)
->start
->cb (sub {
my ($iow, $revents) = @_;
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.
+ Set the event mask to watch. The only allowed values are
+ "urxvt::EVENT_READ" and "urxvt::EVENT_WRITE", which might be
+ ORed together, or "urxvt::EVENT_NONE".
$iow = $iow->start
Start watching for requested events on the given handle.
);
$self->{manpage_overlay} = $self->overlay (0, -2, $self->ncol, 1, urxvt::OVERLAY_RSTYLE, 0);
- $self->{manpage_overlay}->set (0, 0, "scrollback search, see man ${urxvt::RXVTNAME}perl for details");
+ $self->{manpage_overlay}->set (0, 0, "scrollback search, see the ${urxvt::RXVTNAME}perl manpage for details");
$self->idle;
}
else if (!strcmp (tok, "END"))
{
int success;
+
if (c.recv (success))
exit (success ? EXIT_SUCCESS : EXIT_FAILURE);
}
BOOT:
{
- sv_setsv (get_sv ("urxvt::LIBDIR", 1), newSVpvn (LIBDIR, sizeof (LIBDIR) - 1));
+ sv_setsv (get_sv ("urxvt::LIBDIR", 1), newSVpvn (LIBDIR, sizeof (LIBDIR) - 1));
+ sv_setsv (get_sv ("urxvt::RESNAME", 1), newSVpvn (RESNAME, sizeof (RESNAME) - 1));
+ sv_setsv (get_sv ("urxvt::RESCLASS", 1), newSVpvn (RESCLASS, sizeof (RESCLASS) - 1));
+ sv_setsv (get_sv ("urxvt::RXVTNAME", 1), newSVpvn (RXVTNAME, sizeof (RXVTNAME) - 1));
AV *hookname = get_av ("urxvt::HOOKNAME", 1);
# define def(sym) av_store (hookname, HOOK_ ## sym, newSVpv (# sym, 0));
Binds a popup menu to Ctrl-Button3 that lets you convert the selection
text into various other formats/action.
-=item searchable-scrollback (enabled by default)
+=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, terminal input/output is
-suspended, C</> starts an incremental regex search, C<n> searches further,
-C<p> jumps to the previous match. C<enter> leaves search mode at the
-current position and C<escape> returns to the original position.
+Adds regex search functionality to the scrollback buffer, triggered
+by a hotkey (default: C<M-s>). When in search mode, normal terminal
+input/output is suspended.
+
+C</> starts an incremental regex search, C<n> searches further, C<p> or
+C<N> jump to the previous match, C<G> jumps to the bottom and clears the
+history, C<enter> leaves search mode at the current position and C<escape>
+returns to the original position.
=item digital-clock
projects / dana / urxvt.git / commitdiff