- perl: implement additional hook: line_update, add_lines.
- perl: urxvt::line now can set via ->t and ->r.
+ - perl: changed interpretation of --perl-ext-common and -pe.
+ - perl: much increased functionality, better overlays, popup support.
6.3 Wed Jan 4 22:37:10 CET 2006
- SECURITY FIX: on systems using openpty, permissions were
<dt><strong><a name="item__2dpe_string"><strong>-pe</strong> <em>string</em></a></strong><br />
</dt>
<dd>
-Comma-separated list of perl extension scripts to use in this terminal
-instance. See resource <strong>perl-ext</strong>.
+Comma-separated list of perl extension scripts to use (or not to use) in
+this terminal instance. See resource <strong>perl-ext</strong> for details.
</dd>
<p></p></dl>
<p>
<dt><strong><a name="item_perl_2dext_3a_string"><strong>perl-ext</strong>: <em>string</em></a></strong><br />
</dt>
<dd>
-Comma-separated <code>list(s)</code> 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. If this
-resource is empty or missing, then the perl interpreter will not be
-initialized. The idea behind two options is that <strong>perl-ext-common</strong> will
-be used for extensions that should be available to all instances, while
-<strong>perl-ext</strong> is used for specific instances; option <strong>-pe</strong>.
+Comma-separated <code>list(s)</code> of perl extension scripts (default: <code>default</code>) to
+use in this terminal instance; option <strong>-pe</strong>.
+</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
+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>Each extension is looked up in the library directories, loaded if
+necessary, and bound to the current terminal instance.</p>
+</dd>
+<dd>
+<p>If both of these resources are the empty string, then the perl
+interpreter will not be initialized. The idea behind two options is that
+<strong>perl-ext-common</strong> will be used for extensions that should be available to
+all instances, while <strong>perl-ext</strong> is used for specific instances.</p>
</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-07" "6.3" "RXVT-UNICODE"
+.TH rxvt 1 "2006-01-08" "6.3" "RXVT-UNICODE"
.SH "NAME"
rxvt\-unicode (ouR XVT, unicode) \- (a VT102 emulator for the X window system)
.SH "SYNOPSIS"
.Ve
.IP "\fB\-pe\fR \fIstring\fR" 4
.IX Item "-pe string"
-Comma-separated list of perl extension scripts to use in this terminal
-instance. See resource \fBperl-ext\fR.
+Comma-separated list of perl extension scripts to use (or not to use) in
+this terminal instance. See resource \fBperl-ext\fR for details.
.SH "RESOURCES (available also as long\-options)"
.IX Header "RESOURCES (available also as long-options)"
Note: `@@RXVT_NAME@@ \-\-help' gives a list of all resources (long
.IP "\fBperl-ext\fR: \fIstring\fR" 4
.IX Item "perl-ext: string"
.PD
-Comma-separated list(s) 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. If this
-resource is empty or missing, then the perl interpreter will not be
-initialized. The idea behind two options is that \fBperl-ext-common\fR will
-be used for extensions that should be available to all instances, while
-\&\fBperl-ext\fR is used for specific instances; option \fB\-pe\fR.
+Comma-separated list(s) of perl extension scripts (default: \f(CW\*(C`default\*(C'\fR) to
+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
+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
+Each extension is looked up in the library directories, loaded if
+necessary, and bound to the current terminal instance.
+.Sp
+If both of these resources are the empty string, then the perl
+interpreter will not be initialized. The idea behind two options is that
+\&\fBperl-ext-common\fR will be used for extensions that should be available to
+all instances, while \fBperl-ext\fR is used for specific instances.
.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
=item B<-pe> I<string>
-Comma-separated list of perl extension scripts to use in this terminal
-instance. See resource B<perl-ext>.
+Comma-separated list of perl extension scripts to use (or not to use) in
+this terminal instance. See resource B<perl-ext> for details.
=back
=item B<perl-ext>: I<string>
-Comma-separated list(s) 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. If this
-resource is empty or missing, then the perl interpreter will not be
-initialized. The idea behind two options is that B<perl-ext-common> will
-be used for extensions that should be available to all instances, while
-B<perl-ext> is used for specific instances; option B<-pe>.
+Comma-separated list(s) of perl extension scripts (default: C<default>) to
+use in this terminal instance; option B<-pe>.
+
+Extension names can be prefixed with a C<-> sign to prohibit using
+it. This can be useful to selectively disable some extensions loaded
+by default, or specified via the C<perl-ext-common> resource. For
+example, C<default,-selection> will use all the default extension except
+C<selection>.
+
+Each extension is looked up in the library directories, loaded if
+necessary, and bound to the current terminal instance.
+
+If both of these resources are the empty string, then the perl
+interpreter will not be initialized. The idea behind two options is that
+B<perl-ext-common> will be used for extensions that should be available to
+all instances, while B<perl-ext> is used for specific instances.
=item B<perl-eval>: I<string>
while (<$slave>) { print $slave "got <$_>\n" }
-pe *string*
- Comma-separated list of perl extension scripts to use in this
- terminal instance. See resource perl-ext.
+ Comma-separated list of perl extension scripts to use (or not to
+ use) in this terminal instance. See resource perl-ext for details.
RESOURCES (available also as long-options)
Note: `rxvt --help' gives a list of all resources (long options)
perl-ext-common: *string*
perl-ext: *string*
- Comma-separated list(s) 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. If this resource is empty or missing, then the perl
+ Comma-separated list(s) of perl extension scripts (default:
+ "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
+ except "selection".
+
+ Each extension is looked up in the library directories, loaded if
+ necessary, and bound to the current terminal instance.
+
+ If both of these resources are the empty string, then the perl
interpreter will not be initialized. The idea behind two options is
that perl-ext-common will be used for extensions that should be
available to all instances, while perl-ext is used for specific
- instances; option -pe.
+ instances.
perl-eval: *string*
Perl code to be evaluated when all extensions have been registered.
<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>
+ <li><a href="#the_urxvt__popup_class">The <code>urxvt::popup</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>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
-<p>Everytime a terminal object gets created, scripts specified via the
-<code>perl</code> resource are loaded and associated with it.</p>
+<p>Everytime a terminal object gets created, extension scripts specified via
+the <code>perl</code> resource are loaded and associated with it.</p>
<p>Scripts are compiled in a 'use strict' and 'use utf8' environment, and
thus must be encoded as UTF-8.</p>
<p>Each script will only ever be loaded once, even in rxvtd, where
<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
+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>
+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>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>
-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>
resource in the <code>rxvt(1)</code> manpage).
</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 rxvt-unicode
+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 rxvt-unicode does
+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>
<dt><strong><a name="item_on_key_release__24term_2c__24event">on_key_release $term, $event</a></strong><br />
</dt>
<dt><strong><a name="item_on_motion_notify__24term_2c__24event">on_motion_notify $term, $event</a></strong><br />
</dt>
+<dt><strong><a name="item_on_map_notify__24term_2c__24event">on_map_notify $term, $event</a></strong><br />
+</dt>
+<dt><strong><a name="item_on_unmap_notify__24term_2c__24event">on_unmap_notify $term, $event</a></strong><br />
+</dt>
<dd>
Called whenever the corresponding X event is received for the terminal If
the hook returns true, then the even will be ignored by rxvt-unicode.
<dd>
Returns the ``current time'' (as per the event loop).
</dd>
+<p></p>
+<dt><strong><a name="item_urxvt_3a_3acurrenttime">urxvt::CurrentTime</a></strong><br />
+</dt>
+<dt><strong><a name="item_urxvt_3a_3ashiftmask_2c_lockmask_2c_controlmask_2c">urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
+Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
+Button4Mask, Button5Mask, AnyModifier</a></strong><br />
+</dt>
+<dd>
+Various constants for use in X events.
+</dd>
<p></p></dl>
<p>
</p>
Destroy the terminal object (close the window, free resources etc.).
</dd>
<p></p>
+<dt><strong><a name="item_option">$isset = $term->option ($optval[, $set])</a></strong><br />
+</dt>
+<dd>
+Returns true if the option specified by <code>$optval</code> is enabled, and
+optionally change it. All option values are stored by name in the hash
+<code>%urxvt::OPTION</code>. Options not enabled in this binary are not in the hash.
+</dd>
+<dd>
+<p>Here is a a likely non-exhaustive list of option names, please see the
+source file <em>/src/optinc.h</em> to see the actual list:</p>
+</dd>
+<dd>
+<pre>
+ borderLess console cursorBlink cursorUnderline hold iconic insecure
+ intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
+ pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating
+ scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer
+ secondaryScreen secondaryScroll skipBuiltinGlyphs transparent
+ tripleclickwords utmpInhibit visualBell</pre>
+</dd>
+<p></p>
<dt><strong><a name="item_resource">$value = $term->resource ($name[, $newval])</a></strong><br />
</dt>
<dd>
</dd>
<dd>
<p>Here is a a likely non-exhaustive list of resource names, not all of which
-are supported in every build, please see the source to see the actual
-list:</p>
+are supported in every build, please see the source file <em>/src/rsinc.h</em>
+to see the actual list:</p>
</dd>
<dd>
<pre>
If hidden, display the overlay again.
</dd>
<p></p></dl>
+<dt><strong><a name="item_popup">$popup = $term->popup ($event)</a></strong><br />
+</dt>
+<dd>
+Creates a new <code>urxvt::popup</code> object that implements a popup menu. The
+<code>$event</code> <em>must</em> be the event causing the menu to pop up (a button event,
+currently).
+</dd>
+<p></p>
<dt><strong><a name="item_strwidth">$cellwidth = $term->strwidth ($string)</a></strong><br />
</dt>
<dd>
Return various integers describing terminal characteristics.
</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 />
+</dt>
+<dt><strong><a name="item_modnumlockmask">$modifiermask = $term->ModNumLockMask</a></strong><br />
+</dt>
+<dd>
+Return the modifier masks corresponding to the ``ISO Level 3 Shift'' (often
+AltGr), the meta key (often Alt) and the num lock key, if applicable.
+</dd>
+<p></p>
<dt><strong><a name="item_view_start">$view_start = $term->view_start ([$newvalue])</a></strong><br />
</dt>
<dd>
<p></p></dl>
<p>
</p>
+<h2><a name="the_urxvt__popup_class">The <code>urxvt::popup</code> Class</a></h2>
+<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>
.\" ========================================================================
.\"
.IX Title "rxvt 3"
-.TH rxvt 3 "2006-01-07" "6.3" "RXVT-UNICODE"
+.TH rxvt 3 "2006-01-08" "6.3" "RXVT-UNICODE"
.SH "NAME"
@@RXVT_NAME@@perl \- rxvt\-unicode's embedded perl interpreter
.SH "SYNOPSIS"
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
-Everytime a terminal object gets created, scripts specified via the
-\&\f(CW\*(C`perl\*(C'\fR resource are loaded and associated with it.
+Everytime a terminal object gets created, extension scripts specified via
+the \f(CW\*(C`perl\*(C'\fR resource are loaded and associated with it.
.PP
Scripts are compiled in a 'use strict' and 'use utf8' environment, and
thus must be encoded as \s-1UTF\-8\s0.
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
+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.
+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.
.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,
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 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 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 .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 rxvt-unicode
+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 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_motion_notify $term\fR, \f(CW$event" 4
.el .IP "on_motion_notify \f(CW$term\fR, \f(CW$event\fR" 4
.IX Item "on_motion_notify $term, $event"
+.ie n .IP "on_map_notify $term\fR, \f(CW$event" 4
+.el .IP "on_map_notify \f(CW$term\fR, \f(CW$event\fR" 4
+.IX Item "on_map_notify $term, $event"
+.ie n .IP "on_unmap_notify $term\fR, \f(CW$event" 4
+.el .IP "on_unmap_notify \f(CW$term\fR, \f(CW$event\fR" 4
+.IX Item "on_unmap_notify $term, $event"
.PD
Called whenever the corresponding X event is received for the terminal If
the hook returns true, then the even will be ignored by rxvt\-unicode.
.IP "$time = urxvt::NOW" 4
.IX Item "$time = urxvt::NOW"
Returns the \*(L"current time\*(R" (as per the event loop).
+.IP "urxvt::CurrentTime" 4
+.IX Item "urxvt::CurrentTime"
+.PD 0
+.IP "urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask, Button5Mask, AnyModifier" 4
+.IX Item "urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask, Button5Mask, AnyModifier"
+.PD
+Various constants for use in X events.
.Sh "\s-1RENDITION\s0"
.IX Subsection "RENDITION"
Rendition bitsets contain information about colour, font, font styles and
.IP "$term\->destroy" 4
.IX Item "$term->destroy"
Destroy the terminal object (close the window, free resources etc.).
+.ie n .IP "$isset = $term\fR\->option ($optval[, \f(CW$set])" 4
+.el .IP "$isset = \f(CW$term\fR\->option ($optval[, \f(CW$set\fR])" 4
+.IX Item "$isset = $term->option ($optval[, $set])"
+Returns true if the option specified by \f(CW$optval\fR is enabled, and
+optionally change it. All option values are stored by name in the hash
+\&\f(CW%urxvt::OPTION\fR. Options not enabled in this binary are not in the hash.
+.Sp
+Here is a a likely non-exhaustive list of option names, please see the
+source file \fI/src/optinc.h\fR to see the actual list:
+.Sp
+.Vb 6
+\& borderLess console cursorBlink cursorUnderline hold iconic insecure
+\& intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
+\& pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating
+\& scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer
+\& secondaryScreen secondaryScroll skipBuiltinGlyphs transparent
+\& tripleclickwords utmpInhibit visualBell
+.Ve
.ie n .IP "$value = $term\fR\->resource ($name[, \f(CW$newval])" 4
.el .IP "$value = \f(CW$term\fR\->resource ($name[, \f(CW$newval\fR])" 4
.IX Item "$value = $term->resource ($name[, $newval])"
terminal is destroyed, so changing options frequently will eat memory.
.Sp
Here is a a likely non-exhaustive list of resource names, not all of which
-are supported in every build, please see the source to see the actual
-list:
+are supported in every build, please see the source file \fI/src/rsinc.h\fR
+to see the actual list:
.Sp
.Vb 12
\& answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
.RE
.RS 4
.RE
+.ie n .IP "$popup = $term\->popup ($event)" 4
+.el .IP "$popup = \f(CW$term\fR\->popup ($event)" 4
+.IX Item "$popup = $term->popup ($event)"
+Creates a new \f(CW\*(C`urxvt::popup\*(C'\fR object that implements a popup menu. The
+\&\f(CW$event\fR \fImust\fR be the event causing the menu to pop up (a button event,
+currently).
.ie n .IP "$cellwidth = $term\->strwidth ($string)" 4
.el .IP "$cellwidth = \f(CW$term\fR\->strwidth ($string)" 4
.IX Item "$cellwidth = $term->strwidth ($string)"
.IX Item "$lines_in_scrollback = $term->nsaved"
.PD
Return various integers describing terminal characteristics.
+.ie n .IP "$modifiermask = $term\->ModLevel3Mask" 4
+.el .IP "$modifiermask = \f(CW$term\fR\->ModLevel3Mask" 4
+.IX Item "$modifiermask = $term->ModLevel3Mask"
+.PD 0
+.ie n .IP "$modifiermask = $term\->ModMetaMask" 4
+.el .IP "$modifiermask = \f(CW$term\fR\->ModMetaMask" 4
+.IX Item "$modifiermask = $term->ModMetaMask"
+.ie n .IP "$modifiermask = $term\->ModNumLockMask" 4
+.el .IP "$modifiermask = \f(CW$term\fR\->ModNumLockMask" 4
+.IX Item "$modifiermask = $term->ModNumLockMask"
+.PD
+Return the modifier masks corresponding to the \*(L"\s-1ISO\s0 Level 3 Shift\*(R" (often
+AltGr), the meta key (often Alt) and the num lock key, if applicable.
.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])"
.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.
+.ie n .Sh "The ""urxvt::popup"" Class"
+.el .Sh "The \f(CWurxvt::popup\fP Class"
+.IX Subsection "The urxvt::popup Class"
.ie n .Sh "The ""urxvt::timer"" Class"
.el .Sh "The \f(CWurxvt::timer\fP Class"
.IX Subsection "The urxvt::timer Class"
+.RS 4
This class implements timer watchers/events. Time is represented as a
fractional number of seconds since the epoch. Example:
-.PP
+.Sp
.Vb 8
\& $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
\& $term->{timer} = urxvt::timer
.el .IP "$timer = \f(CW$timer\fR\->stop" 4
.IX Item "$timer = $timer->stop"
Stop the timer.
+.RE
+.RS 4
.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
+.Sp
.Vb 12
\& $term->{socket} = ...
\& $term->{iow} = urxvt::iow
.el .IP "$iow = \f(CW$iow\fR\->stop" 4
.IX Item "$iow = $iow->stop"
Stop watching for events on the given filehandle.
+.RE
+.RS 4
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
.Sh "\s-1URXVT_PERL_VERBOSITY\s0"
.IX Item "=3 - script loading and management"
.IP "=10 \- all events received" 4
.IX Item "=10 - all events received"
+.RE
+.RS 4
.PD
.SH "AUTHOR"
.IX Header "AUTHOR"
rxvt --perl-lib $HOME -pe grab_test
DESCRIPTION
- Everytime a terminal object gets created, scripts specified via the
- "perl" resource are loaded and associated with it.
+ Everytime a terminal object gets created, extension scripts specified
+ via the "perl" resource are loaded and associated with it.
Scripts are compiled in a 'use strict' and 'use utf8' environment, and
thus must be encoded as UTF-8.
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.
+ 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.
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
See the selection example extension.
- on_focus_in $term
- Called whenever the window gets the keyboard focus, before urxvt
- does focus in processing.
-
- on_focus_out $term
- Called wheneever the window loses keyboard focus, before urxvt does
- focus out processing.
-
on_view_change $term, $offset
Called whenever the view offset changes, i..e the user or program
scrolls. Offset 0 means display the normal terminal, positive values
"perl:string" action bound to it (see description of the keysym
resource in the rxvt(1) manpage).
+ on_focus_in $term
+ Called whenever the window gets the keyboard focus, before
+ rxvt-unicode does focus in processing.
+
+ on_focus_out $term
+ 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_button_press $term, $event
on_button_release $term, $event
on_motion_notify $term, $event
+ on_map_notify $term, $event
+ on_unmap_notify $term, $event
Called whenever the corresponding X event is received for the
terminal If the hook returns true, then the even will be ignored by
rxvt-unicode.
$time = urxvt::NOW
Returns the "current time" (as per the event loop).
+ urxvt::CurrentTime
+ urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask,
+ Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask,
+ Button5Mask, AnyModifier
+ Various constants for use in X events.
+
RENDITION
Rendition bitsets contain information about colour, font, font styles
and similar information for each screen cell.
$term->destroy
Destroy the terminal object (close the window, free resources etc.).
+ $isset = $term->option ($optval[, $set])
+ Returns true if the option specified by $optval is enabled, and
+ optionally change it. All option values are stored by name in the
+ hash %urxvt::OPTION. Options not enabled in this binary are not in
+ the hash.
+
+ Here is a a likely non-exhaustive list of option names, please see
+ the source file /src/optinc.h to see the actual list:
+
+ borderLess console cursorBlink cursorUnderline hold iconic insecure
+ intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
+ pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating
+ scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer
+ secondaryScreen secondaryScroll skipBuiltinGlyphs transparent
+ tripleclickwords utmpInhibit visualBell
+
$value = $term->resource ($name[, $newval])
Returns the current resource value associated with a given name and
optionally sets a new value. Setting values is most useful in the
memory.
Here is a a likely non-exhaustive list of resource names, not all of
- which are supported in every build, please see the source to see the
- actual list:
+ which are supported in every build, please see the source file
+ /src/rsinc.h to see the actual list:
answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
borderLess color cursorBlink cursorUnderline cutchars delete_key
$overlay->show
If hidden, display the overlay again.
+ $popup = $term->popup ($event)
+ Creates a new "urxvt::popup" object that implements a popup menu.
+ The $event *must* be the event causing the menu to pop up (a button
+ event, currently).
+
$cellwidth = $term->strwidth ($string)
Returns the number of screen-cells this string would need. Correctly
accounts for wide and combining characters.
$lines_in_scrollback = $term->nsaved
Return various integers describing terminal characteristics.
+ $modifiermask = $term->ModLevel3Mask
+ $modifiermask = $term->ModMetaMask
+ $modifiermask = $term->ModNumLockMask
+ Return the modifier masks corresponding to the "ISO Level 3 Shift"
+ (often AltGr), the meta key (often Alt) and the num lock key, if
+ applicable.
+
$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
Converts rxvt-unicodes text reprsentation into a perl string. See
"$term->ROW_t" for details.
+ The "urxvt::popup" Class
The "urxvt::timer" Class
- This class implements timer watchers/events. Time is represented as a
- fractional number of seconds since the epoch. Example:
+ This class implements timer watchers/events. Time is represented as
+ a fractional number of seconds since the epoch. Example:
- $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
- $term->{timer} = urxvt::timer
- ->new
- ->interval (1)
- ->cb (sub {
- $term->{overlay}->set (0, 0,
- sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
- });
+ $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
+ $term->{timer} = urxvt::timer
+ ->new
+ ->interval (1)
+ ->cb (sub {
+ $term->{overlay}->set (0, 0,
+ sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
+ });
- $timer = new urxvt::timer
- Create a new timer object in started state. It is scheduled to fire
- immediately.
+ $timer = new urxvt::timer
+ Create a new timer object in started state. It is scheduled to
+ fire immediately.
- $timer = $timer->cb (sub { my ($timer) = @_; ... })
- Set the callback to be called when the timer triggers.
+ $timer = $timer->cb (sub { my ($timer) = @_; ... })
+ Set the callback to be called when the timer triggers.
- $tstamp = $timer->at
- Return the time this watcher will fire next.
+ $tstamp = $timer->at
+ Return the time this watcher will fire next.
- $timer = $timer->set ($tstamp)
- Set the time the event is generated to $tstamp.
+ $timer = $timer->set ($tstamp)
+ Set the time the event is generated to $tstamp.
- $timer = $timer->interval ($interval)
- Normally (and when $interval is 0), the timer will automatically
- stop after it has fired once. If $interval is non-zero, then the
- timer is automatically rescheduled at the given intervals.
+ $timer = $timer->interval ($interval)
+ Normally (and when $interval is 0), the timer will automatically
+ stop after it has fired once. If $interval is non-zero, then the
+ timer is automatically rescheduled at the given intervals.
- $timer = $timer->start
- Start the timer.
+ $timer = $timer->start
+ Start the timer.
- $timer = $timer->start ($tstamp)
- Set the event trigger time to $tstamp and start the timer.
+ $timer = $timer->start ($tstamp)
+ Set the event trigger time to $tstamp and start the timer.
- $timer = $timer->stop
- Stop the timer.
+ $timer = $timer->stop
+ Stop the timer.
The "urxvt::iow" Class
- This class implements io watchers/events. Example:
+ This class implements io watchers/events. Example:
- $term->{socket} = ...
- $term->{iow} = urxvt::iow
- ->new
- ->fd (fileno $term->{socket})
- ->events (1) # wait for read data
- ->start
- ->cb (sub {
- my ($iow, $revents) = @_;
- # $revents must be 1 here, no need to check
- sysread $term->{socket}, my $buf, 8192
- or end-of-file;
- });
+ $term->{socket} = ...
+ $term->{iow} = urxvt::iow
+ ->new
+ ->fd (fileno $term->{socket})
+ ->events (1) # wait for read data
+ ->start
+ ->cb (sub {
+ my ($iow, $revents) = @_;
+ # $revents must be 1 here, no need to check
+ sysread $term->{socket}, my $buf, 8192
+ or end-of-file;
+ });
- $iow = new urxvt::iow
- Create a new io watcher object in stopped state.
+ $iow = new urxvt::iow
+ Create a new io watcher object in stopped state.
- $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
- Set the callback to be called when io events are triggered.
- $reventmask is a bitset as described in the "events" method.
+ $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
+ Set the callback to be called when io events are triggered.
+ $reventmask is a bitset as described in the "events" method.
- $iow = $iow->fd ($fd)
- Set the filedescriptor (not handle) to watch.
+ $iow = $iow->fd ($fd)
+ Set the filedescriptor (not handle) to watch.
- $iow = $iow->events ($eventmask)
- Set the event mask to watch. Bit #0 (value 1) enables watching for
- read data, Bit #1 (value 2) enables watching for write data.
+ $iow = $iow->events ($eventmask)
+ Set the event mask to watch. Bit #0 (value 1) enables watching
+ for read data, Bit #1 (value 2) enables watching for write data.
- $iow = $iow->start
- Start watching for requested events on the given handle.
+ $iow = $iow->start
+ Start watching for requested events on the given handle.
- $iow = $iow->stop
- Stop watching for events on the given filehandle.
+ $iow = $iow->stop
+ Stop watching for events on the given filehandle.
ENVIRONMENT
URXVT_PERL_VERBOSITY
- This variable controls the verbosity level of the perl extension. Higher
- numbers indicate more verbose output.
+ This variable controls the verbosity level of the perl extension.
+ Higher numbers indicate more verbose output.
- =0 - only fatal messages
- =3 - script loading and management
- =10 - all events received
+ =0 - only fatal messages
+ =3 - script loading and management
+ =10 - all events received
AUTHOR
- Marc Lehmann <pcg@goof.com>
- http://software.schmorp.de/pkg/rxvt-unicode
+
Marc Lehmann <pcg@goof.com>
+ http://software.schmorp.de/pkg/rxvt-unicode
#endif
#if ENABLE_PERL
+ if (!rs[Rs_perl_ext_1])
+ rs[Rs_perl_ext_1] = "default";
+
if ((rs[Rs_perl_ext_1] && *rs[Rs_perl_ext_1])
|| (rs[Rs_perl_ext_2] && *rs[Rs_perl_ext_2])
|| (rs[Rs_perl_eval] && *rs[Rs_perl_eval]))
projects / dana / urxvt.git / commitdiff