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.2 by root, Mon Jan 2 17:21:59 2006 UTC vs.
Revision 1.6 by root, Tue Jan 3 01:39:56 2006 UTC

… …
13<ul> 13<ul>
14 14
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 <li><a href="#packaged_extensions">PACKAGED EXTENSIONS</a></li>
18 <ul> 19 <ul>
19 20
21 <li><a href="#general_api_considerations">General API Considerations</a></li>
20 <li><a href="#hooks">Hooks</a></li> 22 <li><a href="#hooks">Hooks</a></li>
21 <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>
22 <li><a href="#the_urxvt__term_class">The <code>urxvt::term</code> Class</a></li> 24 <li><a href="#the_urxvt__term_class">The <code>urxvt::term</code> Class</a></li>
25 <li><a href="#rendition">RENDITION</a></li>
23 <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>
24 <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>
25 </ul> 28 </ul>
26 29
27 <li><a href="#environment">ENVIRONMENT</a></li> 30 <li><a href="#environment">ENVIRONMENT</a></li>
… …
41<p>rxvtperl - rxvt-unicode's embedded perl interpreter</p> 44<p>rxvtperl - rxvt-unicode's embedded perl interpreter</p>
42<p> 45<p>
43</p> 46</p>
44<hr /> 47<hr />
45<h1><a name="synopsis">SYNOPSIS</a></h1> 48<h1><a name="synopsis">SYNOPSIS</a></h1>
46<p>* Put your scripts into <em>/opt/rxvt/lib/urxvt/perl-ext/</em>, they will be loaded automatically.</p> 49<pre>
47<p>* Each script will only be loaded once, even in urxvtd, and will be valid 50 # create a file grab_test in $HOME:</pre>
48globally.</p>
49<p>* Scripts are evaluated in a 'use strict' and 'use utf8' environment, and
50thus must be encoded as UTF-8.</p>
51<pre> 51<pre>
52 sub on_sel_grab { 52 sub on_sel_grab {
53 warn &quot;you selected &quot;, $_[0]-&gt;selection; 53 warn &quot;you selected &quot;, $_[0]-&gt;selection;
54 () 54 ()
55 }</pre> 55 }</pre>
56<pre> 56<pre>
57 1</pre> 57 # start a rxvt using it:</pre>
58<pre>
59 rxvt --perl-lib $HOME -pe grab_test</pre>
58<p> 60<p>
59</p> 61</p>
60<hr /> 62<hr />
61<h1><a name="description">DESCRIPTION</a></h1> 63<h1><a name="description">DESCRIPTION</a></h1>
64<p>Everytime a terminal object gets created, scripts specified via the
65<code>perl</code> resource are loaded and associated with it.</p>
66<p>Scripts are compiled in a 'use strict' and 'use utf8' environment, and
67thus must be encoded as UTF-8.</p>
68<p>Each script will only ever be loaded once, even in rxvtd, where
69scripts will be shared (But not enabled) for all terminals.</p>
70<p>
71</p>
72<hr />
73<h1><a name="packaged_extensions">PACKAGED EXTENSIONS</a></h1>
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 very simple digital clock in the upper right corner of the
100window. Illustrates overwriting the refresh callbacks to create your own
101overlays 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>
109<p></p></dl>
110<p>
111</p>
112<h2><a name="general_api_considerations">General API Considerations</a></h2>
113<p>All objects (such as terminals, time watchers etc.) are typical
114reference-to-hash objects. The hash can be used to store anything you
115like. All members starting with an underscore (such as <code>_ptr</code> or
116<code>_hook</code>) are reserved for internal uses and must not be accessed or
117modified).</p>
118<p>When objects are destroyed on the C++ side, the perl object hashes are
119emptied, so its best to store related objects such as time watchers and
120the like inside the terminal object so they get destroyed as soon as the
121terminal is destroyed.</p>
62<p> 122<p>
63</p> 123</p>
64<h2><a name="hooks">Hooks</a></h2> 124<h2><a name="hooks">Hooks</a></h2>
65<p>The following subroutines can be declared in loaded scripts, and will be called 125<p>The following subroutines can be declared in loaded scripts, and will be called
66whenever the relevant event happens.</p> 126whenever the relevant event happens.</p>
… …
167<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 />
168</dt> 228</dt>
169<dd> 229<dd>
170Called 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>.
171</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>
172<p></p></dl> 240<p></p></dl>
173<p> 241<p>
174</p> 242</p>
175<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>
176<dl> 244<dl>
… …
183</dd> 251</dd>
184<p></p> 252<p></p>
185<dt><strong><a name="item_urxvt_3a_3awarn__24string">urxvt::warn $string</a></strong><br /> 253<dt><strong><a name="item_urxvt_3a_3awarn__24string">urxvt::warn $string</a></strong><br />
186</dt> 254</dt>
187<dd> 255<dd>
188Calls <code>rxvt_warn</code> witht eh given string which should not include a 256Calls <code>rxvt_warn</code> with the given string which should not include a
189newline. The module also overwrites the <code>warn</code> builtin with a function 257newline. The module also overwrites the <code>warn</code> builtin with a function
190that calls this function. 258that calls this function.
191</dd> 259</dd>
192<dd> 260<dd>
193<p>Using this function has the advantage that its output ends up in the 261<p>Using this function has the advantage that its output ends up in the
194correct place, e.g. on stderr of the connecting urxvtc client.</p> 262correct place, e.g. on stderr of the connecting urxvtc client.</p>
195</dd>
196<p></p>
197<dt><strong><a name="item__24cellwidth__3d_urxvt_3a_3awcswidth__24string">$cellwidth = urxvt::wcswidth $string</a></strong><br />
198</dt>
199<dd>
200Returns the number of screen-cells this string would need. Correctly
201accounts for wide and combining characters.
202</dd> 263</dd>
203<p></p> 264<p></p>
204<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 />
205</dt> 266</dt>
206<dd> 267<dd>
… …
241<pre> 302<pre>
242 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 303 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
243 borderLess color cursorBlink cursorUnderline cutchars delete_key 304 borderLess color cursorBlink cursorUnderline cutchars delete_key
244 display_name embed ext_bwidth fade font geometry hold iconName 305 display_name embed ext_bwidth fade font geometry hold iconName
245 imFont imLocale inputMethod insecure int_bwidth intensityStyles 306 imFont imLocale inputMethod insecure int_bwidth intensityStyles
246 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 307 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
247 modifier mouseWheelScrollPage name pastableTabs path pointerBlank 308 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext
248 pointerBlankDelay preeditType print_pipe pty_fd reverseVideo saveLines 309 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
249 scrollBar scrollBar_align scrollBar_floating scrollBar_right 310 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
250 scrollBar_thickness scrollTtyKeypress scrollTtyOutput scrollWithBuffer 311 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
251 scrollstyle secondaryScreen secondaryScroll selectstyle shade term_name 312 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
252 title transparent transparent_all tripleclickwords utmpInhibit 313 shade term_name title transparent transparent_all tripleclickwords
253 visualBell</pre> 314 utmpInhibit visualBell</pre>
254</dd> 315</dd>
255<p></p> 316<p></p>
256<dt><strong><a name="item_selection_mark">($row, $col) = $term-&gt;selection_mark ([$row, $col])</a></strong><br /> 317<dt><strong><a name="item_selection_mark">($row, $col) = $term-&gt;selection_mark ([$row, $col])</a></strong><br />
257</dt> 318</dt>
258<dt><strong><a name="item_selection_beg">($row, $col) = $term-&gt;selection_beg ([$row, $col])</a></strong><br /> 319<dt><strong><a name="item_selection_beg">($row, $col) = $term-&gt;selection_beg ([$row, $col])</a></strong><br />
… …
269<dd> 330<dd>
270Try to request the primary selection from the server (for example, as set 331Try to request the primary selection from the server (for example, as set
271by the next method). 332by the next method).
272</dd> 333</dd>
273<p></p> 334<p></p>
274<dt><strong><a name="item_selection">$oldtext = $term-&gt;selection ([$newtext])</a></strong><br /> 335<dt><strong>$oldtext = $term-&gt;selection ([$newtext])</strong><br />
275</dt> 336</dt>
276<dd> 337<dd>
277Return the current selection text and optionally replace it by <code>$newtext</code>. 338Return the current selection text and optionally replace it by <code>$newtext</code>.
278</dd> 339</dd>
279<p></p> 340<p></p>
… …
307<p></p> 368<p></p>
308<dt><strong><a name="item_scr_overlay_set">$term-&gt;scr_overlay_set ($x, $y, $text)</a></strong><br /> 369<dt><strong><a name="item_scr_overlay_set">$term-&gt;scr_overlay_set ($x, $y, $text)</a></strong><br />
309</dt> 370</dt>
310<dd> 371<dd>
311Write a string at the given position into the overlay. 372Write a string at the given position into the overlay.
373</dd>
374<p></p>
375<dt><strong><a name="item_strwidth">$cellwidth = $term-&gt;strwidth $string</a></strong><br />
376</dt>
377<dd>
378Returns the number of screen-cells this string would need. Correctly
379accounts for wide and combining characters.
380</dd>
381<p></p>
382<dt><strong><a name="item_locale_encode">$octets = $term-&gt;locale_encode $string</a></strong><br />
383</dt>
384<dd>
385Convert the given text string into the corresponding locale encoding.
386</dd>
387<p></p>
388<dt><strong><a name="item_locale_decode">$string = $term-&gt;locale_decode $octets</a></strong><br />
389</dt>
390<dd>
391Convert the given locale-encoded octets into a perl string.
392</dd>
393<p></p>
394<dt><strong><a name="item_tt_write">$term-&gt;tt_write ($octets)</a></strong><br />
395</dt>
396<dd>
397Write the octets given in <code>$data</code> to the tty (i.e. as program input). To
398pass characters instead of octets, you should convert your strings first
399to the locale-specific encoding using <a href="#item_locale_encode"><code>$term-&gt;locale_encode</code></a>.
400</dd>
401<p></p>
402<dt><strong><a name="item_nrow">$nrow = $term-&gt;nrow</a></strong><br />
403</dt>
404<dt><strong><a name="item_ncol">$ncol = $term-&gt;ncol</a></strong><br />
405</dt>
406<dd>
407Return the number of rows/columns of the terminal window (i.e. as
408specified by <code>-geometry</code>, excluding any scrollback).
409</dd>
410<p></p>
411<dt><strong><a name="item_nsaved">$nsaved = $term-&gt;nsaved</a></strong><br />
412</dt>
413<dd>
414Returns the number of lines in the scrollback buffer.
415</dd>
416<p></p>
417<dt><strong><a name="item_view_start">$view_start = $term-&gt;view_start ([$newvalue])</a></strong><br />
418</dt>
419<dd>
420Returns the negative row number of the topmost line. Minimum value is
421<code>0</code>, which displays the normal terminal contents. Larger values scroll
422this many lines into the scrollback buffer.
423</dd>
424<p></p>
425<dt><strong><a name="item_want_refresh">$term-&gt;want_refresh</a></strong><br />
426</dt>
427<dd>
428Requests a screen refresh. At the next opportunity, rxvt-unicode will
429compare the on-screen display with its stored representation. If they
430differ, it redraws the differences.
431</dd>
432<dd>
433<p>Used after changing terminal contents to display them.</p>
434</dd>
435<p></p>
436<dt><strong><a name="item_row_t">$text = $term-&gt;ROW_t ($row_number[, $new_text[, $start_col]])</a></strong><br />
437</dt>
438<dd>
439Returns the text of the entire row with number <code>$row_number</code>. Row <code>0</code>
440is the topmost terminal line, row <code>$term-&gt;$ncol-1</code> is the bottommost
441terminal line. The scrollback buffer starts at line <code>-1</code> and extends to
442line <a href="#item_nsaved"><code>-$term-&gt;nsaved</code></a>.
443</dd>
444<dd>
445<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
447to replace only parts of a line. The font iindex in the rendition will
448automatically be updated.</p>
449</dd>
450<dd>
451<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
453(<code>chr 65535</code>). Characters with combining characters and other characters
454that do not fit into the normal tetx encoding will be replaced with
455characters in the private use area.</p>
456</dd>
457<dd>
458<p>You have to obey this encoding when changing text. The advantage is
459that <code>substr</code> and similar functions work on screen cells and not on
460characters.</p>
461</dd>
462<dd>
463<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>
464can be used to convert normal strings into this encoding and vice versa.</p>
465</dd>
466<p></p>
467<dt><strong><a name="item_row_r">$rend = $term-&gt;ROW_r ($row_number[, $new_rend[, $start_col]])</a></strong><br />
468</dt>
469<dd>
470Like <a href="#item_row_t"><code>$term-&gt;ROW_t</code></a>, but returns an arrayref with rendition
471bitsets. Rendition bitsets contain information about colour, font, font
472styles and similar information. See also <a href="#item_row_t"><code>$term-&gt;ROW_t</code></a>.
473</dd>
474<dd>
475<p>When setting rendition, the font mask will be ignored.</p>
476</dd>
477<dd>
478<p>See the section on RENDITION, below.</p>
479</dd>
480<p></p>
481<dt><strong><a name="item_row_l">$length = $term-&gt;ROW_l ($row_number[, $new_length])</a></strong><br />
482</dt>
483<dd>
484Returns the number of screen cells that are in use (``the line length''). If
485it is <code>-1</code>, then the line is part of a multiple-row logical ``line'', which
486means all characters are in use and it is continued on the next row.
487</dd>
488<p></p>
489<dt><strong><a name="item_special_encode">$text = $term-&gt;special_encode $string</a></strong><br />
490</dt>
491<dd>
492Converts a perl string into the special encoding used by rxvt-unicode,
493where one character corresponds to one screen cell. See
494<a href="#item_row_t"><code>$term-&gt;ROW_t</code></a> for details.
495</dd>
496<p></p>
497<dt><strong><a name="item_special_decode">$string = $term-&gt;special_decode $text</a></strong><br />
498</dt>
499<dd>
500Converts rxvt-unicodes text reprsentation into a perl string. See
501<a href="#item_row_t"><code>$term-&gt;ROW_t</code></a> for details.
502</dd>
503<p></p></dl>
504<p>
505</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
312</dd> 519</dd>
313<p></p></dl> 520<p></p></dl>
314<p> 521<p>
315</p> 522</p>
316<h2><a name="the_urxvt__timer_class">The <code>urxvt::timer</code> Class</a></h2> 523<h2><a name="the_urxvt__timer_class">The <code>urxvt::timer</code> Class</a></h2>

Diff Legend

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