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.1 by root, Mon Jan 2 15:59:25 2006 UTC vs.
Revision 1.5 by root, Mon Jan 2 21:41:51 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="#general_api_considerations">General API Considerations</a></li>
20 <li><a href="#hooks">Hooks</a></li> 21 <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> 22 <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> 23 <li><a href="#the_urxvt__term_class">The <code>urxvt::term</code> Class</a></li>
23 <li><a href="#the_urxvt__timer_class">The <code>urxvt::timer</code> Class</a></li> 24 <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> 25 <li><a href="#the_urxvt__iow_class">The <code>urxvt::iow</code> Class</a></li>
25 </ul> 26 </ul>
26 27
28 <li><a href="#environment">ENVIRONMENT</a></li>
29 <ul>
30
31 <li><a href="#urxvt_perl_verbosity">URXVT_PERL_VERBOSITY</a></li>
32 </ul>
33
27 <li><a href="#author">AUTHOR</a></li> 34 <li><a href="#author">AUTHOR</a></li>
28</ul> 35</ul>
29<!-- INDEX END --> 36<!-- INDEX END -->
30 37
31<hr /> 38<hr />
… …
35<p>rxvtperl - rxvt-unicode's embedded perl interpreter</p> 42<p>rxvtperl - rxvt-unicode's embedded perl interpreter</p>
36<p> 43<p>
37</p> 44</p>
38<hr /> 45<hr />
39<h1><a name="synopsis">SYNOPSIS</a></h1> 46<h1><a name="synopsis">SYNOPSIS</a></h1>
40<p>* Put your scripts into <em>/opt/rxvt/lib/urxvt/perl-ext/</em>, they will be loaded automatically.</p> 47<pre>
41<p>* Each script will only be loaded once, even in urxvtd, and will be valid 48 # create a file grab_test in $HOME:</pre>
42globally.</p>
43<p>* Scripts are evaluated in a 'use strict' and 'use utf8' environment, and
44thus must be encoded as UTF-8.</p>
45<pre> 49<pre>
46 sub on_sel_grab { 50 sub on_sel_grab {
47 warn &quot;you selected &quot;, $_[0]-&gt;selection; 51 warn &quot;you selected &quot;, $_[0]-&gt;selection;
48 () 52 ()
49 }</pre> 53 }</pre>
50<pre> 54<pre>
51 1</pre> 55 # start a rxvt using it:</pre>
56<pre>
57 rxvt --perl-lib $HOME -pe grab_test</pre>
52<p> 58<p>
53</p> 59</p>
54<hr /> 60<hr />
55<h1><a name="description">DESCRIPTION</a></h1> 61<h1><a name="description">DESCRIPTION</a></h1>
62<p>Everytime a terminal object gets created, scripts specified via the
63<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
65thus must be encoded as UTF-8.</p>
66<p>Each script will only ever be loaded once, even in rxvtd, where
67scripts will be shared (But not enabled) for all terminals.</p>
68<p>
69</p>
70<h2><a name="general_api_considerations">General API Considerations</a></h2>
71<p>All objects (such as terminals, time watchers etc.) are typical
72reference-to-hash objects. The hash can be used to store anything you
73like. All members starting with an underscore (such as <code>_ptr</code> or
74<code>_hook</code>) are reserved for internal uses and must not be accessed or
75modified).</p>
76<p>When objects are destroyed on the C++ side, the perl object hashes are
77emptied, so its best to store related objects such as time watchers and
78the like inside the terminal object so they get destroyed as soon as the
79terminal is destroyed.</p>
56<p> 80<p>
57</p> 81</p>
58<h2><a name="hooks">Hooks</a></h2> 82<h2><a name="hooks">Hooks</a></h2>
59<p>The following subroutines can be declared in loaded scripts, and will be called 83<p>The following subroutines can be declared in loaded scripts, and will be called
60whenever the relevant event happens.</p> 84whenever the relevant event happens.</p>
… …
161<dt><strong><a name="item_on_refresh_end__24term">on_refresh_end $term</a></strong><br /> 185<dt><strong><a name="item_on_refresh_end__24term">on_refresh_end $term</a></strong><br />
162</dt> 186</dt>
163<dd> 187<dd>
164Called just after the screen gets redrawn. See <code>on_refresh_begin</code>. 188Called just after the screen gets redrawn. See <code>on_refresh_begin</code>.
165</dd> 189</dd>
190<p></p>
191<dt><strong><a name="item_on_keyboard_command__24term_2c__24string">on_keyboard_command $term, $string</a></strong><br />
192</dt>
193<dd>
194Called whenever the user presses a key combination that has a
195<code>perl:string</code> action bound to it (see description of the <strong>keysym</strong>
196resource in the <code>rxvt(1)</code> manpage).
197</dd>
166<p></p></dl> 198<p></p></dl>
167<p> 199<p>
168</p> 200</p>
169<h2><a name="functions_in_the_urxvt_package">Functions in the <code>urxvt</code> Package</a></h2> 201<h2><a name="functions_in_the_urxvt_package">Functions in the <code>urxvt</code> Package</a></h2>
170<dl> 202<dl>
… …
177</dd> 209</dd>
178<p></p> 210<p></p>
179<dt><strong><a name="item_urxvt_3a_3awarn__24string">urxvt::warn $string</a></strong><br /> 211<dt><strong><a name="item_urxvt_3a_3awarn__24string">urxvt::warn $string</a></strong><br />
180</dt> 212</dt>
181<dd> 213<dd>
182Calls <code>rxvt_warn</code> witht eh given string which should not include a 214Calls <code>rxvt_warn</code> with the given string which should not include a
183newline. The module also overwrites the <code>warn</code> builtin with a function 215newline. The module also overwrites the <code>warn</code> builtin with a function
184that calls this function. 216that calls this function.
185</dd> 217</dd>
186<dd> 218<dd>
187<p>Using this function has the advantage that its output ends up in the 219<p>Using this function has the advantage that its output ends up in the
188correct place, e.g. on stderr of the connecting urxvtc client.</p> 220correct place, e.g. on stderr of the connecting urxvtc client.</p>
189</dd> 221</dd>
190<p></p> 222<p></p>
191<dt><strong><a name="item__24cellwidth__3d_urxvt_3a_3awcswidth__24string">$cellwidth = urxvt::wcswidth $string</a></strong><br />
192</dt>
193<dd>
194Returns the number of screen-cells this string would need. Correctly
195accounts for wide and combining characters.
196</dd>
197<p></p>
198<dt><strong><a name="item__24time__3d_urxvt_3a_3anow">$time = urxvt::NOW</a></strong><br /> 223<dt><strong><a name="item__24time__3d_urxvt_3a_3anow">$time = urxvt::NOW</a></strong><br />
199</dt> 224</dt>
200<dd> 225<dd>
201Returns the ``current time'' (as per the event loop). 226Returns the ``current time'' (as per the event loop).
202</dd> 227</dd>
203<p></p></dl> 228<p></p></dl>
204<p> 229<p>
205</p> 230</p>
206<h2><a name="the_urxvt__term_class">The <code>urxvt::term</code> Class</a></h2> 231<h2><a name="the_urxvt__term_class">The <code>urxvt::term</code> Class</a></h2>
207<dl> 232<dl>
233<dt><strong><a name="item_resource">$value = $term-&gt;resource ($name[, $newval])</a></strong><br />
234</dt>
235<dd>
236Returns the current resource value associated with a given name and
237optionally sets a new value. Setting values is most useful in the <code>init</code>
238hook. Unset resources are returned and accepted as <code>undef</code>.
239</dd>
240<dd>
241<p>The new value must be properly encoded to a suitable character encoding
242before passing it to this method. Similarly, the returned value may need
243to be converted from the used encoding to text.</p>
244</dd>
245<dd>
246<p>Resource names are as defined in <em>src/rsinc.h</em>. Colours can be specified
247as resource names of the form <code>color+&lt;index&gt;</code>, e.g. <code>color+5</code>. (will
248likely change).</p>
249</dd>
250<dd>
251<p>Please note that resource strings will currently only be freed when the
252terminal is destroyed, so changing options frequently will eat memory.</p>
253</dd>
254<dd>
255<p>Here is a a likely non-exhaustive list of resource names, not all of which
256are supported in every build, please see the source to see the actual
257list:</p>
258</dd>
259<dd>
260<pre>
261 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
262 borderLess color cursorBlink cursorUnderline cutchars delete_key
263 display_name embed ext_bwidth fade font geometry hold iconName
264 imFont imLocale inputMethod insecure int_bwidth intensityStyles
265 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
266 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext
267 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
268 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
269 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
270 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
271 shade term_name title transparent transparent_all tripleclickwords
272 utmpInhibit visualBell</pre>
273</dd>
274<p></p>
208<dt><strong><a name="item_selection_mark">($row, $col) = $term-&gt;selection_mark ([$row, $col])</a></strong><br /> 275<dt><strong><a name="item_selection_mark">($row, $col) = $term-&gt;selection_mark ([$row, $col])</a></strong><br />
209</dt> 276</dt>
210<dt><strong><a name="item_selection_beg">($row, $col) = $term-&gt;selection_beg ([$row, $col])</a></strong><br /> 277<dt><strong><a name="item_selection_beg">($row, $col) = $term-&gt;selection_beg ([$row, $col])</a></strong><br />
211</dt> 278</dt>
212<dt><strong><a name="item_selection_end">($row, $col) = $term-&gt;selection_end ([$row, $col])</a></strong><br /> 279<dt><strong><a name="item_selection_end">($row, $col) = $term-&gt;selection_end ([$row, $col])</a></strong><br />
… …
259<p></p> 326<p></p>
260<dt><strong><a name="item_scr_overlay_set">$term-&gt;scr_overlay_set ($x, $y, $text)</a></strong><br /> 327<dt><strong><a name="item_scr_overlay_set">$term-&gt;scr_overlay_set ($x, $y, $text)</a></strong><br />
261</dt> 328</dt>
262<dd> 329<dd>
263Write a string at the given position into the overlay. 330Write a string at the given position into the overlay.
331</dd>
332<p></p>
333<dt><strong><a name="item_strwidth">$cellwidth = $term-&gt;strwidth $string</a></strong><br />
334</dt>
335<dd>
336Returns the number of screen-cells this string would need. Correctly
337accounts for wide and combining characters.
338</dd>
339<p></p>
340<dt><strong><a name="item_locale_encode">$octets = $term-&gt;locale_encode $string</a></strong><br />
341</dt>
342<dd>
343Convert the given text string into the corresponding locale encoding.
344</dd>
345<p></p>
346<dt><strong><a name="item_locale_decode">$string = $term-&gt;locale_decode $octets</a></strong><br />
347</dt>
348<dd>
349Convert the given locale-encoded octets into a perl string.
350</dd>
351<p></p>
352<dt><strong><a name="item_tt_write">$term-&gt;tt_write ($octets)</a></strong><br />
353</dt>
354<dd>
355Write 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
357the locale-specific encoding using <a href="#item_locale_encode"><code>$term-&gt;locale_encode</code></a>.
264</dd> 358</dd>
265<p></p></dl> 359<p></p></dl>
266<p> 360<p>
267</p> 361</p>
268<h2><a name="the_urxvt__timer_class">The <code>urxvt::timer</code> Class</a></h2> 362<h2><a name="the_urxvt__timer_class">The <code>urxvt::timer</code> Class</a></h2>
… …
380</dd> 474</dd>
381<p></p></dl> 475<p></p></dl>
382<p> 476<p>
383</p> 477</p>
384<hr /> 478<hr />
479<h1><a name="environment">ENVIRONMENT</a></h1>
480<p>
481</p>
482<h2><a name="urxvt_perl_verbosity">URXVT_PERL_VERBOSITY</a></h2>
483<p>This variable controls the verbosity level of the perl extension. Higher
484numbers indicate more verbose output.</p>
485<ol>
486<li><strong><a name="item__2d_only_fatal_messages">- only fatal messages</a></strong><br />
487</li>
488<li><strong><a name="item__2d_script_loading_and_management">- script loading and management</a></strong><br />
489</li>
490<li><strong><a name="item__2d_all_events_received">- all events received</a></strong><br />
491</li>
492</ol>
493<p>
494</p>
495<hr />
385<h1><a name="author">AUTHOR</a></h1> 496<h1><a name="author">AUTHOR</a></h1>
386<pre> 497<pre>
387 Marc Lehmann &lt;pcg@goof.com&gt; 498 Marc Lehmann &lt;pcg@goof.com&gt;
388 <a href="http://software.schmorp.de/pkg/rxvt-unicode">http://software.schmorp.de/pkg/rxvt-unicode</a></pre> 499 <a href="http://software.schmorp.de/pkg/rxvt-unicode">http://software.schmorp.de/pkg/rxvt-unicode</a></pre>
389 500

Diff Legend

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