<li><a href="#name">NAME</a></li>
<li><a href="#synopsis">SYNOPSIS</a></li>
<li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#packaged_extensions">PACKAGED EXTENSIONS</a></li>
<ul>
<li><a href="#general_api_considerations">General API Considerations</a></li>
<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="#rendition">RENDITION</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>
scripts will be shared (But not enabled) for all terminals.</p>
<p>
</p>
+<hr />
+<h1><a name="packaged_extensions">PACKAGED EXTENSIONS</a></h1>
+<p>This section describes the extensiosn delivered with this version. You can
+find them in <em>/opt/rxvt/lib/urxvt/perl/</em>.</p>
+<p>You can activate them like this:</p>
+<pre>
+ rxvt -pe <extensionname></pre>
+<dl>
+<dt><strong><a name="item_selection">selection</a></strong><br />
+</dt>
+<dd>
+Miscellaneous selection modifications.
+</dd>
+<dl>
+<dt><strong><a name="item_rot13">rot13</a></strong><br />
+</dt>
+<dd>
+Rot-13 the selection when activated. Used via keyboard trigger:
+</dd>
+<dd>
+<pre>
+ URxvt.keysym.C-M-r: perl:selection:rot13</pre>
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_digital_2dclock">digital-clock</a></strong><br />
+</dt>
+<dd>
+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.
+</dd>
+<p></p>
+<dt><strong><a name="item_simple_2doverlay_2dclock">simple-overlay-clock</a></strong><br />
+</dt>
+<dd>
+Displays a digital clock using the built-in overlay (colorful, useless).
+</dd>
+<p></p></dl>
+<p>
+</p>
<h2><a name="general_api_considerations">General API Considerations</a></h2>
<p>All objects (such as terminals, time watchers etc.) are typical
reference-to-hash objects. The hash can be used to store anything you
by the next method).
</dd>
<p></p>
-<dt><strong><a name="item_selection">$oldtext = $term->selection ([$newtext])</a></strong><br />
+<dt><strong>$oldtext = $term->selection ([$newtext])</strong><br />
</dt>
<dd>
Return the current selection text and optionally replace it by <code>$newtext</code>.
</dt>
<dd>
Write the octets given in <code>$data</code> to the tty (i.e. as program input). To
-pass characters instead of octets, you should convetr you strings first to
-the locale-specific encoding using <a href="#item_locale_encode"><code>$term->locale_encode</code></a>.
+pass characters instead of octets, you should convert your strings first
+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_nrow">$nrow = $term->nrow</a></strong><br />
+</dt>
+<dt><strong><a name="item_ncol">$ncol = $term->ncol</a></strong><br />
+</dt>
+<dd>
+Return the number of rows/columns of the terminal window (i.e. as
+specified by <code>-geometry</code>, excluding any scrollback).
+</dd>
+<p></p>
+<dt><strong><a name="item_nsaved">$nsaved = $term->nsaved</a></strong><br />
+</dt>
+<dd>
+Returns the number of lines in the scrollback buffer.
+</dd>
+<p></p>
+<dt><strong><a name="item_view_start">$view_start = $term->view_start ([$newvalue])</a></strong><br />
+</dt>
+<dd>
+Returns the negative row number of the topmost line. Minimum value is
+<code>0</code>, which displays the normal terminal contents. Larger values scroll
+this many lines into the scrollback buffer.
+</dd>
+<p></p>
+<dt><strong><a name="item_want_refresh">$term->want_refresh</a></strong><br />
+</dt>
+<dd>
+Requests a screen refresh. At the next opportunity, rxvt-unicode will
+compare the on-screen display with its stored representation. If they
+differ, it redraws the differences.
+</dd>
+<dd>
+<p>Used after changing terminal contents to display them.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_row_t">$text = $term->ROW_t ($row_number[, $new_text[, $start_col]])</a></strong><br />
+</dt>
+<dd>
+Returns the text of the entire row with number <code>$row_number</code>. Row <code>0</code>
+is the topmost terminal line, row <code>$term->$ncol-1</code> is the bottommost
+terminal line. The scrollback buffer starts at line <code>-1</code> and extends to
+line <a href="#item_nsaved"><code>-$term->nsaved</code></a>.
+</dd>
+<dd>
+<p>If <code>$new_text</code> is specified, it will replace characters in the current
+line, starting at column <code>$start_col</code> (default <code>0</code>), which is useful
+to replace only parts of a line. The font iindex in the rendition will
+automatically be updated.</p>
+</dd>
+<dd>
+<p><code>$text</code> is in a special encoding: tabs and wide characters that use more
+than one cell when displayed are padded with urxvt::NOCHAR characters
+(<code>chr 65535</code>). Characters with combining characters and other characters
+that do not fit into the normal tetx encoding will be replaced with
+characters in the private use area.</p>
+</dd>
+<dd>
+<p>You have to obey this encoding when changing text. The advantage is
+that <code>substr</code> and similar functions work on screen cells and not on
+characters.</p>
+</dd>
+<dd>
+<p>The methods <a href="#item_special_encode"><code>$term->special_encode</code></a> and <a href="#item_special_decode"><code>$term->special_decode</code></a>
+can be used to convert normal strings into this encoding and vice versa.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_row_r">$rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])</a></strong><br />
+</dt>
+<dd>
+Like <a href="#item_row_t"><code>$term->ROW_t</code></a>, but returns an arrayref with rendition
+bitsets. Rendition bitsets contain information about colour, font, font
+styles and similar information. See also <a href="#item_row_t"><code>$term->ROW_t</code></a>.
+</dd>
+<dd>
+<p>When setting rendition, the font mask will be ignored.</p>
+</dd>
+<dd>
+<p>See the section on RENDITION, below.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_row_l">$length = $term->ROW_l ($row_number[, $new_length])</a></strong><br />
+</dt>
+<dd>
+Returns the number of screen cells that are in use (``the line length''). If
+it is <code>-1</code>, then the line is part of a multiple-row logical ``line'', which
+means all characters are in use and it is continued on the next row.
+</dd>
+<p></p>
+<dt><strong><a name="item_special_encode">$text = $term->special_encode $string</a></strong><br />
+</dt>
+<dd>
+Converts a perl string into the special encoding used by rxvt-unicode,
+where one character corresponds to one screen cell. See
+<a href="#item_row_t"><code>$term->ROW_t</code></a> for details.
+</dd>
+<p></p>
+<dt><strong><a name="item_special_decode">$string = $term->special_decode $text</a></strong><br />
+</dt>
+<dd>
+Converts rxvt-unicodes text reprsentation into a perl string. See
+<a href="#item_row_t"><code>$term->ROW_t</code></a> for details.
+</dd>
+<p></p></dl>
+<p>
+</p>
+<h2><a name="rendition">RENDITION</a></h2>
+<p>Rendition bitsets contain information about colour, font, font styles and
+similar information for each screen cell.</p>
+<p>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.</p>
+<dl>
+<dt><strong><a name="item__24rend__3d_urxvt_3a_3adefault_rstyle">$rend = urxvt::DEFAULT_RSTYLE</a></strong><br />
+</dt>
+<dd>
+Returns the default rendition, as used when the terminal is starting up or
+being reset. Useful as a base
</dd>
<p></p></dl>
<p>
.\" ========================================================================
.\"
.IX Title "rxvt 3"
-.TH rxvt 3 "2006-01-02" "6.2" "RXVT-UNICODE"
+.TH rxvt 3 "2006-01-03" "6.2" "RXVT-UNICODE"
.SH "NAME"
@@RXVT_NAME@@perl \- rxvt\-unicode's embedded perl interpreter
.SH "SYNOPSIS"
.PP
Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where
scripts will be shared (But not enabled) for all terminals.
+.SH "PACKAGED EXTENSIONS"
+.IX Header "PACKAGED EXTENSIONS"
+This section describes the extensiosn delivered with this version. You can
+find them in \fI@@RXVT_LIBDIR@@/urxvt/perl/\fR.
+.PP
+You can activate them like this:
+.PP
+.Vb 1
+\& @@RXVT_NAME@@ -pe <extensionname>
+.Ve
+.IP "selection" 4
+.IX Item "selection"
+Miscellaneous selection modifications.
+.RS 4
+.IP "rot13" 4
+.IX Item "rot13"
+Rot\-13 the selection when activated. Used via keyboard trigger:
+.Sp
+.Vb 1
+\& URxvt.keysym.C-M-r: perl:selection:rot13
+.Ve
+.RE
+.RS 4
+.RE
+.IP "digital-clock" 4
+.IX Item "digital-clock"
+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.
+.IP "simple-overlay-clock" 4
+.IX Item "simple-overlay-clock"
+Displays a digital clock using the built-in overlay (colorful, useless).
.Sh "General \s-1API\s0 Considerations"
.IX Subsection "General API Considerations"
All objects (such as terminals, time watchers etc.) are typical
.IP "$term\->tt_write ($octets)" 4
.IX Item "$term->tt_write ($octets)"
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 convetr you strings first to
-the locale-specific encoding using \f(CW\*(C`$term\->locale_encode\*(C'\fR.
+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 "$nrow = $term\->nrow" 4
+.el .IP "$nrow = \f(CW$term\fR\->nrow" 4
+.IX Item "$nrow = $term->nrow"
+.PD 0
+.ie n .IP "$ncol = $term\->ncol" 4
+.el .IP "$ncol = \f(CW$term\fR\->ncol" 4
+.IX Item "$ncol = $term->ncol"
+.PD
+Return the number of rows/columns of the terminal window (i.e. as
+specified by \f(CW\*(C`\-geometry\*(C'\fR, excluding any scrollback).
+.ie n .IP "$nsaved = $term\->nsaved" 4
+.el .IP "$nsaved = \f(CW$term\fR\->nsaved" 4
+.IX Item "$nsaved = $term->nsaved"
+Returns the number of lines in the scrollback buffer.
+.ie n .IP "$view_start = $term\->view_start ([$newvalue])" 4
+.el .IP "$view_start = \f(CW$term\fR\->view_start ([$newvalue])" 4
+.IX Item "$view_start = $term->view_start ([$newvalue])"
+Returns the negative row number of the topmost line. Minimum value is
+\&\f(CW0\fR, which displays the normal terminal contents. Larger values scroll
+this many lines into the scrollback buffer.
+.IP "$term\->want_refresh" 4
+.IX Item "$term->want_refresh"
+Requests a screen refresh. At the next opportunity, rxvt-unicode will
+compare the on-screen display with its stored representation. If they
+differ, it redraws the differences.
+.Sp
+Used after changing terminal contents to display them.
+.ie n .IP "$text = $term\fR\->ROW_t ($row_number[, \f(CW$new_text\fR[, \f(CW$start_col]])" 4
+.el .IP "$text = \f(CW$term\fR\->ROW_t ($row_number[, \f(CW$new_text\fR[, \f(CW$start_col\fR]])" 4
+.IX Item "$text = $term->ROW_t ($row_number[, $new_text[, $start_col]])"
+Returns the text of the entire row with number \f(CW$row_number\fR. Row \f(CW0\fR
+is the topmost terminal line, row \f(CW\*(C`$term\->$ncol\-1\*(C'\fR is the bottommost
+terminal line. The scrollback buffer starts at line \f(CW\*(C`\-1\*(C'\fR and extends to
+line \f(CW\*(C`\-$term\->nsaved\*(C'\fR.
+.Sp
+If \f(CW$new_text\fR is specified, it will replace characters in the current
+line, starting at column \f(CW$start_col\fR (default \f(CW0\fR), which is useful
+to replace only parts of a line. The font iindex in the rendition will
+automatically be updated.
+.Sp
+\&\f(CW$text\fR is in a special encoding: tabs and wide characters that use more
+than one cell when displayed are padded with urxvt::NOCHAR characters
+(\f(CW\*(C`chr 65535\*(C'\fR). Characters with combining characters and other characters
+that do not fit into the normal tetx encoding will be replaced with
+characters in the private use area.
+.Sp
+You have to obey this encoding when changing text. The advantage is
+that \f(CW\*(C`substr\*(C'\fR and similar functions work on screen cells and not on
+characters.
+.Sp
+The methods \f(CW\*(C`$term\->special_encode\*(C'\fR and \f(CW\*(C`$term\->special_decode\*(C'\fR
+can be used to convert normal strings into this encoding and vice versa.
+.ie n .IP "$rend = $term\fR\->ROW_r ($row_number[, \f(CW$new_rend\fR[, \f(CW$start_col]])" 4
+.el .IP "$rend = \f(CW$term\fR\->ROW_r ($row_number[, \f(CW$new_rend\fR[, \f(CW$start_col\fR]])" 4
+.IX Item "$rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])"
+Like \f(CW\*(C`$term\->ROW_t\*(C'\fR, but returns an arrayref with rendition
+bitsets. Rendition bitsets contain information about colour, font, font
+styles and similar information. See also \f(CW\*(C`$term\->ROW_t\*(C'\fR.
+.Sp
+When setting rendition, the font mask will be ignored.
+.Sp
+See the section on \s-1RENDITION\s0, below.
+.ie n .IP "$length = $term\fR\->ROW_l ($row_number[, \f(CW$new_length])" 4
+.el .IP "$length = \f(CW$term\fR\->ROW_l ($row_number[, \f(CW$new_length\fR])" 4
+.IX Item "$length = $term->ROW_l ($row_number[, $new_length])"
+Returns the number of screen cells that are in use (\*(L"the line length\*(R"). If
+it is \f(CW\*(C`\-1\*(C'\fR, then the line is part of a multiple-row logical \*(L"line\*(R", which
+means all characters are in use and it is continued on the next row.
+.ie n .IP "$text = $term\fR\->special_encode \f(CW$string" 4
+.el .IP "$text = \f(CW$term\fR\->special_encode \f(CW$string\fR" 4
+.IX Item "$text = $term->special_encode $string"
+Converts a perl string into the special encoding used by rxvt\-unicode,
+where one character corresponds to one screen cell. See
+\&\f(CW\*(C`$term\->ROW_t\*(C'\fR for details.
+.ie n .IP "$string = $term\fR\->special_decode \f(CW$text" 4
+.el .IP "$string = \f(CW$term\fR\->special_decode \f(CW$text\fR" 4
+.IX Item "$string = $term->special_decode $text"
+Converts rxvt-unicodes text reprsentation into a perl string. See
+\&\f(CW\*(C`$term\->ROW_t\*(C'\fR for details.
+.Sh "\s-1RENDITION\s0"
+.IX Subsection "RENDITION"
+Rendition bitsets contain information about colour, font, font styles and
+similar information for each screen cell.
+.PP
+The following \*(L"macros\*(R" 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.
+.IP "$rend = urxvt::DEFAULT_RSTYLE" 4
+.IX Item "$rend = urxvt::DEFAULT_RSTYLE"
+Returns the default rendition, as used when the terminal is starting up or
+being reset. Useful as a base
.ie n .Sh "The ""urxvt::timer"" Class"
.el .Sh "The \f(CWurxvt::timer\fP Class"
.IX Subsection "The urxvt::timer Class"
Each script will only ever be loaded once, even in rxvtd, where scripts
will be shared (But not enabled) for all terminals.
+PACKAGED EXTENSIONS
+ This section describes the extensiosn delivered with this version. You
+ can find them in /opt/rxvt/lib/urxvt/perl/.
+
+ You can activate them like this:
+
+ rxvt -pe <extensionname>
+
+ selection
+ Miscellaneous selection modifications.
+
+ rot13
+ Rot-13 the selection when activated. Used via keyboard trigger:
+
+ URxvt.keysym.C-M-r: perl:selection:rot13
+
+ digital-clock
+ 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.
+
+ simple-overlay-clock
+ Displays a digital clock using the built-in overlay (colorful,
+ useless).
+
General API Considerations
All objects (such as terminals, time watchers etc.) are typical
reference-to-hash objects. The hash can be used to store anything you
$term->tt_write ($octets)
Write the octets given in $data to the tty (i.e. as program input).
- To pass characters instead of octets, you should convetr you strings
- first to the locale-specific encoding using "$term->locale_encode".
+ To pass characters instead of octets, you should convert your
+ strings first to the locale-specific encoding using
+ "$term->locale_encode".
+
+ $nrow = $term->nrow
+ $ncol = $term->ncol
+ Return the number of rows/columns of the terminal window (i.e. as
+ specified by "-geometry", excluding any scrollback).
+
+ $nsaved = $term->nsaved
+ Returns the number of lines in the scrollback buffer.
+
+ $view_start = $term->view_start ([$newvalue])
+ Returns the negative row number of the topmost line. Minimum value
+ is 0, which displays the normal terminal contents. Larger values
+ scroll this many lines into the scrollback buffer.
+
+ $term->want_refresh
+ Requests a screen refresh. At the next opportunity, rxvt-unicode
+ will compare the on-screen display with its stored representation.
+ If they differ, it redraws the differences.
+
+ Used after changing terminal contents to display them.
+
+ $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
+ Returns the text of the entire row with number $row_number. Row 0 is
+ the topmost terminal line, row "$term->$ncol-1" is the bottommost
+ terminal line. The scrollback buffer starts at line -1 and extends
+ to line "-$term->nsaved".
+
+ If $new_text is specified, it will replace characters in the current
+ line, starting at column $start_col (default 0), which is useful to
+ replace only parts of a line. The font iindex in the rendition will
+ automatically be updated.
+
+ $text is in a special encoding: tabs and wide characters that use
+ more than one cell when displayed are padded with urxvt::NOCHAR
+ characters ("chr 65535"). Characters with combining characters and
+ other characters that do not fit into the normal tetx encoding will
+ be replaced with characters in the private use area.
+
+ You have to obey this encoding when changing text. The advantage is
+ that "substr" and similar functions work on screen cells and not on
+ characters.
+
+ The methods "$term->special_encode" and "$term->special_decode" can
+ be used to convert normal strings into this encoding and vice versa.
+
+ $rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])
+ Like "$term->ROW_t", but returns an arrayref with rendition bitsets.
+ Rendition bitsets contain information about colour, font, font
+ styles and similar information. See also "$term->ROW_t".
+
+ When setting rendition, the font mask will be ignored.
+
+ See the section on RENDITION, below.
+
+ $length = $term->ROW_l ($row_number[, $new_length])
+ Returns the number of screen cells that are in use ("the line
+ length"). If it is -1, then the line is part of a multiple-row
+ logical "line", which means all characters are in use and it is
+ continued on the next row.
+
+ $text = $term->special_encode $string
+ Converts a perl string into the special encoding used by
+ rxvt-unicode, where one character corresponds to one screen cell.
+ See "$term->ROW_t" for details.
+
+ $string = $term->special_decode $text
+ Converts rxvt-unicodes text reprsentation into a perl string. See
+ "$term->ROW_t" for details.
+
+ 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.
+
+ $rend = urxvt::DEFAULT_RSTYLE
+ Returns the default rendition, as used when the terminal is starting
+ up or being reset. Useful as a base
The "urxvt::timer" Class
This class implements timer watchers/events. Time is represented as a
thus must be encoded as UTF-8.
Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where
-scripts will be shared (But not enabled) for all terminals.
+scripts will be shared (but not enabled) for all terminals.
=head1 PACKAGED EXTENSIONS
projects / dana / urxvt.git / commitdiff