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.5 by root, Mon Jan 2 21:41:51 2006 UTC vs.
Revision 1.8 by root, Tue Jan 3 04:20:37 2006 UTC

… …
15 <li><a href="#name">NAME</a></li> 15 <li><a href="#name">NAME</a></li>
16 <li><a href="#synopsis">SYNOPSIS</a></li> 16 <li><a href="#synopsis">SYNOPSIS</a></li>
17 <li><a href="#description">DESCRIPTION</a></li> 17 <li><a href="#description">DESCRIPTION</a></li>
18 <ul> 18 <ul>
19 19
20 <li><a href="#prepackaged_extensions">Prepackaged Extensions</a></li>
20 <li><a href="#general_api_considerations">General API Considerations</a></li> 21 <li><a href="#general_api_considerations">General API Considerations</a></li>
21 <li><a href="#hooks">Hooks</a></li> 22 <li><a href="#hooks">Hooks</a></li>
22 <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>
23 <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>
24 <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>
25 <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>
26 </ul> 28 </ul>
27 29
… …
36<!-- INDEX END --> 38<!-- INDEX END -->
37 39
38<hr /> 40<hr />
39<p> 41<p>
40</p> 42</p>
43<hr />
41<h1><a name="name">NAME</a></h1> 44<h1><a name="name">NAME</a></h1>
42<p>rxvtperl - rxvt-unicode's embedded perl interpreter</p> 45<p>rxvtperl - rxvt-unicode's embedded perl interpreter</p>
43<p> 46<p>
44</p> 47</p>
45<hr /> 48<hr />
… …
62<p>Everytime a terminal object gets created, scripts specified via the 65<p>Everytime a terminal object gets created, scripts specified via the
63<code>perl</code> resource are loaded and associated with it.</p> 66<code>perl</code> resource are loaded and associated with it.</p>
64<p>Scripts are compiled in a 'use strict' and 'use utf8' environment, and 67<p>Scripts are compiled in a 'use strict' and 'use utf8' environment, and
65thus must be encoded as UTF-8.</p> 68thus must be encoded as UTF-8.</p>
66<p>Each script will only ever be loaded once, even in rxvtd, where 69<p>Each script will only ever be loaded once, even in rxvtd, where
67scripts will be shared (But not enabled) for all terminals.</p> 70scripts will be shared (but not enabled) for all terminals.</p>
71<p>
72</p>
73<h2><a name="prepackaged_extensions">Prepackaged Extensions</a></h2>
74<p>This section describes the extensiosn delivered with this version. You can
75find them in <em>/opt/rxvt/lib/urxvt/perl/</em>.</p>
76<p>You can activate them like this:</p>
77<pre>
78 rxvt -pe &lt;extensionname&gt;</pre>
79<dl>
80<dt><strong><a name="item_selection">selection</a></strong><br />
81</dt>
82<dd>
83Miscellaneous selection modifications.
84</dd>
85<dl>
86<dt><strong><a name="item_rot13">rot13</a></strong><br />
87</dt>
88<dd>
89Rot-13 the selection when activated. Used via keyboard trigger:
90</dd>
91<dd>
92<pre>
93 URxvt.keysym.C-M-r: perl:selection:rot13</pre>
94</dd>
95<p></p></dl>
96<dt><strong><a name="item_digital_2dclock">digital-clock</a></strong><br />
97</dt>
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>
105Displays a very simple digital clock in the upper right corner of the
106window. Illustrates overwriting the refresh callbacks to create your own
107overlays or changes.
108</dd>
109<p></p></dl>
68<p> 110<p>
69</p> 111</p>
70<h2><a name="general_api_considerations">General API Considerations</a></h2> 112<h2><a name="general_api_considerations">General API Considerations</a></h2>
71<p>All objects (such as terminals, time watchers etc.) are typical 113<p>All objects (such as terminals, time watchers etc.) are typical
72reference-to-hash objects. The hash can be used to store anything you 114reference-to-hash objects. The hash can be used to store anything you
… …
222<p></p> 264<p></p>
223<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 />
224</dt> 266</dt>
225<dd> 267<dd>
226Returns 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.
227</dd> 331</dd>
228<p></p></dl> 332<p></p></dl>
229<p> 333<p>
230</p> 334</p>
231<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>
… …
288<dd> 392<dd>
289Try to request the primary selection from the server (for example, as set 393Try to request the primary selection from the server (for example, as set
290by the next method). 394by the next method).
291</dd> 395</dd>
292<p></p> 396<p></p>
293<dt><strong><a name="item_selection">$oldtext = $term-&gt;selection ([$newtext])</a></strong><br /> 397<dt><strong>$oldtext = $term-&gt;selection ([$newtext])</strong><br />
294</dt> 398</dt>
295<dd> 399<dd>
296Return 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>.
297</dd> 401</dd>
298<p></p>
299<dt><strong><a name="item_scr_overlay">$term-&gt;scr_overlay ($x, $y, $text)</a></strong><br />
300</dt>
301<dd> 402<dd>
403<p>#=item $term-&gt;overlay ($x, $y, $text)
404#
302Create 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>
303</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>
304<p></p> 431<p></p>
305<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 />
306</dt> 433</dt>
307<dd> 434<dd>
308Create a new (empty) overlay at the given position with the given 435Create a new (empty) overlay at the given position with the given
309width/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
310<code>$y</code> is negative, then this is counted from the right/bottom side, 437(default: <code>OVERLAY_RSTYLE</code>).
311respectively.
312</dd>
313<p></p>
314<dt><strong><a name="item_scr_overlay_off">$term-&gt;scr_overlay_off</a></strong><br />
315</dt>
316<dd> 438</dd>
317Switch the overlay off again.
318</dd> 439<dd>
319<p></p> 440<p>If <code>$border</code> is <code>2</code> (default), then a decorative border will be put
320<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>
321</dt>
322<dd> 442</dd>
323Put a single character (specified numerically) at the given overlay
324position.
325</dd> 443<dd>
326<p></p> 444<p>If either <code>$x</code> or <code>$y</code> is negative, then this is counted from the
327<dt><strong><a name="item_scr_overlay_set">$term-&gt;scr_overlay_set ($x, $y, $text)</a></strong><br /> 445right/bottom side, respectively.</p>
328</dt>
329<dd> 446</dd>
330Write 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.
331</dd> 461</dd>
332<p></p> 462<p></p>
333<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 />
334</dt> 464</dt>
335<dd> 465<dd>
… …
351<p></p> 481<p></p>
352<dt><strong><a name="item_tt_write">$term-&gt;tt_write ($octets)</a></strong><br /> 482<dt><strong><a name="item_tt_write">$term-&gt;tt_write ($octets)</a></strong><br />
353</dt> 483</dt>
354<dd> 484<dd>
355Write the octets given in <code>$data</code> to the tty (i.e. as program input). To 485Write the octets given in <code>$data</code> to the tty (i.e. as program input). To
356pass characters instead of octets, you should convetr you strings first to 486pass characters instead of octets, you should convert your strings first
357the locale-specific encoding using <a href="#item_locale_encode"><code>$term-&gt;locale_encode</code></a>. 487to the locale-specific encoding using <a href="#item_locale_encode"><code>$term-&gt;locale_encode</code></a>.
488</dd>
489<p></p>
490<dt><strong><a name="item_nrow">$nrow = $term-&gt;nrow</a></strong><br />
491</dt>
492<dt><strong><a name="item_ncol">$ncol = $term-&gt;ncol</a></strong><br />
493</dt>
494<dd>
495Return the number of rows/columns of the terminal window (i.e. as
496specified by <code>-geometry</code>, excluding any scrollback).
497</dd>
498<p></p>
499<dt><strong><a name="item_nsaved">$nsaved = $term-&gt;nsaved</a></strong><br />
500</dt>
501<dd>
502Returns the number of lines in the scrollback buffer.
503</dd>
504<p></p>
505<dt><strong><a name="item_view_start">$view_start = $term-&gt;view_start ([$newvalue])</a></strong><br />
506</dt>
507<dd>
508Returns the negative row number of the topmost line. Minimum value is
509<code>0</code>, which displays the normal terminal contents. Larger values scroll
510this many lines into the scrollback buffer.
511</dd>
512<p></p>
513<dt><strong><a name="item_want_refresh">$term-&gt;want_refresh</a></strong><br />
514</dt>
515<dd>
516Requests a screen refresh. At the next opportunity, rxvt-unicode will
517compare the on-screen display with its stored representation. If they
518differ, it redraws the differences.
519</dd>
520<dd>
521<p>Used after changing terminal contents to display them.</p>
522</dd>
523<p></p>
524<dt><strong><a name="item_row_t">$text = $term-&gt;ROW_t ($row_number[, $new_text[, $start_col]])</a></strong><br />
525</dt>
526<dd>
527Returns the text of the entire row with number <code>$row_number</code>. Row <code>0</code>
528is the topmost terminal line, row <code>$term-&gt;$ncol-1</code> is the bottommost
529terminal line. The scrollback buffer starts at line <code>-1</code> and extends to
530line <a href="#item_nsaved"><code>-$term-&gt;nsaved</code></a>.
531</dd>
532<dd>
533<p>If <code>$new_text</code> is specified, it will replace characters in the current
534line, starting at column <code>$start_col</code> (default <code>0</code>), which is useful
535to replace only parts of a line. The font index in the rendition will
536automatically be updated.</p>
537</dd>
538<dd>
539<p><code>$text</code> is in a special encoding: tabs and wide characters that use more
540than one cell when displayed are padded with urxvt::NOCHAR characters
541(<code>chr 65535</code>). Characters with combining characters and other characters
542that do not fit into the normal tetx encoding will be replaced with
543characters in the private use area.</p>
544</dd>
545<dd>
546<p>You have to obey this encoding when changing text. The advantage is
547that <code>substr</code> and similar functions work on screen cells and not on
548characters.</p>
549</dd>
550<dd>
551<p>The methods <a href="#item_special_encode"><code>$term-&gt;special_encode</code></a> and <a href="#item_special_decode"><code>$term-&gt;special_decode</code></a>
552can be used to convert normal strings into this encoding and vice versa.</p>
553</dd>
554<p></p>
555<dt><strong><a name="item_row_r">$rend = $term-&gt;ROW_r ($row_number[, $new_rend[, $start_col]])</a></strong><br />
556</dt>
557<dd>
558Like <a href="#item_row_t"><code>$term-&gt;ROW_t</code></a>, but returns an arrayref with rendition
559bitsets. Rendition bitsets contain information about colour, font, font
560styles and similar information. See also <a href="#item_row_t"><code>$term-&gt;ROW_t</code></a>.
561</dd>
562<dd>
563<p>When setting rendition, the font mask will be ignored.</p>
564</dd>
565<dd>
566<p>See the section on RENDITION, above.</p>
567</dd>
568<p></p>
569<dt><strong><a name="item_row_l">$length = $term-&gt;ROW_l ($row_number[, $new_length])</a></strong><br />
570</dt>
571<dd>
572Returns the number of screen cells that are in use (``the line length''). If
573it is <code>-1</code>, then the line is part of a multiple-row logical ``line'', which
574means all characters are in use and it is continued on the next row.
575</dd>
576<p></p>
577<dt><strong><a name="item_special_encode">$text = $term-&gt;special_encode $string</a></strong><br />
578</dt>
579<dd>
580Converts a perl string into the special encoding used by rxvt-unicode,
581where one character corresponds to one screen cell. See
582<a href="#item_row_t"><code>$term-&gt;ROW_t</code></a> for details.
583</dd>
584<p></p>
585<dt><strong><a name="item_special_decode">$string = $term-&gt;special_decode $text</a></strong><br />
586</dt>
587<dd>
588Converts rxvt-unicodes text reprsentation into a perl string. See
589<a href="#item_row_t"><code>$term-&gt;ROW_t</code></a> for details.
358</dd> 590</dd>
359<p></p></dl> 591<p></p></dl>
360<p> 592<p>
361</p> 593</p>
362<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>
363<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
364fractional number of seconds since the epoch. Example:</p> 596fractional number of seconds since the epoch. Example:</p>
365<pre> 597<pre>
366 # create a digital clock display in upper right corner 598 $term-&gt;{overlay} = $term-&gt;overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
367 $term-&gt;{timer} = urxvt::timer 599 $term-&gt;{timer} = urxvt::timer
368 -&gt;new 600 -&gt;new
369 -&gt;start (urxvt::NOW) 601 -&gt;interval (1)
370 -&gt;cb (sub { 602 -&gt;cb (sub {
371 my ($timer) = @_;
372 my $time = $timer-&gt;at;
373 $timer-&gt;start ($time + 1);
374 $self-&gt;scr_overlay (-1, 0, 603 $term-&gt;{overlay}-&gt;set (0, 0,
375 POSIX::strftime &quot;%H:%M:%S&quot;, localtime $time); 604 sprintf &quot;%2d:%02d:%02d&quot;, (localtime urxvt::NOW)[2,1,0]);
376 });</pre> 605 });</pre>
377<dl> 606<dl>
378<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 />
379</dt> 608</dt>
380<dd> 609<dd>
381Create a new timer object in stopped state. 610Create a new timer object in started state. It is scheduled to fire
611immediately.
382</dd> 612</dd>
383<p></p> 613<p></p>
384<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 />
385</dt> 615</dt>
386<dd> 616<dd>
… …
391</dt> 621</dt>
392<dd> 622<dd>
393Return the time this watcher will fire next. 623Return the time this watcher will fire next.
394</dd> 624</dd>
395<p></p> 625<p></p>
396<dt><strong><a name="item_set">$timer = $timer-&gt;set ($tstamp)</a></strong><br /> 626<dt><strong>$timer = $timer-&gt;set ($tstamp)</strong><br />
397</dt> 627</dt>
398<dd> 628<dd>
399Set 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.
400</dd> 638</dd>
401<p></p> 639<p></p>
402<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 />
403</dt> 641</dt>
404<dd> 642<dd>

Diff Legend

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