… | |
… | |
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> |
42 | globally.</p> |
|
|
43 | <p>* Scripts are evaluated in a 'use strict' and 'use utf8' environment, and |
|
|
44 | thus must be encoded as UTF-8.</p> |
|
|
45 | <pre> |
49 | <pre> |
46 | sub on_sel_grab { |
50 | sub on_sel_grab { |
47 | warn "you selected ", $_[0]->selection; |
51 | warn "you selected ", $_[0]->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 |
|
|
65 | thus must be encoded as UTF-8.</p> |
|
|
66 | <p>Each script will only ever be loaded once, even in rxvtd, where |
|
|
67 | scripts 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 |
|
|
72 | reference-to-hash objects. The hash can be used to store anything you |
|
|
73 | like. 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 |
|
|
75 | modified).</p> |
|
|
76 | <p>When objects are destroyed on the C++ side, the perl object hashes are |
|
|
77 | emptied, so its best to store related objects such as time watchers and |
|
|
78 | the like inside the terminal object so they get destroyed as soon as the |
|
|
79 | terminal 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 |
60 | whenever the relevant event happens.</p> |
84 | whenever 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> |
164 | Called just after the screen gets redrawn. See <code>on_refresh_begin</code>. |
188 | Called 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> |
|
|
194 | Called 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> |
|
|
196 | resource 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> |
182 | Calls <code>rxvt_warn</code> witht eh given string which should not include a |
214 | Calls <code>rxvt_warn</code> with the given string which should not include a |
183 | newline. The module also overwrites the <code>warn</code> builtin with a function |
215 | newline. The module also overwrites the <code>warn</code> builtin with a function |
184 | that calls this function. |
216 | that 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 |
188 | correct place, e.g. on stderr of the connecting urxvtc client.</p> |
220 | correct 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> |
|
|
194 | Returns the number of screen-cells this string would need. Correctly |
|
|
195 | accounts 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> |
201 | Returns the ``current time'' (as per the event loop). |
226 | Returns 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->resource ($name[, $newval])</a></strong><br /> |
|
|
234 | </dt> |
|
|
235 | <dd> |
|
|
236 | Returns the current resource value associated with a given name and |
|
|
237 | optionally sets a new value. Setting values is most useful in the <code>init</code> |
|
|
238 | hook. 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 |
|
|
242 | before passing it to this method. Similarly, the returned value may need |
|
|
243 | to 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 |
|
|
247 | as resource names of the form <code>color+<index></code>, e.g. <code>color+5</code>. (will |
|
|
248 | likely change).</p> |
|
|
249 | </dd> |
|
|
250 | <dd> |
|
|
251 | <p>Please note that resource strings will currently only be freed when the |
|
|
252 | terminal 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 |
|
|
256 | are supported in every build, please see the source to see the actual |
|
|
257 | list:</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->selection_mark ([$row, $col])</a></strong><br /> |
275 | <dt><strong><a name="item_selection_mark">($row, $col) = $term->selection_mark ([$row, $col])</a></strong><br /> |
209 | </dt> |
276 | </dt> |
210 | <dt><strong><a name="item_selection_beg">($row, $col) = $term->selection_beg ([$row, $col])</a></strong><br /> |
277 | <dt><strong><a name="item_selection_beg">($row, $col) = $term->selection_beg ([$row, $col])</a></strong><br /> |
211 | </dt> |
278 | </dt> |
212 | <dt><strong><a name="item_selection_end">($row, $col) = $term->selection_end ([$row, $col])</a></strong><br /> |
279 | <dt><strong><a name="item_selection_end">($row, $col) = $term->selection_end ([$row, $col])</a></strong><br /> |
… | |
… | |
259 | <p></p> |
326 | <p></p> |
260 | <dt><strong><a name="item_scr_overlay_set">$term->scr_overlay_set ($x, $y, $text)</a></strong><br /> |
327 | <dt><strong><a name="item_scr_overlay_set">$term->scr_overlay_set ($x, $y, $text)</a></strong><br /> |
261 | </dt> |
328 | </dt> |
262 | <dd> |
329 | <dd> |
263 | Write a string at the given position into the overlay. |
330 | Write a string at the given position into the overlay. |
|
|
331 | </dd> |
|
|
332 | <p></p> |
|
|
333 | <dt><strong><a name="item_strwidth">$cellwidth = $term->strwidth $string</a></strong><br /> |
|
|
334 | </dt> |
|
|
335 | <dd> |
|
|
336 | Returns the number of screen-cells this string would need. Correctly |
|
|
337 | accounts for wide and combining characters. |
|
|
338 | </dd> |
|
|
339 | <p></p> |
|
|
340 | <dt><strong><a name="item_locale_encode">$octets = $term->locale_encode $string</a></strong><br /> |
|
|
341 | </dt> |
|
|
342 | <dd> |
|
|
343 | Convert the given text string into the corresponding locale encoding. |
|
|
344 | </dd> |
|
|
345 | <p></p> |
|
|
346 | <dt><strong><a name="item_locale_decode">$string = $term->locale_decode $octets</a></strong><br /> |
|
|
347 | </dt> |
|
|
348 | <dd> |
|
|
349 | Convert the given locale-encoded octets into a perl string. |
|
|
350 | </dd> |
|
|
351 | <p></p> |
|
|
352 | <dt><strong><a name="item_tt_write">$term->tt_write ($octets)</a></strong><br /> |
|
|
353 | </dt> |
|
|
354 | <dd> |
|
|
355 | Write the octets given in <code>$data</code> to the tty (i.e. as program input). To |
|
|
356 | pass characters instead of octets, you should convetr you strings first to |
|
|
357 | the locale-specific encoding using <a href="#item_locale_encode"><code>$term->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 |
|
|
484 | numbers 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 <pcg@goof.com> |
498 | Marc Lehmann <pcg@goof.com> |
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 | |