ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/rxvt-unicode/doc/rxvtperl.3.html
(Generate patch)

Comparing rxvt-unicode/doc/rxvtperl.3.html (file contents):
Revision 1.7 by root, Tue Jan 3 01:45:12 2006 UTC vs.
Revision 1.8 by root, Tue Jan 3 04:20:37 2006 UTC

… …
19 19
20 <li><a href="#prepackaged_extensions">Prepackaged Extensions</a></li> 20 <li><a href="#prepackaged_extensions">Prepackaged Extensions</a></li>
21 <li><a href="#general_api_considerations">General API Considerations</a></li> 21 <li><a href="#general_api_considerations">General API Considerations</a></li>
22 <li><a href="#hooks">Hooks</a></li> 22 <li><a href="#hooks">Hooks</a></li>
23 <li><a href="#functions_in_the_urxvt_package">Functions in the <code>urxvt</code> Package</a></li> 23 <li><a href="#functions_in_the_urxvt_package">Functions in the <code>urxvt</code> Package</a></li>
24 <li><a href="#rendition">RENDITION</a></li>
24 <li><a href="#the_urxvt__term_class">The <code>urxvt::term</code> Class</a></li> 25 <li><a href="#the_urxvt__term_class">The <code>urxvt::term</code> Class</a></li>
25 <li><a href="#rendition">RENDITION</a></li>
26 <li><a href="#the_urxvt__timer_class">The <code>urxvt::timer</code> Class</a></li> 26 <li><a href="#the_urxvt__timer_class">The <code>urxvt::timer</code> Class</a></li>
27 <li><a href="#the_urxvt__iow_class">The <code>urxvt::iow</code> Class</a></li> 27 <li><a href="#the_urxvt__iow_class">The <code>urxvt::iow</code> Class</a></li>
28 </ul> 28 </ul>
29 29
30 <li><a href="#environment">ENVIRONMENT</a></li> 30 <li><a href="#environment">ENVIRONMENT</a></li>
… …
94</dd> 94</dd>
95<p></p></dl> 95<p></p></dl>
96<dt><strong><a name="item_digital_2dclock">digital-clock</a></strong><br /> 96<dt><strong><a name="item_digital_2dclock">digital-clock</a></strong><br />
97</dt> 97</dt>
98<dd> 98<dd>
99Displays a digital clock using the built-in overlay.
100</dd>
101<p></p>
102<dt><strong><a name="item_example_2drefresh_2dhooks">example-refresh-hooks</a></strong><br />
103</dt>
104<dd>
99Displays a very simple digital clock in the upper right corner of the 105Displays a very simple digital clock in the upper right corner of the
100window. Illustrates overwriting the refresh callbacks to create your own 106window. Illustrates overwriting the refresh callbacks to create your own
101overlays or changes. 107overlays or changes.
102</dd>
103<p></p>
104<dt><strong><a name="item_simple_2doverlay_2dclock">simple-overlay-clock</a></strong><br />
105</dt>
106<dd>
107Displays a digital clock using the built-in overlay (colorful, useless).
108</dd> 108</dd>
109<p></p></dl> 109<p></p></dl>
110<p> 110<p>
111</p> 111</p>
112<h2><a name="general_api_considerations">General API Considerations</a></h2> 112<h2><a name="general_api_considerations">General API Considerations</a></h2>
… …
264<p></p> 264<p></p>
265<dt><strong><a name="item__24time__3d_urxvt_3a_3anow">$time = urxvt::NOW</a></strong><br /> 265<dt><strong><a name="item__24time__3d_urxvt_3a_3anow">$time = urxvt::NOW</a></strong><br />
266</dt> 266</dt>
267<dd> 267<dd>
268Returns the ``current time'' (as per the event loop). 268Returns the ``current time'' (as per the event loop).
269</dd>
270<p></p></dl>
271<p>
272</p>
273<h2><a name="rendition">RENDITION</a></h2>
274<p>Rendition bitsets contain information about colour, font, font styles and
275similar information for each screen cell.</p>
276<p>The following ``macros'' deal with changes in rendition sets. You should
277never just create a bitset, you should always modify an existing one,
278as they contain important information required for correct operation of
279rxvt-unicode.</p>
280<dl>
281<dt><strong><a name="item__24rend__3d_urxvt_3a_3adefault_rstyle">$rend = urxvt::DEFAULT_RSTYLE</a></strong><br />
282</dt>
283<dd>
284Returns the default rendition, as used when the terminal is starting up or
285being reset. Useful as a base to start when creating renditions.
286</dd>
287<p></p>
288<dt><strong><a name="item__24rend__3d_urxvt_3a_3aoverlay_rstyle">$rend = urxvt::OVERLAY_RSTYLE</a></strong><br />
289</dt>
290<dd>
291Return the rendition mask used for overlays by default.
292</dd>
293<p></p>
294<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 />
295</dt>
296<dd>
297Return the bit that enabled bold, italic, blink, reverse-video and
298underline, respectively. To enable such a style, just logically OR it into
299the bitset.
300</dd>
301<p></p>
302<dt><strong><a name="item__24foreground__3d_urxvt_3a_3aget_basefg__24rend">$foreground = urxvt::GET_BASEFG $rend</a></strong><br />
303</dt>
304<dt><strong><a name="item__24background__3d_urxvt_3a_3aget_basebg__24rend">$background = urxvt::GET_BASEBG $rend</a></strong><br />
305</dt>
306<dd>
307Return the foreground/background colour index, respectively.
308</dd>
309<p></p>
310<dt><strong><a name="item_set_fgcolor">$rend = urxvt::SET_FGCOLOR ($rend, $new_colour)</a></strong><br />
311</dt>
312<dt><strong><a name="item_set_bgcolor">$rend = urxvt::SET_BGCOLOR ($rend, $new_colour)</a></strong><br />
313</dt>
314<dd>
315Replace the foreground/background colour in the rendition mask with the
316specified one.
317</dd>
318<p></p>
319<dt><strong><a name="item_get_custom">$value = urxvt::GET_CUSTOM ($rend)</a></strong><br />
320</dt>
321<dd>
322Return the ``custom'' value: Every rendition has 5 bits for use by
323extensions. They can be set and changed as you like and are initially
324zero.
325</dd>
326<p></p>
327<dt><strong><a name="item_set_custom">$rend = urxvt::SET_CUSTOM ($rend, $new_value)</a></strong><br />
328</dt>
329<dd>
330Change the custom value.
269</dd> 331</dd>
270<p></p></dl> 332<p></p></dl>
271<p> 333<p>
272</p> 334</p>
273<h2><a name="the_urxvt__term_class">The <code>urxvt::term</code> Class</a></h2> 335<h2><a name="the_urxvt__term_class">The <code>urxvt::term</code> Class</a></h2>
… …
335<dt><strong>$oldtext = $term-&gt;selection ([$newtext])</strong><br /> 397<dt><strong>$oldtext = $term-&gt;selection ([$newtext])</strong><br />
336</dt> 398</dt>
337<dd> 399<dd>
338Return the current selection text and optionally replace it by <code>$newtext</code>. 400Return the current selection text and optionally replace it by <code>$newtext</code>.
339</dd> 401</dd>
340<p></p>
341<dt><strong><a name="item_scr_overlay">$term-&gt;scr_overlay ($x, $y, $text)</a></strong><br />
342</dt>
343<dd> 402<dd>
403<p>#=item $term-&gt;overlay ($x, $y, $text)
404#
344Create a simple multi-line overlay box. See the next method for details. 405#Create a simple multi-line overlay box. See the next method for details.
406#
407#=cut</p>
408</dd>
345</dd> 409<dd>
410<p>sub urxvt::term::scr_overlay {
411die;
412 my ($self, $x, $y, $text) = @_;</p>
413</dd>
414<dd>
415<pre>
416 my @lines = split /\n/, $text;</pre>
417</dd>
418<dd>
419<pre>
420 my $w = 0;
421 for (map $self-&gt;strwidth ($_), @lines) {
422 $w = $_ if $w &lt; $_;
423 }</pre>
424</dd>
425<dd>
426<pre>
427 $self-&gt;scr_overlay_new ($x, $y, $w, scalar @lines);
428 $self-&gt;scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
429}</pre>
430</dd>
346<p></p> 431<p></p>
347<dt><strong><a name="item_scr_overlay_new">$term-&gt;scr_overlay_new ($x, $y, $width, $height)</a></strong><br /> 432<dt><strong><a name="item_overlay">$term-&gt;overlay ($x, $y, $width, $height[, $rstyle[, $border]])</a></strong><br />
348</dt> 433</dt>
349<dd> 434<dd>
350Create a new (empty) overlay at the given position with the given 435Create a new (empty) overlay at the given position with the given
351width/height. A border will be put around the box. If either <code>$x</code> or 436width/height. <code>$rstyle</code> defines the initial rendition style
352<code>$y</code> is negative, then this is counted from the right/bottom side, 437(default: <code>OVERLAY_RSTYLE</code>).
353respectively.
354</dd>
355<p></p>
356<dt><strong><a name="item_scr_overlay_off">$term-&gt;scr_overlay_off</a></strong><br />
357</dt>
358<dd> 438</dd>
359Switch the overlay off again.
360</dd> 439<dd>
361<p></p> 440<p>If <code>$border</code> is <code>2</code> (default), then a decorative border will be put
362<dt><strong><a name="item_scr_overlay_set_char">$term-&gt;scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE)</a></strong><br /> 441around the box.</p>
363</dt>
364<dd> 442</dd>
365Put a single character (specified numerically) at the given overlay
366position.
367</dd> 443<dd>
368<p></p> 444<p>If either <code>$x</code> or <code>$y</code> is negative, then this is counted from the
369<dt><strong><a name="item_scr_overlay_set">$term-&gt;scr_overlay_set ($x, $y, $text)</a></strong><br /> 445right/bottom side, respectively.</p>
370</dt>
371<dd> 446</dd>
372Write a string at the given position into the overlay. 447<dd>
448<p>This method returns an urxvt::overlay object. The overlay will be visible
449as long as the perl object is referenced.</p>
450</dd>
451<dd>
452<p>Currently, the only method on the <code>urxvt::overlay</code> object is <a href="#item_set"><code>set</code></a>:</p>
453</dd>
454<p></p>
455<dt><strong><a name="item_set">$overlay-&gt;set ($x, $y, $text, $rend)</a></strong><br />
456</dt>
457<dd>
458Similar to <a href="#item_row_t"><code>$term-&gt;ROW_t</code></a> and <a href="#item_row_r"><code>$term-&gt;ROW_r</code></a> in that it puts
459text in rxvt-unicode's special encoding and an array of rendition values
460at a specific position inside the overlay.
373</dd> 461</dd>
374<p></p> 462<p></p>
375<dt><strong><a name="item_strwidth">$cellwidth = $term-&gt;strwidth $string</a></strong><br /> 463<dt><strong><a name="item_strwidth">$cellwidth = $term-&gt;strwidth $string</a></strong><br />
376</dt> 464</dt>
377<dd> 465<dd>
… …
442line <a href="#item_nsaved"><code>-$term-&gt;nsaved</code></a>. 530line <a href="#item_nsaved"><code>-$term-&gt;nsaved</code></a>.
443</dd> 531</dd>
444<dd> 532<dd>
445<p>If <code>$new_text</code> is specified, it will replace characters in the current 533<p>If <code>$new_text</code> is specified, it will replace characters in the current
446line, starting at column <code>$start_col</code> (default <code>0</code>), which is useful 534line, starting at column <code>$start_col</code> (default <code>0</code>), which is useful
447to replace only parts of a line. The font iindex in the rendition will 535to replace only parts of a line. The font index in the rendition will
448automatically be updated.</p> 536automatically be updated.</p>
449</dd> 537</dd>
450<dd> 538<dd>
451<p><code>$text</code> is in a special encoding: tabs and wide characters that use more 539<p><code>$text</code> is in a special encoding: tabs and wide characters that use more
452than one cell when displayed are padded with urxvt::NOCHAR characters 540than one cell when displayed are padded with urxvt::NOCHAR characters
… …
473</dd> 561</dd>
474<dd> 562<dd>
475<p>When setting rendition, the font mask will be ignored.</p> 563<p>When setting rendition, the font mask will be ignored.</p>
476</dd> 564</dd>
477<dd> 565<dd>
478<p>See the section on RENDITION, below.</p> 566<p>See the section on RENDITION, above.</p>
479</dd> 567</dd>
480<p></p> 568<p></p>
481<dt><strong><a name="item_row_l">$length = $term-&gt;ROW_l ($row_number[, $new_length])</a></strong><br /> 569<dt><strong><a name="item_row_l">$length = $term-&gt;ROW_l ($row_number[, $new_length])</a></strong><br />
482</dt> 570</dt>
483<dd> 571<dd>
… …
501<a href="#item_row_t"><code>$term-&gt;ROW_t</code></a> for details. 589<a href="#item_row_t"><code>$term-&gt;ROW_t</code></a> for details.
502</dd> 590</dd>
503<p></p></dl> 591<p></p></dl>
504<p> 592<p>
505</p> 593</p>
506<h2><a name="rendition">RENDITION</a></h2>
507<p>Rendition bitsets contain information about colour, font, font styles and
508similar information for each screen cell.</p>
509<p>The following ``macros'' deal with changes in rendition sets. You should
510never just create a bitset, you should always modify an existing one,
511as they contain important information required for correct operation of
512rxvt-unicode.</p>
513<dl>
514<dt><strong><a name="item__24rend__3d_urxvt_3a_3adefault_rstyle">$rend = urxvt::DEFAULT_RSTYLE</a></strong><br />
515</dt>
516<dd>
517Returns the default rendition, as used when the terminal is starting up or
518being reset. Useful as a base
519</dd>
520<p></p></dl>
521<p>
522</p>
523<h2><a name="the_urxvt__timer_class">The <code>urxvt::timer</code> Class</a></h2> 594<h2><a name="the_urxvt__timer_class">The <code>urxvt::timer</code> Class</a></h2>
524<p>This class implements timer watchers/events. Time is represented as a 595<p>This class implements timer watchers/events. Time is represented as a
525fractional number of seconds since the epoch. Example:</p> 596fractional number of seconds since the epoch. Example:</p>
526<pre> 597<pre>
527 # create a digital clock display in upper right corner 598 $term-&gt;{overlay} = $term-&gt;overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
528 $term-&gt;{timer} = urxvt::timer 599 $term-&gt;{timer} = urxvt::timer
529 -&gt;new 600 -&gt;new
530 -&gt;start (urxvt::NOW) 601 -&gt;interval (1)
531 -&gt;cb (sub { 602 -&gt;cb (sub {
532 my ($timer) = @_;
533 my $time = $timer-&gt;at;
534 $timer-&gt;start ($time + 1);
535 $self-&gt;scr_overlay (-1, 0, 603 $term-&gt;{overlay}-&gt;set (0, 0,
536 POSIX::strftime &quot;%H:%M:%S&quot;, localtime $time); 604 sprintf &quot;%2d:%02d:%02d&quot;, (localtime urxvt::NOW)[2,1,0]);
537 });</pre> 605 });</pre>
538<dl> 606<dl>
539<dt><strong><a name="item__24timer__3d_new_urxvt_3a_3atimer">$timer = new urxvt::timer</a></strong><br /> 607<dt><strong><a name="item__24timer__3d_new_urxvt_3a_3atimer">$timer = new urxvt::timer</a></strong><br />
540</dt> 608</dt>
541<dd> 609<dd>
542Create a new timer object in stopped state. 610Create a new timer object in started state. It is scheduled to fire
611immediately.
543</dd> 612</dd>
544<p></p> 613<p></p>
545<dt><strong><a name="item_cb">$timer = $timer-&gt;cb (sub { my ($timer) = @_; ... })</a></strong><br /> 614<dt><strong><a name="item_cb">$timer = $timer-&gt;cb (sub { my ($timer) = @_; ... })</a></strong><br />
546</dt> 615</dt>
547<dd> 616<dd>
… …
552</dt> 621</dt>
553<dd> 622<dd>
554Return the time this watcher will fire next. 623Return the time this watcher will fire next.
555</dd> 624</dd>
556<p></p> 625<p></p>
557<dt><strong><a name="item_set">$timer = $timer-&gt;set ($tstamp)</a></strong><br /> 626<dt><strong>$timer = $timer-&gt;set ($tstamp)</strong><br />
558</dt> 627</dt>
559<dd> 628<dd>
560Set the time the event is generated to $tstamp. 629Set the time the event is generated to $tstamp.
630</dd>
631<p></p>
632<dt><strong><a name="item_interval">$timer = $timer-&gt;interval ($interval)</a></strong><br />
633</dt>
634<dd>
635Normally (and when <code>$interval</code> is <code>0</code>), the timer will automatically
636stop after it has fired once. If <code>$interval</code> is non-zero, then the timer
637is automatically rescheduled at the given intervals.
561</dd> 638</dd>
562<p></p> 639<p></p>
563<dt><strong><a name="item_start">$timer = $timer-&gt;start</a></strong><br /> 640<dt><strong><a name="item_start">$timer = $timer-&gt;start</a></strong><br />
564</dt> 641</dt>
565<dd> 642<dd>

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines