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.4 by root, Mon Jan 2 20:35:39 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 />
46<h1><a name="synopsis">SYNOPSIS</a></h1> 49<h1><a name="synopsis">SYNOPSIS</a></h1>
47<p>* Put your scripts into <em>/opt/rxvt/lib/urxvt/perl-ext/</em>, they will be loaded automatically.</p> 50<pre>
48<p>* Scripts are evaluated in a 'use strict' and 'use utf8' environment, and 51 # create a file grab_test in $HOME:</pre>
49thus must be encoded as UTF-8.</p>
50<pre> 52<pre>
51 sub on_sel_grab { 53 sub on_sel_grab {
52 warn &quot;you selected &quot;, $_[0]-&gt;selection; 54 warn &quot;you selected &quot;, $_[0]-&gt;selection;
53 () 55 ()
54 }</pre> 56 }</pre>
55<pre> 57<pre>
56 1</pre> 58 # start a rxvt using it:</pre>
59<pre>
60 rxvt --perl-lib $HOME -pe grab_test</pre>
57<p> 61<p>
58</p> 62</p>
59<hr /> 63<hr />
60<h1><a name="description">DESCRIPTION</a></h1> 64<h1><a name="description">DESCRIPTION</a></h1>
61<p>Everytime a terminal object gets created, scripts specified via the 65<p>Everytime a terminal object gets created, scripts specified via the
62<code>perl</code> resource are associated with it.</p> 66<code>perl</code> resource are loaded and associated with it.</p>
67<p>Scripts are compiled in a 'use strict' and 'use utf8' environment, and
68thus must be encoded as UTF-8.</p>
63<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
64scripts 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>
65<p> 110<p>
66</p> 111</p>
67<h2><a name="general_api_considerations">General API Considerations</a></h2> 112<h2><a name="general_api_considerations">General API Considerations</a></h2>
68<p>All objects (such as terminals, time watchers etc.) are typical 113<p>All objects (such as terminals, time watchers etc.) are typical
69reference-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
… …
182<dt><strong><a name="item_on_refresh_end__24term">on_refresh_end $term</a></strong><br /> 227<dt><strong><a name="item_on_refresh_end__24term">on_refresh_end $term</a></strong><br />
183</dt> 228</dt>
184<dd> 229<dd>
185Called just after the screen gets redrawn. See <code>on_refresh_begin</code>. 230Called just after the screen gets redrawn. See <code>on_refresh_begin</code>.
186</dd> 231</dd>
232<p></p>
233<dt><strong><a name="item_on_keyboard_command__24term_2c__24string">on_keyboard_command $term, $string</a></strong><br />
234</dt>
235<dd>
236Called whenever the user presses a key combination that has a
237<code>perl:string</code> action bound to it (see description of the <strong>keysym</strong>
238resource in the <code>rxvt(1)</code> manpage).
239</dd>
187<p></p></dl> 240<p></p></dl>
188<p> 241<p>
189</p> 242</p>
190<h2><a name="functions_in_the_urxvt_package">Functions in the <code>urxvt</code> Package</a></h2> 243<h2><a name="functions_in_the_urxvt_package">Functions in the <code>urxvt</code> Package</a></h2>
191<dl> 244<dl>
… …
211<p></p> 264<p></p>
212<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 />
213</dt> 266</dt>
214<dd> 267<dd>
215Returns 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.
216</dd> 331</dd>
217<p></p></dl> 332<p></p></dl>
218<p> 333<p>
219</p> 334</p>
220<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>
… …
277<dd> 392<dd>
278Try 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
279by the next method). 394by the next method).
280</dd> 395</dd>
281<p></p> 396<p></p>
282<dt><strong><a name="item_selection">$oldtext = $term-&gt;selection ([$newtext])</a></strong><br /> 397<dt><strong>$oldtext = $term-&gt;selection ([$newtext])</strong><br />
283</dt> 398</dt>
284<dd> 399<dd>
285Return 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>.
286</dd> 401</dd>
287<p></p>
288<dt><strong><a name="item_scr_overlay">$term-&gt;scr_overlay ($x, $y, $text)</a></strong><br />
289</dt>
290<dd> 402<dd>
403<p>#=item $term-&gt;overlay ($x, $y, $text)
404#
291Create 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>
292</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>
293<p></p> 431<p></p>
294<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 />
295</dt> 433</dt>
296<dd> 434<dd>
297Create a new (empty) overlay at the given position with the given 435Create a new (empty) overlay at the given position with the given
298width/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
299<code>$y</code> is negative, then this is counted from the right/bottom side, 437(default: <code>OVERLAY_RSTYLE</code>).
300respectively.
301</dd>
302<p></p>
303<dt><strong><a name="item_scr_overlay_off">$term-&gt;scr_overlay_off</a></strong><br />
304</dt>
305<dd> 438</dd>
306Switch the overlay off again.
307</dd> 439<dd>
308<p></p> 440<p>If <code>$border</code> is <code>2</code> (default), then a decorative border will be put
309<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>
310</dt>
311<dd> 442</dd>
312Put a single character (specified numerically) at the given overlay
313position.
314</dd> 443<dd>
315<p></p> 444<p>If either <code>$x</code> or <code>$y</code> is negative, then this is counted from the
316<dt><strong><a name="item_scr_overlay_set">$term-&gt;scr_overlay_set ($x, $y, $text)</a></strong><br /> 445right/bottom side, respectively.</p>
317</dt>
318<dd> 446</dd>
319Write 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.
320</dd> 461</dd>
321<p></p> 462<p></p>
322<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 />
323</dt> 464</dt>
324<dd> 465<dd>
… …
340<p></p> 481<p></p>
341<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 />
342</dt> 483</dt>
343<dd> 484<dd>
344Write 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
345pass characters instead of octets, you should convetr you strings first to 486pass characters instead of octets, you should convert your strings first
346the 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.
347</dd> 590</dd>
348<p></p></dl> 591<p></p></dl>
349<p> 592<p>
350</p> 593</p>
351<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>
352<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
353fractional number of seconds since the epoch. Example:</p> 596fractional number of seconds since the epoch. Example:</p>
354<pre> 597<pre>
355 # create a digital clock display in upper right corner 598 $term-&gt;{overlay} = $term-&gt;overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
356 $term-&gt;{timer} = urxvt::timer 599 $term-&gt;{timer} = urxvt::timer
357 -&gt;new 600 -&gt;new
358 -&gt;start (urxvt::NOW) 601 -&gt;interval (1)
359 -&gt;cb (sub { 602 -&gt;cb (sub {
360 my ($timer) = @_;
361 my $time = $timer-&gt;at;
362 $timer-&gt;start ($time + 1);
363 $self-&gt;scr_overlay (-1, 0, 603 $term-&gt;{overlay}-&gt;set (0, 0,
364 POSIX::strftime &quot;%H:%M:%S&quot;, localtime $time); 604 sprintf &quot;%2d:%02d:%02d&quot;, (localtime urxvt::NOW)[2,1,0]);
365 });</pre> 605 });</pre>
366<dl> 606<dl>
367<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 />
368</dt> 608</dt>
369<dd> 609<dd>
370Create a new timer object in stopped state. 610Create a new timer object in started state. It is scheduled to fire
611immediately.
371</dd> 612</dd>
372<p></p> 613<p></p>
373<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 />
374</dt> 615</dt>
375<dd> 616<dd>
… …
380</dt> 621</dt>
381<dd> 622<dd>
382Return the time this watcher will fire next. 623Return the time this watcher will fire next.
383</dd> 624</dd>
384<p></p> 625<p></p>
385<dt><strong><a name="item_set">$timer = $timer-&gt;set ($tstamp)</a></strong><br /> 626<dt><strong>$timer = $timer-&gt;set ($tstamp)</strong><br />
386</dt> 627</dt>
387<dd> 628<dd>
388Set 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.
389</dd> 638</dd>
390<p></p> 639<p></p>
391<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 />
392</dt> 641</dt>
393<dd> 642<dd>

Diff Legend

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