perl*-resources and keysym resources.
- fix directory permissions on install.
- improved sched_yield support.
- - meta8 support was forcefully enabled in most configurations,
+ - meta8 support was forcefully enabled in most configurations.
restored configurability of this (useless) feature (reported
by Mikachu)
src/rxvtperl.h
src/rxvtperl.C
-src/perl/simple-overlay-clock
+src/perl/example-refresh-hooks
src/perl/digital-clock
src/perl/selection
<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__term_class">The <code>urxvt::term</code> Class</a></li>
<li><a href="#the_urxvt__timer_class">The <code>urxvt::timer</code> Class</a></li>
<li><a href="#the_urxvt__iow_class">The <code>urxvt::iow</code> Class</a></li>
</ul>
<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.
+Displays a digital clock using the built-in overlay.
</dd>
<p></p>
-<dt><strong><a name="item_simple_2doverlay_2dclock">simple-overlay-clock</a></strong><br />
+<dt><strong><a name="item_example_2drefresh_2dhooks">example-refresh-hooks</a></strong><br />
</dt>
<dd>
-Displays a digital clock using the built-in overlay (colorful, useless).
+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></dl>
<p>
<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 to start when creating renditions.
+</dd>
+<p></p>
+<dt><strong><a name="item__24rend__3d_urxvt_3a_3aoverlay_rstyle">$rend = urxvt::OVERLAY_RSTYLE</a></strong><br />
+</dt>
+<dd>
+Return the rendition mask used for overlays by default.
+</dd>
+<p></p>
+<dt><strong><a name="item__24rendbit__3d_urxvt_3a_3ars_bold_2c_rs_italic_2c_">$rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline</a></strong><br />
+</dt>
+<dd>
+Return the bit that enabled bold, italic, blink, reverse-video and
+underline, respectively. To enable such a style, just logically OR it into
+the bitset.
+</dd>
+<p></p>
+<dt><strong><a name="item__24foreground__3d_urxvt_3a_3aget_basefg__24rend">$foreground = urxvt::GET_BASEFG $rend</a></strong><br />
+</dt>
+<dt><strong><a name="item__24background__3d_urxvt_3a_3aget_basebg__24rend">$background = urxvt::GET_BASEBG $rend</a></strong><br />
+</dt>
+<dd>
+Return the foreground/background colour index, respectively.
+</dd>
+<p></p>
+<dt><strong><a name="item_set_fgcolor">$rend = urxvt::SET_FGCOLOR ($rend, $new_colour)</a></strong><br />
+</dt>
+<dt><strong><a name="item_set_bgcolor">$rend = urxvt::SET_BGCOLOR ($rend, $new_colour)</a></strong><br />
+</dt>
+<dd>
+Replace the foreground/background colour in the rendition mask with the
+specified one.
+</dd>
+<p></p>
+<dt><strong><a name="item_get_custom">$value = urxvt::GET_CUSTOM ($rend)</a></strong><br />
+</dt>
+<dd>
+Return the ``custom'' value: Every rendition has 5 bits for use by
+extensions. They can be set and changed as you like and are initially
+zero.
+</dd>
+<p></p>
+<dt><strong><a name="item_set_custom">$rend = urxvt::SET_CUSTOM ($rend, $new_value)</a></strong><br />
+</dt>
+<dd>
+Change the custom value.
+</dd>
+<p></p></dl>
+<p>
+</p>
<h2><a name="the_urxvt__term_class">The <code>urxvt::term</code> Class</a></h2>
<dl>
<dt><strong><a name="item_resource">$value = $term->resource ($name[, $newval])</a></strong><br />
<dd>
Return the current selection text and optionally replace it by <code>$newtext</code>.
</dd>
-<p></p>
-<dt><strong><a name="item_scr_overlay">$term->scr_overlay ($x, $y, $text)</a></strong><br />
-</dt>
<dd>
-Create a simple multi-line overlay box. See the next method for details.
+<p>#=item $term->overlay ($x, $y, $text)
+#
+#Create a simple multi-line overlay box. See the next method for details.
+#
+#=cut</p>
+</dd>
+<dd>
+<p>sub urxvt::term::scr_overlay {
+die;
+ my ($self, $x, $y, $text) = @_;</p>
+</dd>
+<dd>
+<pre>
+ my @lines = split /\n/, $text;</pre>
+</dd>
+<dd>
+<pre>
+ my $w = 0;
+ for (map $self->strwidth ($_), @lines) {
+ $w = $_ if $w < $_;
+ }</pre>
+</dd>
+<dd>
+<pre>
+ $self->scr_overlay_new ($x, $y, $w, scalar @lines);
+ $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
+}</pre>
</dd>
<p></p>
-<dt><strong><a name="item_scr_overlay_new">$term->scr_overlay_new ($x, $y, $width, $height)</a></strong><br />
+<dt><strong><a name="item_overlay">$term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])</a></strong><br />
</dt>
<dd>
Create a new (empty) overlay at the given position with the given
-width/height. A border will be put around the box. If either <code>$x</code> or
-<code>$y</code> is negative, then this is counted from the right/bottom side,
-respectively.
+width/height. <code>$rstyle</code> defines the initial rendition style
+(default: <code>OVERLAY_RSTYLE</code>).
</dd>
-<p></p>
-<dt><strong><a name="item_scr_overlay_off">$term->scr_overlay_off</a></strong><br />
-</dt>
<dd>
-Switch the overlay off again.
+<p>If <code>$border</code> is <code>2</code> (default), then a decorative border will be put
+around the box.</p>
+</dd>
+<dd>
+<p>If either <code>$x</code> or <code>$y</code> is negative, then this is counted from the
+right/bottom side, respectively.</p>
+</dd>
+<dd>
+<p>This method returns an urxvt::overlay object. The overlay will be visible
+as long as the perl object is referenced.</p>
</dd>
-<p></p>
-<dt><strong><a name="item_scr_overlay_set_char">$term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE)</a></strong><br />
-</dt>
<dd>
-Put a single character (specified numerically) at the given overlay
-position.
+<p>Currently, the only method on the <code>urxvt::overlay</code> object is <a href="#item_set"><code>set</code></a>:</p>
</dd>
<p></p>
-<dt><strong><a name="item_scr_overlay_set">$term->scr_overlay_set ($x, $y, $text)</a></strong><br />
+<dt><strong><a name="item_set">$overlay->set ($x, $y, $text, $rend)</a></strong><br />
</dt>
<dd>
-Write a string at the given position into the overlay.
+Similar to <a href="#item_row_t"><code>$term->ROW_t</code></a> and <a href="#item_row_r"><code>$term->ROW_r</code></a> in that it puts
+text in rxvt-unicode's special encoding and an array of rendition values
+at a specific position inside the overlay.
</dd>
<p></p>
<dt><strong><a name="item_strwidth">$cellwidth = $term->strwidth $string</a></strong><br />
<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
+to replace only parts of a line. The font index in the rendition will
automatically be updated.</p>
</dd>
<dd>
<p>When setting rendition, the font mask will be ignored.</p>
</dd>
<dd>
-<p>See the section on RENDITION, below.</p>
+<p>See the section on RENDITION, above.</p>
</dd>
<p></p>
<dt><strong><a name="item_row_l">$length = $term->ROW_l ($row_number[, $new_length])</a></strong><br />
<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>
-</p>
<h2><a name="the_urxvt__timer_class">The <code>urxvt::timer</code> Class</a></h2>
<p>This class implements timer watchers/events. Time is represented as a
fractional number of seconds since the epoch. Example:</p>
<pre>
- # create a digital clock display in upper right corner
+ $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
$term->{timer} = urxvt::timer
->new
- ->start (urxvt::NOW)
+ ->interval (1)
->cb (sub {
- my ($timer) = @_;
- my $time = $timer->at;
- $timer->start ($time + 1);
- $self->scr_overlay (-1, 0,
- POSIX::strftime "%H:%M:%S", localtime $time);
+ $term->{overlay}->set (0, 0,
+ sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
});</pre>
<dl>
<dt><strong><a name="item__24timer__3d_new_urxvt_3a_3atimer">$timer = new urxvt::timer</a></strong><br />
</dt>
<dd>
-Create a new timer object in stopped state.
+Create a new timer object in started state. It is scheduled to fire
+immediately.
</dd>
<p></p>
<dt><strong><a name="item_cb">$timer = $timer->cb (sub { my ($timer) = @_; ... })</a></strong><br />
Return the time this watcher will fire next.
</dd>
<p></p>
-<dt><strong><a name="item_set">$timer = $timer->set ($tstamp)</a></strong><br />
+<dt><strong>$timer = $timer->set ($tstamp)</strong><br />
</dt>
<dd>
Set the time the event is generated to $tstamp.
</dd>
<p></p>
+<dt><strong><a name="item_interval">$timer = $timer->interval ($interval)</a></strong><br />
+</dt>
+<dd>
+Normally (and when <code>$interval</code> is <code>0</code>), the timer will automatically
+stop after it has fired once. If <code>$interval</code> is non-zero, then the timer
+is automatically rescheduled at the given intervals.
+</dd>
+<p></p>
<dt><strong><a name="item_start">$timer = $timer->start</a></strong><br />
</dt>
<dd>
.RE
.IP "digital-clock" 4
.IX Item "digital-clock"
+Displays a digital clock using the built-in overlay.
+.IP "example-refresh-hooks" 4
+.IX Item "example-refresh-hooks"
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 "$time = urxvt::NOW" 4
.IX Item "$time = urxvt::NOW"
Returns the \*(L"current time\*(R" (as per the event loop).
+.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 to start when creating renditions.
+.IP "$rend = urxvt::OVERLAY_RSTYLE" 4
+.IX Item "$rend = urxvt::OVERLAY_RSTYLE"
+Return the rendition mask used for overlays by default.
+.IP "$rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline" 4
+.IX Item "$rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline"
+Return the bit that enabled bold, italic, blink, reverse-video and
+underline, respectively. To enable such a style, just logically \s-1OR\s0 it into
+the bitset.
+.ie n .IP "$foreground = urxvt::GET_BASEFG $rend" 4
+.el .IP "$foreground = urxvt::GET_BASEFG \f(CW$rend\fR" 4
+.IX Item "$foreground = urxvt::GET_BASEFG $rend"
+.PD 0
+.ie n .IP "$background = urxvt::GET_BASEBG $rend" 4
+.el .IP "$background = urxvt::GET_BASEBG \f(CW$rend\fR" 4
+.IX Item "$background = urxvt::GET_BASEBG $rend"
+.PD
+Return the foreground/background colour index, respectively.
+.ie n .IP "$rend = urxvt::SET_FGCOLOR ($rend, $new_colour)" 4
+.el .IP "$rend = urxvt::SET_FGCOLOR ($rend, \f(CW$new_colour\fR)" 4
+.IX Item "$rend = urxvt::SET_FGCOLOR ($rend, $new_colour)"
+.PD 0
+.ie n .IP "$rend = urxvt::SET_BGCOLOR ($rend, $new_colour)" 4
+.el .IP "$rend = urxvt::SET_BGCOLOR ($rend, \f(CW$new_colour\fR)" 4
+.IX Item "$rend = urxvt::SET_BGCOLOR ($rend, $new_colour)"
+.PD
+Replace the foreground/background colour in the rendition mask with the
+specified one.
+.IP "$value = urxvt::GET_CUSTOM ($rend)" 4
+.IX Item "$value = urxvt::GET_CUSTOM ($rend)"
+Return the \*(L"custom\*(R" value: Every rendition has 5 bits for use by
+extensions. They can be set and changed as you like and are initially
+zero.
+.ie n .IP "$rend = urxvt::SET_CUSTOM ($rend, $new_value)" 4
+.el .IP "$rend = urxvt::SET_CUSTOM ($rend, \f(CW$new_value\fR)" 4
+.IX Item "$rend = urxvt::SET_CUSTOM ($rend, $new_value)"
+Change the custom value.
.ie n .Sh "The ""urxvt::term"" Class"
.el .Sh "The \f(CWurxvt::term\fP Class"
.IX Subsection "The urxvt::term Class"
.el .IP "$oldtext = \f(CW$term\fR\->selection ([$newtext])" 4
.IX Item "$oldtext = $term->selection ([$newtext])"
Return the current selection text and optionally replace it by \f(CW$newtext\fR.
-.ie n .IP "$term\->scr_overlay ($x, $y\fR, \f(CW$text)" 4
-.el .IP "$term\->scr_overlay ($x, \f(CW$y\fR, \f(CW$text\fR)" 4
-.IX Item "$term->scr_overlay ($x, $y, $text)"
-Create a simple multi-line overlay box. See the next method for details.
-.ie n .IP "$term\->scr_overlay_new ($x, $y\fR, \f(CW$width\fR, \f(CW$height)" 4
-.el .IP "$term\->scr_overlay_new ($x, \f(CW$y\fR, \f(CW$width\fR, \f(CW$height\fR)" 4
-.IX Item "$term->scr_overlay_new ($x, $y, $width, $height)"
+.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
+.Sp
+sub urxvt::term::scr_overlay {
+die;
+ my ($self, \f(CW$x\fR, \f(CW$y\fR, \f(CW$text\fR) = \f(CW@_\fR;
+.Sp
+.Vb 1
+\& my @lines = split /\en/, $text;
+.Ve
+.Sp
+.Vb 4
+\& my $w = 0;
+\& for (map $self->strwidth ($_), @lines) {
+\& $w = $_ if $w < $_;
+\& }
+.Ve
+.Sp
+.Vb 3
+\& $self->scr_overlay_new ($x, $y, $w, scalar @lines);
+\& $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
+\&}
+.Ve
+.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]])"
Create a new (empty) overlay at the given position with the given
-width/height. A border will be put around the box. If either \f(CW$x\fR or
-\&\f(CW$y\fR is negative, then this is counted from the right/bottom side,
-respectively.
-.IP "$term\->scr_overlay_off" 4
-.IX Item "$term->scr_overlay_off"
-Switch the overlay off again.
-.ie n .IP "$term\->scr_overlay_set_char ($x, $y\fR, \f(CW$char\fR, \f(CW$rend = \s-1OVERLAY_RSTYLE\s0)" 4
-.el .IP "$term\->scr_overlay_set_char ($x, \f(CW$y\fR, \f(CW$char\fR, \f(CW$rend\fR = \s-1OVERLAY_RSTYLE\s0)" 4
-.IX Item "$term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE)"
-Put a single character (specified numerically) at the given overlay
-position.
-.ie n .IP "$term\->scr_overlay_set ($x, $y\fR, \f(CW$text)" 4
-.el .IP "$term\->scr_overlay_set ($x, \f(CW$y\fR, \f(CW$text\fR)" 4
-.IX Item "$term->scr_overlay_set ($x, $y, $text)"
-Write a string at the given position into the overlay.
+width/height. \f(CW$rstyle\fR defines the initial rendition style
+(default: \f(CW\*(C`OVERLAY_RSTYLE\*(C'\fR).
+.Sp
+If \f(CW$border\fR is \f(CW2\fR (default), then a decorative border will be put
+around the box.
+.Sp
+If either \f(CW$x\fR or \f(CW$y\fR is negative, then this is counted from the
+right/bottom side, respectively.
+.Sp
+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:
+.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.
.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"
.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
+to replace only parts of a line. The font index in the rendition will
automatically be updated.
.Sp
\&\f(CW$text\fR is in a special encoding: tabs and wide characters that use more
.Sp
When setting rendition, the font mask will be ignored.
.Sp
-See the section on \s-1RENDITION\s0, below.
+See the section on \s-1RENDITION\s0, above.
.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])"
.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"
This class implements timer watchers/events. Time is represented as a
fractional number of seconds since the epoch. Example:
.PP
-.Vb 11
-\& # create a digital clock display in upper right corner
+.Vb 8
+\& $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
\& $term->{timer} = urxvt::timer
\& ->new
-\& ->start (urxvt::NOW)
+\& ->interval (1)
\& ->cb (sub {
-\& my ($timer) = @_;
-\& my $time = $timer->at;
-\& $timer->start ($time + 1);
-\& $self->scr_overlay (-1, 0,
-\& POSIX::strftime "%H:%M:%S", localtime $time);
+\& $term->{overlay}->set (0, 0,
+\& sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
\& });
.Ve
.IP "$timer = new urxvt::timer" 4
.IX Item "$timer = new urxvt::timer"
-Create a new timer object in stopped state.
+Create a new timer object in started state. It is scheduled to fire
+immediately.
.ie n .IP "$timer = $timer\fR\->cb (sub { my ($timer) = \f(CW@_; ... })" 4
.el .IP "$timer = \f(CW$timer\fR\->cb (sub { my ($timer) = \f(CW@_\fR; ... })" 4
.IX Item "$timer = $timer->cb (sub { my ($timer) = @_; ... })"
.el .IP "$timer = \f(CW$timer\fR\->set ($tstamp)" 4
.IX Item "$timer = $timer->set ($tstamp)"
Set the time the event is generated to \f(CW$tstamp\fR.
+.ie n .IP "$timer = $timer\->interval ($interval)" 4
+.el .IP "$timer = \f(CW$timer\fR\->interval ($interval)" 4
+.IX Item "$timer = $timer->interval ($interval)"
+Normally (and when \f(CW$interval\fR is \f(CW0\fR), the timer will automatically
+stop after it has fired once. If \f(CW$interval\fR is non\-zero, then the timer
+is automatically rescheduled at the given intervals.
.ie n .IP "$timer = $timer\->start" 4
.el .IP "$timer = \f(CW$timer\fR\->start" 4
.IX Item "$timer = $timer->start"
URxvt.keysym.C-M-r: perl:selection:rot13
digital-clock
+ Displays a digital clock using the built-in overlay.
+
+ example-refresh-hooks
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
$time = urxvt::NOW
Returns the "current time" (as per the event loop).
+ 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 to start when creating
+ renditions.
+
+ $rend = urxvt::OVERLAY_RSTYLE
+ Return the rendition mask used for overlays by default.
+
+ $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
+ Return the bit that enabled bold, italic, blink, reverse-video and
+ underline, respectively. To enable such a style, just logically OR
+ it into the bitset.
+
+ $foreground = urxvt::GET_BASEFG $rend
+ $background = urxvt::GET_BASEBG $rend
+ Return the foreground/background colour index, respectively.
+
+ $rend = urxvt::SET_FGCOLOR ($rend, $new_colour)
+ $rend = urxvt::SET_BGCOLOR ($rend, $new_colour)
+ Replace the foreground/background colour in the rendition mask with
+ the specified one.
+
+ $value = urxvt::GET_CUSTOM ($rend)
+ Return the "custom" value: Every rendition has 5 bits for use by
+ extensions. They can be set and changed as you like and are
+ initially zero.
+
+ $rend = urxvt::SET_CUSTOM ($rend, $new_value)
+ Change the custom value.
+
The "urxvt::term" Class
$value = $term->resource ($name[, $newval])
Returns the current resource value associated with a given name and
Return the current selection text and optionally replace it by
$newtext.
- $term->scr_overlay ($x, $y, $text)
- Create a simple multi-line overlay box. See the next method for
- details.
+ #=item $term->overlay ($x, $y, $text) # #Create a simple multi-line
+ overlay box. See the next method for details. # #=cut
- $term->scr_overlay_new ($x, $y, $width, $height)
+ sub urxvt::term::scr_overlay { die; 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 ($x, $y, $width, $height[, $rstyle[, $border]])
Create a new (empty) overlay at the given position with the given
- width/height. A border will be put around the box. If either $x or
- $y is negative, then this is counted from the right/bottom side,
- respectively.
+ width/height. $rstyle defines the initial rendition style (default:
+ "OVERLAY_RSTYLE").
+
+ If $border is 2 (default), then a decorative border will be put
+ around the box.
- $term->scr_overlay_off
- Switch the overlay off again.
+ If either $x or $y is negative, then this is counted from the
+ right/bottom side, respectively.
- $term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE)
- Put a single character (specified numerically) at the given overlay
- position.
+ This method returns an urxvt::overlay object. The overlay will be
+ visible as long as the perl object is referenced.
- $term->scr_overlay_set ($x, $y, $text)
- Write a string at the given position into the overlay.
+ Currently, the only method on the "urxvt::overlay" object is "set":
+
+ $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.
$cellwidth = $term->strwidth $string
Returns the number of screen-cells this string would need. Correctly
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
+ replace only parts of a line. The font index in the rendition will
automatically be updated.
$text is in a special encoding: tabs and wide characters that use
When setting rendition, the font mask will be ignored.
- See the section on RENDITION, below.
+ See the section on RENDITION, above.
$length = $term->ROW_l ($row_number[, $new_length])
Returns the number of screen cells that are in use ("the line
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
fractional number of seconds since the epoch. Example:
- # create a digital clock display in upper right corner
+ $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
$term->{timer} = urxvt::timer
->new
- ->start (urxvt::NOW)
+ ->interval (1)
->cb (sub {
- my ($timer) = @_;
- my $time = $timer->at;
- $timer->start ($time + 1);
- $self->scr_overlay (-1, 0,
- POSIX::strftime "%H:%M:%S", localtime $time);
- });
+ $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 stopped state.
+ 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->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->start
Start the timer.
#! perl
-# this creates a simple digital clock by overwriting the refresh hooks
+# this creates a simple digital clock
sub on_init {
my ($self) = @_;
- # force a refresh every second
- $self->{digital_clock_refresh} = urxvt::timer
+ $self->{digital_clock_overlay} = $self->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
+ $self->{digital_clock_timer} = urxvt::timer
->new
- ->start (urxvt::NOW)
+ ->interval (1)
->cb (sub {
- $self->{digital_clock_refresh}->start ($self->{digital_clock_refresh}->at + 1);
- $self->want_refresh;
+ $self->{digital_clock_overlay}->set (0, 0,
+ sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
});
()
}
-# before refreshing: replace upper right with the clock display
-sub on_refresh_begin {
- my ($self) = @_;
-
- my $time = sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2, 1, 0];
- my $xpos = $self->ncol - length $time;
-
- $xpos >= 0
- or return;
-
- $self->{digital_clock_rend} = $self->ROW_r (0, [(urxvt::DEFAULT_RSTYLE) x length $time], $xpos);
- $self->{digital_clock_text} = $self->ROW_t (0, $time, $xpos);
-
- ()
-}
-
-# after refreshing: restore previous screen contents
-sub on_refresh_end {
- my ($self) = @_;
-
- exists $self->{digital_clock_text}
- or return;
-
- $self->ROW_r (0, delete $self->{digital_clock_rend});
- $self->ROW_t (0, delete $self->{digital_clock_text});
-
- ()
-}
-
--- /dev/null
+#! perl
+
+# this creates a simple digital clock by overwriting the refresh hooks
+
+sub on_init {
+ my ($self) = @_;
+
+ # force a refresh every second
+ $self->{digital_clock_refresh} = urxvt::timer
+ ->new
+ ->start (urxvt::NOW)
+ ->cb (sub {
+ $self->{digital_clock_refresh}->start ($self->{digital_clock_refresh}->at + 1);
+ $self->want_refresh;
+ });
+
+ ()
+}
+
+# before refreshing: replace upper right with the clock display
+sub on_refresh_begin {
+ my ($self) = @_;
+
+ my $time = sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2, 1, 0];
+ my $xpos = $self->ncol - length $time;
+
+ $xpos >= 0
+ or return;
+
+ $self->{digital_clock_rend} = $self->ROW_r (0, [(urxvt::DEFAULT_RSTYLE) x length $time], $xpos);
+ $self->{digital_clock_text} = $self->ROW_t (0, $time, $xpos);
+
+ ()
+}
+
+# after refreshing: restore previous screen contents
+sub on_refresh_end {
+ my ($self) = @_;
+
+ exists $self->{digital_clock_text}
+ or return;
+
+ $self->ROW_r (0, delete $self->{digital_clock_rend});
+ $self->ROW_t (0, delete $self->{digital_clock_text});
+
+ ()
+}
+
+
+++ /dev/null
-#! perl
-
-# this creates a simple clock using the overlay box. it is not very useful, because
-# it makes the iso14755 mode almost useles as its box gets destroyed every second.
-
-use POSIX ();
-
-sub on_init {
- my ($self) = @_;
-
- $self->{timer} = urxvt::timer
- ->new
- ->start (urxvt::NOW)
- ->cb (sub {
- my ($timer) = @_;
- my $time = $timer->at;
- $timer->start ($time + 1);
- $self->scr_overlay (-1, 0, POSIX::strftime "%H:%M:%S", localtime $time);
- });
-
- ()
-}
-
struct timer : time_watcher, perl_watcher
{
+ tstamp interval;
+
timer ()
: time_watcher (this, &timer::execute)
{
void execute (time_watcher &w)
{
+ if (interval)
+ start (at + interval);
+
invoke ("urxvt::timer", newSVtimer (this));
}
};
}
};
+/////////////////////////////////////////////////////////////////////////////
+
+#define SvOVERLAY(sv) (overlay *)SvPTR (sv, "urxvt::overlay")
+
+struct overlay {
+ HV *self;
+ rxvt_term *THIS;
+ int x, y, w, h;
+ int border;
+ text_t **text;
+ rend_t **rend;
+
+ overlay (rxvt_term *THIS, int x_, int y_, int w_, int h_, rend_t rstyle, int border);
+ ~overlay ();
+
+ void swap ();
+
+ void set (int x, int y, SV *str, SV *rend);
+};
+
+overlay::overlay (rxvt_term *THIS, int x_, int y_, int w_, int h_, rend_t rstyle, int border)
+: THIS(THIS), x(x_), y(y_), w(w_), h(h_), border(border == 2)
+{
+ if (border == 2)
+ {
+ w += 2;
+ h += 2;
+ }
+
+ text = new text_t *[h];
+ rend = new rend_t *[h];
+
+ for (int y = 0; y < h; y++)
+ {
+ text_t *tp = text[y] = new text_t[w];
+ rend_t *rp = rend[y] = new rend_t[w];
+
+ text_t t0, t1, t2;
+ rend_t r = rstyle;
+
+ if (border == 2)
+ {
+ if (y == 0)
+ t0 = 0x2554, t1 = 0x2550, t2 = 0x2557;
+ else if (y < h - 1)
+ t0 = 0x2551, t1 = 0x0020, t2 = 0x2551;
+ else
+ t0 = 0x255a, t1 = 0x2550, t2 = 0x255d;
+
+ *tp++ = t0;
+ *rp++ = r;
+
+ for (int x = w - 2; x-- > 0; )
+ {
+ *tp++ = t1;
+ *rp++ = r;
+ }
+
+ *tp = t2;
+ *rp = r;
+ }
+ else
+ for (int x = w; x-- > 0; )
+ {
+ *tp++ = 0x0020;
+ *rp++ = r;
+ }
+ }
+
+ THIS->want_refresh = 1;
+}
+
+overlay::~overlay ()
+{
+ for (int y = h; y--; )
+ {
+ delete [] text[y];
+ delete [] rend[y];
+ }
+
+ delete [] text;
+ delete [] rend;
+
+ THIS->want_refresh = 1;
+}
+
+void overlay::swap ()
+{
+ int ov_x = max (0, min (MOD (x, THIS->ncol), THIS->ncol - w));
+ int ov_y = max (0, min (MOD (y, THIS->nrow), THIS->nrow - h));
+
+ int ov_w = min (w, THIS->ncol - ov_x);
+ int ov_h = min (h, THIS->nrow - ov_y);
+
+ for (int y = ov_h; y--; )
+ {
+ text_t *t1 = text [y];
+ rend_t *r1 = rend [y];
+
+ text_t *t2 = ROW(y + ov_y - THIS->view_start).t + ov_x;
+ rend_t *r2 = ROW(y + ov_y - THIS->view_start).r + ov_x;
+
+ for (int x = ov_w; x--; )
+ {
+ text_t t = *t1; *t1++ = *t2; *t2++ = t;
+ rend_t r = *r1; *r1++ = *r2; *r2++ = SET_FONT (r, THIS->fontset [GET_STYLE (r)]->find_font (t));
+ }
+ }
+
+}
+
+void overlay::set (int x, int y, SV *str, SV *rend)
+{
+ x += border;
+ y += border;
+
+ if (!IN_RANGE_EXC (y, 0, h - border))
+ return;
+
+ wchar_t *wstr = sv2wcs (str);
+
+ for (int col = min (wcslen (wstr), w - x - border); col--; )
+ text [y][x + col] = wstr [col];
+
+ free (wstr);
+
+ THIS->want_refresh = 1;
+}
+
+
/////////////////////////////////////////////////////////////////////////////
struct rxvt_perl_interp rxvt_perl;
bool
rxvt_perl_interp::invoke (rxvt_term *term, hook_type htype, ...)
{
- if (!perl
- || (!should_invoke [htype] && htype != HOOK_INIT && htype != HOOK_DESTROY))
+ if (!perl)
return false;
if (htype == HOOK_INIT) // first hook ever called
- term->self = (void *)newSVptr ((void *)term, "urxvt::term");
+ {
+ term->self = (void *)newSVptr ((void *)term, "urxvt::term");
+ hv_store ((HV *)SvRV ((SV *)term->self), "_overlay", 8, newRV_noinc ((SV *)newHV ()), 0);
+ }
+ else if (htype == HOOK_DESTROY)
+ {
+ // handled later
+ }
+ else if (htype == HOOK_REFRESH_BEGIN || htype == HOOK_REFRESH_END)
+ {
+ HV *hv = (HV *)SvRV (*hv_fetch ((HV *)SvRV ((SV *)term->self), "_overlay", 8, 0));
+
+ if (HvKEYS (hv))
+ {
+ hv_iterinit (hv);
+
+ while (HE *he = hv_iternext (hv))
+ ((overlay *)SvIV (hv_iterval (hv, he)))->swap ();
+ }
+ }
+ else if (!should_invoke [htype])
+ return false;
dSP;
va_list ap;
if (new_text)
{
- STRLEN slen;
- char *str = SvPVutf8 (new_text, slen);
- wchar_t *wstr = rxvt_utf8towcs (str, slen);
+ wchar_t *wstr = sv2wcs (new_text);
int len = wcslen (wstr);
}
void
-rxvt_term::scr_overlay_new (int x, int y, int w, int h)
+rxvt_term::tt_write (SV *octets)
+ INIT:
+ STRLEN len;
+ char *str = SvPVbyte (octets, len);
+ C_ARGS:
+ (unsigned char *)str, len
-void
-rxvt_term::scr_overlay_off ()
+SV *
+rxvt_term::overlay (int x, int y, int w, int h, int rstyle = OVERLAY_RSTYLE, int border = 2)
+ CODE:
+{
+ overlay *o = new overlay (THIS, x, y, w, h, rstyle, border);
+ RETVAL = newSVptr ((void *)o, "urxvt::overlay");
+ o->self = (HV *)SvRV (RETVAL);
+
+ HV *hv = (HV *)SvRV (*hv_fetch ((HV *)SvRV ((SV *)THIS->self), "_overlay", 8, 0));
+ char key[33]; sprintf (key, "%32lx", (long)o);
+ hv_store (hv, key, 32, newSViv ((long)o), 0);
+}
+ OUTPUT:
+ RETVAL
+
+MODULE = urxvt PACKAGE = urxvt::overlay
void
-rxvt_term::scr_overlay_set_char (int x, int y, U32 text, U32 rend = OVERLAY_RSTYLE)
- CODE:
- THIS->scr_overlay_set (x, y, text, rend);
+overlay::set (int x, int y, SV *text, SV *rend = 0)
void
-rxvt_term::scr_overlay_set (int x, int y, SV *text)
+overlay::DESTROY ()
CODE:
{
- wchar_t *wtext = sv2wcs (text);
- THIS->scr_overlay_set (x, y, wtext);
- free (wtext);
-}
+ SV **ovs = hv_fetch ((HV *)SvRV ((SV *)THIS->THIS->self), "_overlay", 8, 0);
+ if (ovs)
+ {
+ HV *hv = (HV *)SvRV (*ovs);
+ char key[33]; sprintf (key, "%32lx", (long)THIS);
+ hv_delete (hv, key, 32, G_DISCARD);
+ }
-void
-rxvt_term::tt_write (SV *octets)
- INIT:
- STRLEN len;
- char *str = SvPVbyte (octets, len);
- C_ARGS:
- (unsigned char *)str, len
+ delete THIS;
+}
MODULE = urxvt PACKAGE = urxvt::timer
timer::new ()
CODE:
timer *w = new timer;
+ w->start (NOW);
RETVAL = newSVptr ((void *)w, "urxvt::timer");
w->self = (HV *)SvRV (RETVAL);
OUTPUT:
OUTPUT:
RETVAL
+timer *
+timer::interval (NV interval)
+ CODE:
+ THIS->interval = interval;
+ RETVAL = THIS;
+ OUTPUT:
+ RETVAL
+
timer *
timer::set (NV tstamp)
CODE:
/*
* B: reverse any characters which are selected
*/
- PERL_INVOKE ((this, HOOK_REFRESH_BEGIN, DT_END));
scr_reverse_selection ();
/*
}
}
+ PERL_INVOKE ((this, HOOK_REFRESH_BEGIN, DT_END));
#if ENABLE_OVERLAY
scr_swap_overlay ();
#endif
#if ENABLE_OVERLAY
scr_swap_overlay ();
#endif
+ PERL_INVOKE ((this, HOOK_REFRESH_END, DT_END));
/*
* G: cleanup cursor and display outline cursor if necessary
* H: cleanup selection
*/
scr_reverse_selection ();
- PERL_INVOKE ((this, HOOK_REFRESH_END, DT_END));
if (refresh_type & SMOOTH_REFRESH)
XFlush (display->display);
rxvt_term * T_TERM
timer * T_TIMER
iow * T_IOW
+overlay * T_OVERLAY
INPUT
T_TERM
$var = SvTIMER ($arg);
T_IOW
$var = SvIOW ($arg);
+T_OVERLAY
+ $var = SvOVERLAY ($arg);
OUTPUT
T_TERM
Returns the "current time" (as per the event loop).
+=back
+
=head2 RENDITION
Rendition bitsets contain information about colour, font, font styles and
0
}
-=back
-
=head2 The C<urxvt::term> Class
=over 4
projects / dana / urxvt.git / commitdiff