<dd>
Colon-separated list of perl extension scripts to use in this terminal
instance. Each extension is looked up in the library directories, loaded
-if necessary, and bound to the current terminal instance; option <strong>-pe</strong>.
+if necessary, and bound to the current terminal instance. If this resource
+is empty or missing, then the perl interpreter will not be initialized;
+option <strong>-pe</strong>.
</dd>
<p></p>
<dt><strong><a name="item_perl_2deval_3a_string"><strong>perl-eval</strong>: <em>string</em></a></strong><br />
.\" ========================================================================
.\"
.IX Title "rxvt 1"
-.TH rxvt 1 "2006-01-02" "6.2" "RXVT-UNICODE"
+.TH rxvt 1 "2006-01-03" "6.2" "RXVT-UNICODE"
.SH "NAME"
rxvt\-unicode (ouR XVT, unicode) \- (a VT102 emulator for the X window system)
.SH "SYNOPSIS"
.IX Item "perl-ext: string"
Colon-separated list of perl extension scripts to use in this terminal
instance. Each extension is looked up in the library directories, loaded
-if necessary, and bound to the current terminal instance; option \fB\-pe\fR.
+if necessary, and bound to the current terminal instance. If this resource
+is empty or missing, then the perl interpreter will not be initialized;
+option \fB\-pe\fR.
.IP "\fBperl-eval\fR: \fIstring\fR" 4
.IX Item "perl-eval: string"
Perl code to be evaluated when all extensions have been registered. See the
Colon-separated list of perl extension scripts to use in this
terminal instance. Each extension is looked up in the library
directories, loaded if necessary, and bound to the current terminal
- instance; option -pe.
+ instance. If this resource is empty or missing, then the perl
+ interpreter will not be initialized; option -pe.
perl-eval: *string*
Perl code to be evaluated when all extensions have been registered.
<li><a href="#prepackaged_extensions">Prepackaged Extensions</a></li>
<li><a href="#general_api_considerations">General API Considerations</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>
<li><a href="#rendition">RENDITION</a></li>
<li><a href="#the_urxvt__term_class">The <code>urxvt::term</code> Class</a></li>
<dt><strong><a name="item_selection">selection</a></strong><br />
</dt>
<dd>
-Miscellaneous selection modifications.
+Intelligent selection. This etxension tries to be more intelligent when the user
+extends selections (double-click).
+</dd>
+<dd>
+<p>It also offers the following bindable event:</p>
</dd>
<dl>
<dt><strong><a name="item_rot13">rot13</a></strong><br />
<p>All objects (such as terminals, time watchers etc.) are typical
reference-to-hash objects. The hash can be used to store anything you
like. All members starting with an underscore (such as <code>_ptr</code> or
-<code>_hook</code>) are reserved for internal uses and must not be accessed or
+<code>_hook</code>) are reserved for internal uses and <strong>MUST NOT</strong> be accessed or
modified).</p>
<p>When objects are destroyed on the C++ side, the perl object hashes are
emptied, so its best to store related objects such as time watchers and
<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>The following subroutines can be declared in loaded scripts, 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.</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>Returning a true value aborts selection grabbing. It will still be hilighted.</p>
</dd>
<p></p>
+<dt><strong><a name="item_on_sel_extend__24term">on_sel_extend $term</a></strong><br />
+</dt>
+<dd>
+Called whenever the user tries to extend the selection (e.g. with a double
+click) and is either supposed to return false (normal operation), or
+should extend the selection itelf and return true to suppress the built-in
+processing.
+</dd>
+<dd>
+<p>See the <em>selection</em> example extension.</p>
+</dd>
+<p></p>
<dt><strong><a name="item_on_focus_in__24term">on_focus_in $term</a></strong><br />
</dt>
<dd>
<p></p></dl>
<p>
</p>
+<h2><a name="variables_in_the_urxvt_package">Variables in the <code>urxvt</code> Package</a></h2>
+<dl>
+<dt><strong><a name="item__24urxvt_3a_3aterm">$urxvt::TERM</a></strong><br />
+</dt>
+<dd>
+The current terminal. Whenever a callback/Hook is bein executed, this
+variable stores the current <code>urxvt::term</code> object.
+</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 />
as long as the perl object is referenced.</p>
</dd>
<dd>
-<p>Currently, the only method on the <code>urxvt::overlay</code> object is <a href="#item_set"><code>set</code></a>:</p>
+<p>The methods currently supported on <code>urxvt::overlay</code> objects are:</p>
</dd>
-<p></p>
+<dl>
<dt><strong><a name="item_set">$overlay->set ($x, $y, $text, $rend)</a></strong><br />
</dt>
<dd>
at a specific position inside the overlay.
</dd>
<p></p>
+<dt><strong><a name="item_hide">$overlay->hide</a></strong><br />
+</dt>
+<dd>
+If visible, hide the overlay, but do not destroy it.
+</dd>
+<p></p>
+<dt><strong><a name="item_show">$overlay->show</a></strong><br />
+</dt>
+<dd>
+If hidden, display the overlay again.
+</dd>
+<p></p></dl>
<dt><strong><a name="item_strwidth">$cellwidth = $term->strwidth $string</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>.
+line <a href="#item_nsaved"><code>-$term->nsaved</code></a>. Nothing will be returned if a nonexistent line
+is requested.
</dd>
<dd>
<p>If <code>$new_text</code> is specified, it will replace characters in the current
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>
+<p>The methods <
code>$term->special_encode</code> 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_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.
+Returns the number of screen cells that are in use (``the line
+length''). Unlike the urxvt core, this returns <a href="#item_ncol"><code>$term->ncol</code></a> if the
+line is joined with the following one.
+</dd>
+<p></p>
+<dt><strong><a name="item_is_longer">$bool = $term->is_longer ($row_number)</a></strong><br />
+</dt>
+<dd>
+Returns true if the row is part of a multiple-row logical ``line'' (i.e.
+joined with the following row), which means all characters are in use
+and it is continued on the next row (and possibly a continuation of the
+previous row(s)).
</dd>
<p></p>
-<dt><strong><a name="item_special_encode">$text = $term->special_encode $string</a></strong><br />
+<dt><strong><a name="item_line">$line = $term->line ($row_number)</a></strong><br />
+</dt>
+<dd>
+Create and return a new <code>urxvt::line</code> object that stores information
+about the logical line that row <code>$row_number</code> is part of. It supports the
+following methods:
+</dd>
+<dl>
+<dt><strong><a name="item_t">$text = $line->t</a></strong><br />
+</dt>
+<dd>
+Returns the full text of the line, similar to <a href="#item_row_t"><code>ROW_t</code></a>
+</dd>
+<p></p>
+<dt><strong><a name="item_r">$rend = $line->r</a></strong><br />
+</dt>
+<dd>
+Returns the full rendition array of the line, similar to <a href="#item_row_r"><code>ROW_r</code></a>
+</dd>
+<p></p>
+<dt><strong><a name="item_l">$length = $line->l</a></strong><br />
+</dt>
+<dd>
+Returns the length of the line in cells, similar to <a href="#item_row_l"><code>ROW_l</code></a>.
+</dd>
+<p></p>
+<dt><strong><a name="item_beg">$rownum = $line->beg</a></strong><br />
+</dt>
+<dt><strong><a name="item_end">$rownum = $line->end</a></strong><br />
+</dt>
+<dd>
+Return the row number of the first/last row of the line, respectively.
+</dd>
+<p></p>
+<dt><strong><a name="item_offset_of">$offset = $line->offset_of ($row, $col)</a></strong><br />
+</dt>
+<dd>
+Returns the character offset of the given row|col pair within the logical
+line.
+</dd>
+<p></p>
+<dt><strong><a name="item_coord_of">($row, $col) = $line->coord_of ($offset)</a></strong><br />
+</dt>
+<dd>
+Translates a string offset into terminal coordinates again.
+</dd>
+<p></p></dl>
+<dt><strong>($row, $col) = $line->coord_of ($offset)
+=item $text = $term->special_encode $string</strong><br />
</dt>
<dd>
Converts a perl string into the special encoding used by rxvt-unicode,
.Ve
.IP "selection" 4
.IX Item "selection"
-Miscellaneous selection modifications.
+Intelligent selection. This etxension tries to be more intelligent when the user
+extends selections (double\-click).
+.Sp
+It also offers the following bindable event:
.RS 4
.IP "rot13" 4
.IX Item "rot13"
All objects (such as terminals, time watchers etc.) are typical
reference-to-hash objects. The hash can be used to store anything you
like. All members starting with an underscore (such as \f(CW\*(C`_ptr\*(C'\fR or
-\&\f(CW\*(C`_hook\*(C'\fR) are reserved for internal uses and must not be accessed or
+\&\f(CW\*(C`_hook\*(C'\fR) are reserved for internal uses and \fB\s-1MUST\s0 \s-1NOT\s0\fR be accessed or
modified).
.PP
When objects are destroyed on the \*(C+ side, the perl object hashes are
terminal is destroyed.
.Sh "Hooks"
.IX Subsection "Hooks"
-The following subroutines can be declared in loaded scripts, and will be called
-whenever the relevant event happens.
+The following subroutines can be declared in loaded scripts, 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.
.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,
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_sel_extend $term" 4
+.el .IP "on_sel_extend \f(CW$term\fR" 4
+.IX Item "on_sel_extend $term"
+Called whenever the user tries to extend the selection (e.g. with a double
+click) and is either supposed to return false (normal operation), or
+should extend the selection itelf and return true to suppress the built-in
+processing.
+.Sp
+See the \fIselection\fR example extension.
.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 user presses a key combination that has a
\&\f(CW\*(C`perl:string\*(C'\fR action bound to it (see description of the \fBkeysym\fR
resource in the @@RXVT_NAME@@(1) manpage).
+.ie n .Sh "Variables in the ""urxvt"" Package"
+.el .Sh "Variables in the \f(CWurxvt\fP Package"
+.IX Subsection "Variables in the urxvt Package"
+.IP "$urxvt::TERM" 4
+.IX Item "$urxvt::TERM"
+The current terminal. Whenever a callback/Hook is bein executed, this
+variable stores the current \f(CW\*(C`urxvt::term\*(C'\fR object.
.ie n .Sh "Functions in the ""urxvt"" Package"
.el .Sh "Functions in the \f(CWurxvt\fP Package"
.IX Subsection "Functions in the urxvt Package"
This method returns an urxvt::overlay object. The overlay will be visible
as long as the perl object is referenced.
.Sp
-Currently, the only method on the \f(CW\*(C`urxvt::overlay\*(C'\fR object is \f(CW\*(C`set\*(C'\fR:
+The methods currently supported on \f(CW\*(C`urxvt::overlay\*(C'\fR objects are:
+.RS 4
.ie n .IP "$overlay\->set ($x, $y\fR, \f(CW$text\fR, \f(CW$rend)" 4
.el .IP "$overlay\->set ($x, \f(CW$y\fR, \f(CW$text\fR, \f(CW$rend\fR)" 4
.IX Item "$overlay->set ($x, $y, $text, $rend)"
Similar to \f(CW\*(C`$term\->ROW_t\*(C'\fR and \f(CW\*(C`$term\->ROW_r\*(C'\fR in that it puts
text in rxvt\-unicode's special encoding and an array of rendition values
at a specific position inside the overlay.
+.IP "$overlay\->hide" 4
+.IX Item "$overlay->hide"
+If visible, hide the overlay, but do not destroy it.
+.IP "$overlay\->show" 4
+.IX Item "$overlay->show"
+If hidden, display the overlay again.
+.RE
+.RS 4
+.RE
.ie n .IP "$cellwidth = $term\fR\->strwidth \f(CW$string" 4
.el .IP "$cellwidth = \f(CW$term\fR\->strwidth \f(CW$string\fR" 4
.IX Item "$cellwidth = $term->strwidth $string"
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.
+line \f(CW\*(C`\-$term\->nsaved\*(C'\fR. Nothing will be returned if a nonexistent line
+is requested.
.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
.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"
+Returns the number of screen cells that are in use (\*(L"the line
+length\*(R"). Unlike the urxvt core, this returns \f(CW\*(C`$term\->ncol\*(C'\fR if the
+line is joined with the following one.
+.ie n .IP "$bool = $term\->is_longer ($row_number)" 4
+.el .IP "$bool = \f(CW$term\fR\->is_longer ($row_number)" 4
+.IX Item "$bool = $term->is_longer ($row_number)"
+Returns true if the row is part of a multiple-row logical \*(L"line\*(R" (i.e.
+joined with the following row), which means all characters are in use
+and it is continued on the next row (and possibly a continuation of the
+previous row(s)).
+.ie n .IP "$line = $term\->line ($row_number)" 4
+.el .IP "$line = \f(CW$term\fR\->line ($row_number)" 4
+.IX Item "$line = $term->line ($row_number)"
+Create and return a new \f(CW\*(C`urxvt::line\*(C'\fR object that stores information
+about the logical line that row \f(CW$row_number\fR is part of. It supports the
+following methods:
+.RS 4
+.ie n .IP "$text = $line\->t" 4
+.el .IP "$text = \f(CW$line\fR\->t" 4
+.IX Item "$text = $line->t"
+Returns the full text of the line, similar to \f(CW\*(C`ROW_t\*(C'\fR
+.ie n .IP "$rend = $line\->r" 4
+.el .IP "$rend = \f(CW$line\fR\->r" 4
+.IX Item "$rend = $line->r"
+Returns the full rendition array of the line, similar to \f(CW\*(C`ROW_r\*(C'\fR
+.ie n .IP "$length = $line\->l" 4
+.el .IP "$length = \f(CW$line\fR\->l" 4
+.IX Item "$length = $line->l"
+Returns the length of the line in cells, similar to \f(CW\*(C`ROW_l\*(C'\fR.
+.ie n .IP "$rownum = $line\->beg" 4
+.el .IP "$rownum = \f(CW$line\fR\->beg" 4
+.IX Item "$rownum = $line->beg"
+.PD 0
+.ie n .IP "$rownum = $line\->end" 4
+.el .IP "$rownum = \f(CW$line\fR\->end" 4
+.IX Item "$rownum = $line->end"
+.PD
+Return the row number of the first/last row of the line, respectively.
+.ie n .IP "$offset = $line\fR\->offset_of ($row, \f(CW$col)" 4
+.el .IP "$offset = \f(CW$line\fR\->offset_of ($row, \f(CW$col\fR)" 4
+.IX Item "$offset = $line->offset_of ($row, $col)"
+Returns the character offset of the given row|col pair within the logical
+line.
+.ie n .IP "($row, $col\fR) = \f(CW$line\->coord_of ($offset)" 4
+.el .IP "($row, \f(CW$col\fR) = \f(CW$line\fR\->coord_of ($offset)" 4
+.IX Item "($row, $col) = $line->coord_of ($offset)"
+Translates a string offset into terminal coordinates again.
+.RE
+.RS 4
+.RE
+.ie n .IP "($row, $col\fR) = \f(CW$line\fR\->coord_of ($offset) =item \f(CW$text\fR = \f(CW$term\fR\->special_encode \f(CW$string" 4
+.el .IP "($row, \f(CW$col\fR) = \f(CW$line\fR\->coord_of ($offset) =item \f(CW$text\fR = \f(CW$term\fR\->special_encode \f(CW$string\fR" 4
+.IX Item "($row, $col) = $line->coord_of ($offset) =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.
rxvt -pe <extensionname>
selection
- Miscellaneous selection modifications.
+ Intelligent selection. This etxension tries to be more intelligent
+ when the user extends selections (double-click).
+
+ It also offers the following bindable event:
rot13
Rot-13 the selection when activated. Used via keyboard trigger:
All objects (such as terminals, time watchers etc.) are typical
reference-to-hash objects. The hash can be used to store anything you
like. All members starting with an underscore (such as "_ptr" or
- "_hook") are reserved for internal uses and must not be accessed or
+ "_hook") are reserved for internal uses and MUST NOT be accessed or
modified).
When objects are destroyed on the C++ side, the perl object hashes are
The following subroutines can be declared in loaded scripts, 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.
+
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++
Returning a true value aborts selection grabbing. It will still be
hilighted.
+ on_sel_extend $term
+ Called whenever the user tries to extend the selection (e.g. with a
+ double click) and is either supposed to return false (normal
+ operation), or should extend the selection itelf and return true to
+ suppress the built-in processing.
+
+ See the selection example extension.
+
on_focus_in $term
Called whenever the window gets the keyboard focus, before urxvt
does focus in processing.
"perl:string" action bound to it (see description of the keysym
resource in the rxvt(1) manpage).
+ Variables in the "urxvt" Package
+ $urxvt::TERM
+ The current terminal. Whenever a callback/Hook is bein executed,
+ this variable stores the current "urxvt::term" object.
+
Functions in the "urxvt" Package
urxvt::fatal $errormessage
Fatally aborts execution with the given error message. Avoid at all
This method returns an urxvt::overlay object. The overlay will be
visible as long as the perl object is referenced.
- Currently, the only method on the "urxvt::overlay" object is "set":
+ The methods currently supported on "urxvt::overlay" objects are:
+
+ $overlay->set ($x, $y, $text, $rend)
+ Similar to "$term->ROW_t" and "$term->ROW_r" in that it puts
+ text in rxvt-unicode's special encoding and an array of
+ rendition values at a specific position inside the overlay.
- $overlay->set ($x, $y, $text, $rend)
- Similar to "$term->ROW_t" and "$term->ROW_r" in that it puts text in
- rxvt-unicode's special encoding and an array of rendition values at
- a specific position inside the overlay.
+ $overlay->hide
+ If visible, hide the overlay, but do not destroy it.
+
+ $overlay->show
+ If hidden, display the overlay again.
$cellwidth = $term->strwidth $string
Returns the number of screen-cells this string would need. Correctly
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".
+ to line "-$term->nsaved". Nothing will be returned if a nonexistent
+ line is requested.
If $new_text is specified, it will replace characters in the current
line, starting at column $start_col (default 0), which is useful to
$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.
+ length"). Unlike the urxvt core, this returns "$term->ncol" if the
+ line is joined with the following one.
+
+ $bool = $term->is_longer ($row_number)
+ Returns true if the row is part of a multiple-row logical "line"
+ (i.e. joined with the following row), which means all characters are
+ in use and it is continued on the next row (and possibly a
+ continuation of the previous row(s)).
+
+ $line = $term->line ($row_number)
+ Create and return a new "urxvt::line" object that stores information
+ about the logical line that row $row_number is part of. It supports
+ the following methods:
+
+ $text = $line->t
+ Returns the full text of the line, similar to "ROW_t"
+
+ $rend = $line->r
+ Returns the full rendition array of the line, similar to "ROW_r"
+
+ $length = $line->l
+ Returns the length of the line in cells, similar to "ROW_l".
+
+ $rownum = $line->beg
+ $rownum = $line->end
+ Return the row number of the first/last row of the line,
+ respectively.
+
+ $offset = $line->offset_of ($row, $col)
+ Returns the character offset of the given row|col pair within
+ the logical line.
+
+ ($row, $col) = $line->coord_of ($offset)
+ Translates a string offset into terminal coordinates again.
- $text = $term->special_encode $string
+ ($row, $col) = $line->coord_of ($offset) =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 "$term->ROW_t" for details.
projects / dana / urxvt.git / commitdiff