ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/cvsroot/rxvt-unicode/doc/rxvtperl.3.html
Revision: 1.20
Committed: Tue Jan 10 18:09:22 2006 UTC (20 years, 9 months ago) by root
Content type: text/html
Branch: MAIN
Changes since 1.19: +16 -9 lines
Log Message:
*** empty log message ***

File Contents

# User Rev Content
1 root 1.1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
2     <html xmlns="http://www.w3.org/1999/xhtml">
3     <head>
4     <title>rxvtperl - rxvt-unicode's embedded perl interpreter</title>
5     <link rev="made" href="mailto:perl-binary@plan9.de" />
6     </head>
7    
8     <body style="background-color: white">
9    
10     <p><a name="__index__"></a></p>
11     <!-- INDEX BEGIN -->
12    
13     <ul>
14    
15     <li><a href="#name">NAME</a></li>
16     <li><a href="#synopsis">SYNOPSIS</a></li>
17     <li><a href="#description">DESCRIPTION</a></li>
18 root 1.20 <li><a href="#prepackaged_extensions">PREPACKAGED EXTENSIONS</a></li>
19     <li><a href="#api_documentation">API DOCUMENTATION</a></li>
20 root 1.1 <ul>
21    
22 root 1.3 <li><a href="#general_api_considerations">General API Considerations</a></li>
23 root 1.19 <li><a href="#extension_objects">Extension Objects</a></li>
24 root 1.1 <li><a href="#hooks">Hooks</a></li>
25 root 1.9 <li><a href="#variables_in_the_urxvt_package">Variables in the <code>urxvt</code> Package</a></li>
26 root 1.1 <li><a href="#functions_in_the_urxvt_package">Functions in the <code>urxvt</code> Package</a></li>
27 root 1.8 <li><a href="#rendition">RENDITION</a></li>
28 root 1.16 <li><a href="#the_urxvt__anyevent_class">The <code>urxvt::anyevent</code> Class</a></li>
29 root 1.1 <li><a href="#the_urxvt__term_class">The <code>urxvt::term</code> Class</a></li>
30 root 1.15 <li><a href="#the_urxvt__popup_class">The <code>urxvt::popup</code> Class</a></li>
31 root 1.1 <li><a href="#the_urxvt__timer_class">The <code>urxvt::timer</code> Class</a></li>
32     <li><a href="#the_urxvt__iow_class">The <code>urxvt::iow</code> Class</a></li>
33     </ul>
34    
35 root 1.2 <li><a href="#environment">ENVIRONMENT</a></li>
36     <ul>
37    
38     <li><a href="#urxvt_perl_verbosity">URXVT_PERL_VERBOSITY</a></li>
39     </ul>
40    
41 root 1.1 <li><a href="#author">AUTHOR</a></li>
42     </ul>
43     <!-- INDEX END -->
44    
45     <hr />
46     <p>
47     </p>
48 root 1.7 <hr />
49 root 1.1 <h1><a name="name">NAME</a></h1>
50     <p>rxvtperl - rxvt-unicode's embedded perl interpreter</p>
51     <p>
52     </p>
53     <hr />
54     <h1><a name="synopsis">SYNOPSIS</a></h1>
55 root 1.5 <pre>
56     # create a file grab_test in $HOME:</pre>
57 root 1.1 <pre>
58     sub on_sel_grab {
59     warn &quot;you selected &quot;, $_[0]-&gt;selection;
60     ()
61     }</pre>
62     <pre>
63 root 1.5 # start a rxvt using it:</pre>
64     <pre>
65     rxvt --perl-lib $HOME -pe grab_test</pre>
66 root 1.1 <p>
67     </p>
68     <hr />
69     <h1><a name="description">DESCRIPTION</a></h1>
70 root 1.15 <p>Everytime a terminal object gets created, extension scripts specified via
71     the <code>perl</code> resource are loaded and associated with it.</p>
72 root 1.5 <p>Scripts are compiled in a 'use strict' and 'use utf8' environment, and
73     thus must be encoded as UTF-8.</p>
74 root 1.3 <p>Each script will only ever be loaded once, even in rxvtd, where
75 root 1.7 scripts will be shared (but not enabled) for all terminals.</p>
76 root 1.3 <p>
77     </p>
78 root 1.20 <hr />
79     <h1><a name="prepackaged_extensions">PREPACKAGED EXTENSIONS</a></h1>
80     <p>This section describes the extensions delivered with this release. You can
81 root 1.6 find them in <em>/opt/rxvt/lib/urxvt/perl/</em>.</p>
82     <p>You can activate them like this:</p>
83     <pre>
84     rxvt -pe &lt;extensionname&gt;</pre>
85     <dl>
86 root 1.16 <dt><strong><a name="item_selection">selection (enabled by default)</a></strong><br />
87 root 1.6 </dt>
88     <dd>
89 root 1.20 (More) intelligent selection. This extension tries to be more intelligent
90     when the user extends selections (double-click). Right now, it tries to
91     select urls and complete shell-quoted arguments, which is very convenient,
92     too, if your <em>ls</em> supports <code>--quoting-style=shell</code>.
93 root 1.9 </dd>
94     <dd>
95 root 1.20 <p>It also offers the following bindable keyboard command:</p>
96 root 1.6 </dd>
97     <dl>
98     <dt><strong><a name="item_rot13">rot13</a></strong><br />
99     </dt>
100     <dd>
101     Rot-13 the selection when activated. Used via keyboard trigger:
102     </dd>
103     <dd>
104     <pre>
105     URxvt.keysym.C-M-r: perl:selection:rot13</pre>
106     </dd>
107     <p></p></dl>
108 root 1.16 <dt><strong><a name="item_popup">option-popup (enabled by default)</a></strong><br />
109     </dt>
110     <dd>
111 root 1.17 Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at
112 root 1.16 runtime.
113     </dd>
114     <p></p>
115 root 1.17 <dt><strong>selection-popup (enabled by default)</strong><br />
116     </dt>
117     <dd>
118     Binds a popup menu to Ctrl-Button3 that lets you convert the selection
119 root 1.20 text into various other formats/action (such as uri unescaping, perl
120     evalution, web-browser starting etc.), depending on content.
121 root 1.17 </dd>
122     <p></p>
123 root 1.19 <dt><strong><a name="item_searchable_2dscrollback_3chotkey_3e__28enabled_by_">searchable-scrollback&lt;hotkey&gt; (enabled by default)</a></strong><br />
124     </dt>
125     <dd>
126     Adds regex search functionality to the scrollback buffer, triggered
127     by a hotkey (default: <code>M-s</code>). When in search mode, normal terminal
128     input/output is suspended.
129     </dd>
130     <dd>
131     <p><code>/</code> starts an incremental regex search, <code>n</code> searches further, <code>p</code> or
132     <code>N</code> jump to the previous match, <code>G</code> jumps to the bottom and clears the
133     history, <code>enter</code> leaves search mode at the current position and <code>escape</code>
134     returns to the original position.</p>
135     </dd>
136     <p></p>
137 root 1.6 <dt><strong><a name="item_digital_2dclock">digital-clock</a></strong><br />
138     </dt>
139     <dd>
140 root 1.8 Displays a digital clock using the built-in overlay.
141 root 1.6 </dd>
142     <p></p>
143 root 1.14 <dt><strong><a name="item_mark_2durls">mark-urls</a></strong><br />
144     </dt>
145     <dd>
146     Uses per-line display filtering (<code>on_line_update</code>) to underline urls.
147     </dd>
148     <p></p>
149     <dt><strong><a name="item_block_2dgraphics_2dto_2dascii">block-graphics-to-ascii</a></strong><br />
150     </dt>
151     <dd>
152     A not very useful example of filtering all text output to the terminal,
153     by replacing all line-drawing characters (U+2500 .. U+259F) by a
154     similar-looking ascii character.
155     </dd>
156     <p></p>
157 root 1.8 <dt><strong><a name="item_example_2drefresh_2dhooks">example-refresh-hooks</a></strong><br />
158 root 1.6 </dt>
159     <dd>
160 root 1.8 Displays a very simple digital clock in the upper right corner of the
161     window. Illustrates overwriting the refresh callbacks to create your own
162     overlays or changes.
163 root 1.6 </dd>
164     <p></p></dl>
165     <p>
166     </p>
167 root 1.20 <hr />
168     <h1><a name="api_documentation">API DOCUMENTATION</a></h1>
169     <p>
170     </p>
171 root 1.3 <h2><a name="general_api_considerations">General API Considerations</a></h2>
172     <p>All objects (such as terminals, time watchers etc.) are typical
173     reference-to-hash objects. The hash can be used to store anything you
174     like. All members starting with an underscore (such as <code>_ptr</code> or
175 root 1.9 <code>_hook</code>) are reserved for internal uses and <strong>MUST NOT</strong> be accessed or
176 root 1.3 modified).</p>
177     <p>When objects are destroyed on the C++ side, the perl object hashes are
178     emptied, so its best to store related objects such as time watchers and
179     the like inside the terminal object so they get destroyed as soon as the
180     terminal is destroyed.</p>
181 root 1.14 <p>Argument names also often indicate the type of a parameter. Here are some
182     hints on what they mean:</p>
183     <dl>
184     <dt><strong><a name="item__24text">$text</a></strong><br />
185     </dt>
186     <dd>
187     Rxvt-unicodes special way of encoding text, where one ``unicode'' character
188     always represents one screen cell. See <em>row_t</em> for a discussion of this format.
189     </dd>
190     <p></p>
191     <dt><strong><a name="item__24string">$string</a></strong><br />
192     </dt>
193     <dd>
194     A perl text string, with an emphasis on <em>text</em>. It can store all unicode
195     characters and is to be distinguished with text encoded in a specific
196     encoding (often locale-specific) and binary data.
197     </dd>
198     <p></p>
199     <dt><strong><a name="item__24octets">$octets</a></strong><br />
200     </dt>
201     <dd>
202     Either binary data or - more common - a text string encoded in a
203     locale-specific way.
204     </dd>
205     <p></p></dl>
206 root 1.1 <p>
207     </p>
208 root 1.19 <h2><a name="extension_objects">Extension Objects</a></h2>
209     <p>Very perl extension is a perl class. A separate perl object is created
210     for each terminal and each extension and passed as the first parameter to
211     hooks. So extensions can use their <code>$self</code> object without having to think
212     about other extensions, with the exception of methods and members that
213     begin with an underscore character <code>_</code>: these are reserved for internal
214     use.</p>
215     <p>Although it isn't a <code>urxvt::term</code> object, you can call all methods of the
216     <code>urxvt::term</code> class on this object.</p>
217     <p>It has the following methods and data members:</p>
218     <dl>
219     <dt><strong><a name="item__24urxvt_term__3d__24self_2d_3e_7bterm_7d">$urxvt_term = $self-&gt;{term}</a></strong><br />
220     </dt>
221     <dd>
222     Returns the <code>urxvt::term</code> object associated with this instance of the
223     extension. This member <em>must not</em> be changed in any way.
224     </dd>
225     <p></p>
226     <dt><strong><a name="item_enable">$self-&gt;enable ($hook_name =&gt; $cb, [$hook_name =&gt; $cb..])</a></strong><br />
227     </dt>
228     <dd>
229     Dynamically enable the given hooks (named without the <code>on_</code> prefix) for
230     this extension, replacing any previous hook. This is useful when you want
231     to overwrite time-critical hooks only temporarily.
232     </dd>
233     <p></p>
234     <dt><strong><a name="item_disable">$self-&gt;disable ($hook_name[, $hook_name..])</a></strong><br />
235     </dt>
236     <dd>
237     Dynamically disable the given hooks.
238     </dd>
239     <p></p></dl>
240     <p>
241     </p>
242 root 1.1 <h2><a name="hooks">Hooks</a></h2>
243 root 1.14 <p>The following subroutines can be declared in extension files, and will be
244 root 1.9 called whenever the relevant event happens.</p>
245 root 1.19 <p>The first argument passed to them is an extension oject as described in
246     the in the <code>Extension Objects</code> section.</p>
247     <p><strong>All</strong> of these hooks must return a boolean value. If it is true, then the
248     event counts as being <em>consumed</em>, and the invocation of other hooks is
249     skipped, and the relevant action might not be carried out by the C++ code.</p>
250     <p><em>When in doubt, return a false value (preferably <code>()</code>). </em>&gt;</p>
251 root 1.1 <dl>
252     <dt><strong><a name="item_on_init__24term">on_init $term</a></strong><br />
253     </dt>
254     <dd>
255     Called after a new terminal object has been initialized, but before
256 root 1.14 windows are created or the command gets run. Most methods are unsafe to
257     call or deliver senseless data, as terminal size and other characteristics
258     have not yet been determined. You can safely query and change resources,
259     though.
260 root 1.1 </dd>
261     <p></p>
262     <dt><strong><a name="item_on_reset__24term">on_reset $term</a></strong><br />
263     </dt>
264     <dd>
265     Called after the screen is ``reset'' for any reason, such as resizing or
266     control sequences. Here is where you can react on changes to size-related
267     variables.
268     </dd>
269     <p></p>
270     <dt><strong><a name="item_on_start__24term">on_start $term</a></strong><br />
271     </dt>
272     <dd>
273     Called at the very end of initialisation of a new terminal, just before
274     returning to the mainloop.
275     </dd>
276     <p></p>
277     <dt><strong><a name="item_on_sel_make__24term_2c__24eventtime">on_sel_make $term, $eventtime</a></strong><br />
278     </dt>
279     <dd>
280     Called whenever a selection has been made by the user, but before the
281     selection text is copied, so changes to the beginning, end or type of the
282     selection will be honored.
283     </dd>
284     <dd>
285     <p>Returning a true value aborts selection making by urxvt, in which case you
286     have to make a selection yourself by calling <a href="#item_selection_grab"><code>$term-&gt;selection_grab</code></a>.</p>
287     </dd>
288     <p></p>
289     <dt><strong><a name="item_on_sel_grab__24term_2c__24eventtime">on_sel_grab $term, $eventtime</a></strong><br />
290     </dt>
291     <dd>
292     Called whenever a selection has been copied, but before the selection is
293     requested from the server. The selection text can be queried and changed
294     by calling <a href="#item_selection"><code>$term-&gt;selection</code></a>.
295     </dd>
296     <dd>
297     <p>Returning a true value aborts selection grabbing. It will still be hilighted.</p>
298     </dd>
299     <p></p>
300 root 1.9 <dt><strong><a name="item_on_sel_extend__24term">on_sel_extend $term</a></strong><br />
301     </dt>
302     <dd>
303     Called whenever the user tries to extend the selection (e.g. with a double
304     click) and is either supposed to return false (normal operation), or
305     should extend the selection itelf and return true to suppress the built-in
306     processing.
307     </dd>
308     <dd>
309     <p>See the <em>selection</em> example extension.</p>
310     </dd>
311     <p></p>
312 root 1.1 <dt><strong><a name="item_on_view_change__24term_2c__24offset">on_view_change $term, $offset</a></strong><br />
313     </dt>
314     <dd>
315     Called whenever the view offset changes, i..e the user or program
316     scrolls. Offset <code>0</code> means display the normal terminal, positive values
317     show this many lines of scrollback.
318     </dd>
319     <p></p>
320     <dt><strong><a name="item_on_scroll_back__24term_2c__24lines_2c__24saved">on_scroll_back $term, $lines, $saved</a></strong><br />
321     </dt>
322     <dd>
323     Called whenever lines scroll out of the terminal area into the scrollback
324     buffer. <code>$lines</code> is the number of lines scrolled out and may be larger
325     than the scroll back buffer or the terminal.
326     </dd>
327     <dd>
328     <p>It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
329     $nrow - 1) represent the lines to be scrolled out). <code>$saved</code> is the total
330     number of lines that will be in the scrollback buffer.</p>
331     </dd>
332     <p></p>
333 root 1.11 <dt><strong><a name="item_on_osc_seq__24term_2c__24string">on_osc_seq $term, $string</a></strong><br />
334     </dt>
335     <dd>
336     Called whenever the <strong>ESC ] 777 ; string ST</strong> command sequence (OSC =
337     operating system command) is processed. Cursor position and other state
338     information is up-to-date when this happens. For interoperability, the
339     string should start with the extension name and a colon, to distinguish
340     it from commands for other extensions, and this might be enforced in the
341     future.
342     </dd>
343     <dd>
344     <p>Be careful not ever to trust (in a security sense) the data you receive,
345     as its source can not easily be controleld (e-mail content, messages from
346     other users on the same system etc.).</p>
347     </dd>
348     <p></p>
349 root 1.14 <dt><strong><a name="item_on_add_lines__24term_2c__24string">on_add_lines $term, $string</a></strong><br />
350     </dt>
351     <dd>
352     Called whenever text is about to be output, with the text as argument. You
353     can filter/change and output the text yourself by returning a true value
354     and calling <a href="#item_scr_add_lines"><code>$term-&gt;scr_add_lines</code></a> yourself. Please note that this
355     might be very slow, however, as your hook is called for <strong>all</strong> text being
356     output.
357     </dd>
358     <p></p>
359 root 1.19 <dt><strong><a name="item_on_tt_write__24term_2c__24octets">on_tt_write $term, $octets</a></strong><br />
360     </dt>
361     <dd>
362     Called whenever some data is written to the tty/pty and can be used to
363     suppress or filter tty input.
364     </dd>
365     <p></p>
366 root 1.14 <dt><strong><a name="item_on_line_update__24term_2c__24row">on_line_update $term, $row</a></strong><br />
367     </dt>
368     <dd>
369     Called whenever a line was updated or changed. Can be used to filter
370     screen output (e.g. underline urls or other useless stuff). Only lines
371     that are being shown will be filtered, and, due to performance reasons,
372     not always immediately.
373     </dd>
374     <dd>
375     <p>The row number is always the topmost row of the line if the line spans
376     multiple rows.</p>
377     </dd>
378     <dd>
379     <p>Please note that, if you change the line, then the hook might get called
380     later with the already-modified line (e.g. if unrelated parts change), so
381     you cannot just toggle rendition bits, but only set them.</p>
382     </dd>
383     <p></p>
384 root 1.1 <dt><strong><a name="item_on_refresh_begin__24term">on_refresh_begin $term</a></strong><br />
385     </dt>
386     <dd>
387     Called just before the screen gets redrawn. Can be used for overlay
388     or similar effects by modify terminal contents in refresh_begin, and
389     restoring them in refresh_end. The built-in overlay and selection display
390     code is run after this hook, and takes precedence.
391     </dd>
392     <p></p>
393     <dt><strong><a name="item_on_refresh_end__24term">on_refresh_end $term</a></strong><br />
394     </dt>
395     <dd>
396     Called just after the screen gets redrawn. See <code>on_refresh_begin</code>.
397     </dd>
398 root 1.5 <p></p>
399     <dt><strong><a name="item_on_keyboard_command__24term_2c__24string">on_keyboard_command $term, $string</a></strong><br />
400     </dt>
401     <dd>
402     Called whenever the user presses a key combination that has a
403     <code>perl:string</code> action bound to it (see description of the <strong>keysym</strong>
404     resource in the <code>rxvt(1)</code> manpage).
405     </dd>
406 root 1.14 <p></p>
407 root 1.15 <dt><strong><a name="item_on_focus_in__24term">on_focus_in $term</a></strong><br />
408     </dt>
409     <dd>
410     Called whenever the window gets the keyboard focus, before rxvt-unicode
411     does focus in processing.
412     </dd>
413     <p></p>
414     <dt><strong><a name="item_on_focus_out__24term">on_focus_out $term</a></strong><br />
415     </dt>
416     <dd>
417     Called wheneever the window loses keyboard focus, before rxvt-unicode does
418     focus out processing.
419     </dd>
420     <p></p>
421 root 1.19 <dt><strong><a name="item_on_key_press__24term_2c__24event_2c__24keysym_2c__">on_key_press $term, $event, $keysym, $octets</a></strong><br />
422 root 1.14 </dt>
423 root 1.19 <dt><strong><a name="item_on_key_release__24term_2c__24event_2c__24keysym">on_key_release $term, $event, $keysym</a></strong><br />
424 root 1.14 </dt>
425     <dt><strong><a name="item_on_button_press__24term_2c__24event">on_button_press $term, $event</a></strong><br />
426     </dt>
427     <dt><strong><a name="item_on_button_release__24term_2c__24event">on_button_release $term, $event</a></strong><br />
428     </dt>
429     <dt><strong><a name="item_on_motion_notify__24term_2c__24event">on_motion_notify $term, $event</a></strong><br />
430     </dt>
431 root 1.15 <dt><strong><a name="item_on_map_notify__24term_2c__24event">on_map_notify $term, $event</a></strong><br />
432     </dt>
433     <dt><strong><a name="item_on_unmap_notify__24term_2c__24event">on_unmap_notify $term, $event</a></strong><br />
434     </dt>
435 root 1.14 <dd>
436     Called whenever the corresponding X event is received for the terminal If
437     the hook returns true, then the even will be ignored by rxvt-unicode.
438     </dd>
439     <dd>
440     <p>The event is a hash with most values as named by Xlib (see the XEvent
441     manpage), with the additional members <code>row</code> and <code>col</code>, which are the row
442     and column under the mouse cursor.</p>
443     </dd>
444     <dd>
445     <p><code>on_key_press</code> additionally receives the string rxvt-unicode would
446     output, if any, in locale-specific encoding.</p>
447     </dd>
448     <dd>
449     <p>subwindow.</p>
450     </dd>
451 root 1.1 <p></p></dl>
452     <p>
453     </p>
454 root 1.9 <h2><a name="variables_in_the_urxvt_package">Variables in the <code>urxvt</code> Package</a></h2>
455     <dl>
456     <dt><strong><a name="item__24urxvt_3a_3aterm">$urxvt::TERM</a></strong><br />
457     </dt>
458     <dd>
459 root 1.14 The current terminal. This variable stores the current <code>urxvt::term</code>
460     object, whenever a callback/hook is executing.
461 root 1.9 </dd>
462     <p></p></dl>
463     <p>
464     </p>
465 root 1.1 <h2><a name="functions_in_the_urxvt_package">Functions in the <code>urxvt</code> Package</a></h2>
466     <dl>
467 root 1.14 <dt><strong><a name="item__24term__3d_new_urxvt__5barg_2e_2e_2e_5d">$term = new urxvt [arg...]</a></strong><br />
468     </dt>
469     <dd>
470     Creates a new terminal, very similar as if you had started it with
471     <code>system $binfile, arg...</code>. Croaks (and probably outputs an error message)
472     if the new instance couldn't be created. Returns <code>undef</code> if the new
473     instance didn't initialise perl, and the terminal object otherwise. The
474     <code>init</code> and <a href="#item_start"><code>start</code></a> hooks will be called during the call.
475     </dd>
476     <p></p>
477 root 1.1 <dt><strong><a name="item_urxvt_3a_3afatal__24errormessage">urxvt::fatal $errormessage</a></strong><br />
478     </dt>
479     <dd>
480     Fatally aborts execution with the given error message. Avoid at all
481     costs! The only time this is acceptable is when the terminal process
482     starts up.
483     </dd>
484     <p></p>
485     <dt><strong><a name="item_urxvt_3a_3awarn__24string">urxvt::warn $string</a></strong><br />
486     </dt>
487     <dd>
488 root 1.3 Calls <code>rxvt_warn</code> with the given string which should not include a
489 root 1.1 newline. The module also overwrites the <code>warn</code> builtin with a function
490     that calls this function.
491     </dd>
492     <dd>
493     <p>Using this function has the advantage that its output ends up in the
494     correct place, e.g. on stderr of the connecting urxvtc client.</p>
495     </dd>
496     <p></p>
497 root 1.18 <dt><strong><a name="item__24is_safe__3d_urxvt_3a_3asafe">$is_safe = urxvt::safe</a></strong><br />
498     </dt>
499     <dd>
500     Returns true when it is safe to do potentially unsafe things, such as
501     evaluating perl code specified by the user. This is true when urxvt was
502     started setuid or setgid.
503     </dd>
504     <p></p>
505 root 1.1 <dt><strong><a name="item__24time__3d_urxvt_3a_3anow">$time = urxvt::NOW</a></strong><br />
506     </dt>
507     <dd>
508     Returns the ``current time'' (as per the event loop).
509     </dd>
510 root 1.15 <p></p>
511     <dt><strong><a name="item_urxvt_3a_3acurrenttime">urxvt::CurrentTime</a></strong><br />
512     </dt>
513     <dt><strong><a name="item_urxvt_3a_3ashiftmask_2c_lockmask_2c_controlmask_2c">urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
514     Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
515     Button4Mask, Button5Mask, AnyModifier</a></strong><br />
516     </dt>
517     <dd>
518 root 1.16 Various constants for use in X calls and event processing.
519 root 1.15 </dd>
520 root 1.1 <p></p></dl>
521     <p>
522     </p>
523 root 1.8 <h2><a name="rendition">RENDITION</a></h2>
524     <p>Rendition bitsets contain information about colour, font, font styles and
525     similar information for each screen cell.</p>
526     <p>The following ``macros'' deal with changes in rendition sets. You should
527     never just create a bitset, you should always modify an existing one,
528     as they contain important information required for correct operation of
529     rxvt-unicode.</p>
530     <dl>
531     <dt><strong><a name="item__24rend__3d_urxvt_3a_3adefault_rstyle">$rend = urxvt::DEFAULT_RSTYLE</a></strong><br />
532     </dt>
533     <dd>
534     Returns the default rendition, as used when the terminal is starting up or
535     being reset. Useful as a base to start when creating renditions.
536     </dd>
537     <p></p>
538     <dt><strong><a name="item__24rend__3d_urxvt_3a_3aoverlay_rstyle">$rend = urxvt::OVERLAY_RSTYLE</a></strong><br />
539     </dt>
540     <dd>
541     Return the rendition mask used for overlays by default.
542     </dd>
543     <p></p>
544     <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 />
545     </dt>
546     <dd>
547     Return the bit that enabled bold, italic, blink, reverse-video and
548     underline, respectively. To enable such a style, just logically OR it into
549     the bitset.
550     </dd>
551     <p></p>
552     <dt><strong><a name="item__24foreground__3d_urxvt_3a_3aget_basefg__24rend">$foreground = urxvt::GET_BASEFG $rend</a></strong><br />
553     </dt>
554     <dt><strong><a name="item__24background__3d_urxvt_3a_3aget_basebg__24rend">$background = urxvt::GET_BASEBG $rend</a></strong><br />
555     </dt>
556     <dd>
557     Return the foreground/background colour index, respectively.
558     </dd>
559     <p></p>
560     <dt><strong><a name="item_set_fgcolor">$rend = urxvt::SET_FGCOLOR ($rend, $new_colour)</a></strong><br />
561     </dt>
562     <dt><strong><a name="item_set_bgcolor">$rend = urxvt::SET_BGCOLOR ($rend, $new_colour)</a></strong><br />
563     </dt>
564     <dd>
565     Replace the foreground/background colour in the rendition mask with the
566     specified one.
567     </dd>
568     <p></p>
569     <dt><strong><a name="item_get_custom">$value = urxvt::GET_CUSTOM ($rend)</a></strong><br />
570     </dt>
571     <dd>
572     Return the ``custom'' value: Every rendition has 5 bits for use by
573     extensions. They can be set and changed as you like and are initially
574     zero.
575     </dd>
576     <p></p>
577     <dt><strong><a name="item_set_custom">$rend = urxvt::SET_CUSTOM ($rend, $new_value)</a></strong><br />
578     </dt>
579     <dd>
580     Change the custom value.
581     </dd>
582     <p></p></dl>
583     <p>
584     </p>
585 root 1.16 <h2><a name="the_urxvt__anyevent_class">The <code>urxvt::anyevent</code> Class</a></h2>
586     <p>The sole purpose of this class is to deliver an interface to the
587     <code>AnyEvent</code> module - any module using it will work inside urxvt without
588     further work. The only exception is that you cannot wait on condition
589     variables, but non-blocking condvar use is ok. What this means is that you
590     cannot use blocking APIs, but the non-blocking variant should work.</p>
591     <p>
592     </p>
593 root 1.1 <h2><a name="the_urxvt__term_class">The <code>urxvt::term</code> Class</a></h2>
594     <dl>
595 root 1.14 <dt><strong><a name="item_destroy">$term-&gt;destroy</a></strong><br />
596     </dt>
597     <dd>
598     Destroy the terminal object (close the window, free resources etc.).
599     </dd>
600     <p></p>
601 root 1.15 <dt><strong><a name="item_option">$isset = $term-&gt;option ($optval[, $set])</a></strong><br />
602     </dt>
603     <dd>
604     Returns true if the option specified by <code>$optval</code> is enabled, and
605     optionally change it. All option values are stored by name in the hash
606     <code>%urxvt::OPTION</code>. Options not enabled in this binary are not in the hash.
607     </dd>
608     <dd>
609     <p>Here is a a likely non-exhaustive list of option names, please see the
610     source file <em>/src/optinc.h</em> to see the actual list:</p>
611     </dd>
612     <dd>
613     <pre>
614     borderLess console cursorBlink cursorUnderline hold iconic insecure
615     intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
616     pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating
617     scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer
618     secondaryScreen secondaryScroll skipBuiltinGlyphs transparent
619     tripleclickwords utmpInhibit visualBell</pre>
620     </dd>
621     <p></p>
622 root 1.2 <dt><strong><a name="item_resource">$value = $term-&gt;resource ($name[, $newval])</a></strong><br />
623     </dt>
624     <dd>
625     Returns the current resource value associated with a given name and
626     optionally sets a new value. Setting values is most useful in the <code>init</code>
627     hook. Unset resources are returned and accepted as <code>undef</code>.
628     </dd>
629     <dd>
630     <p>The new value must be properly encoded to a suitable character encoding
631     before passing it to this method. Similarly, the returned value may need
632     to be converted from the used encoding to text.</p>
633     </dd>
634     <dd>
635     <p>Resource names are as defined in <em>src/rsinc.h</em>. Colours can be specified
636     as resource names of the form <code>color+&lt;index&gt;</code>, e.g. <code>color+5</code>. (will
637     likely change).</p>
638     </dd>
639     <dd>
640     <p>Please note that resource strings will currently only be freed when the
641     terminal is destroyed, so changing options frequently will eat memory.</p>
642     </dd>
643     <dd>
644     <p>Here is a a likely non-exhaustive list of resource names, not all of which
645 root 1.15 are supported in every build, please see the source file <em>/src/rsinc.h</em>
646     to see the actual list:</p>
647 root 1.2 </dd>
648     <dd>
649     <pre>
650     answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
651     borderLess color cursorBlink cursorUnderline cutchars delete_key
652     display_name embed ext_bwidth fade font geometry hold iconName
653     imFont imLocale inputMethod insecure int_bwidth intensityStyles
654 root 1.4 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
655 root 1.12 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2
656 root 1.3 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
657     reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
658     scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
659     scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
660     shade term_name title transparent transparent_all tripleclickwords
661     utmpInhibit visualBell</pre>
662 root 1.2 </dd>
663     <p></p>
664 root 1.19 <dt><strong><a name="item_parse_keysym">$success = $term-&gt;parse_keysym ($keysym_spec, $command_string)</a></strong><br />
665     </dt>
666     <dd>
667     Adds a keymap translation exactly as specified via a resource. See the
668     <code>keysym</code> resource in the <code>rxvt(1)</code> manpage.
669     </dd>
670     <p></p>
671 root 1.14 <dt><strong><a name="item_rstyle">$rend = $term-&gt;rstyle ([$new_rstyle])</a></strong><br />
672 root 1.13 </dt>
673     <dd>
674 root 1.14 Return and optionally change the current rendition. Text that is output by
675     the terminal application will use this style.
676 root 1.13 </dd>
677     <p></p>
678     <dt><strong><a name="item_screen_cur">($row, $col) = $term-&gt;screen_cur ([$row, $col])</a></strong><br />
679     </dt>
680     <dd>
681     Return the current coordinates of the text cursor position and optionally
682     set it (which is usually bad as applications don't expect that).
683     </dd>
684     <p></p>
685 root 1.1 <dt><strong><a name="item_selection_mark">($row, $col) = $term-&gt;selection_mark ([$row, $col])</a></strong><br />
686     </dt>
687     <dt><strong><a name="item_selection_beg">($row, $col) = $term-&gt;selection_beg ([$row, $col])</a></strong><br />
688     </dt>
689     <dt><strong><a name="item_selection_end">($row, $col) = $term-&gt;selection_end ([$row, $col])</a></strong><br />
690     </dt>
691     <dd>
692     Return the current values of the selection mark, begin or end positions,
693     and optionally set them to new values.
694     </dd>
695     <p></p>
696     <dt><strong><a name="item_selection_grab">$success = $term-&gt;selection_grab ($eventtime)</a></strong><br />
697     </dt>
698     <dd>
699     Try to request the primary selection from the server (for example, as set
700     by the next method).
701     </dd>
702     <p></p>
703 root 1.6 <dt><strong>$oldtext = $term-&gt;selection ([$newtext])</strong><br />
704 root 1.1 </dt>
705     <dd>
706     Return the current selection text and optionally replace it by <code>$newtext</code>.
707     </dd>
708 root 1.19 <p></p>
709     <dt><strong><a name="item_overlay_simple">$term-&gt;overlay_simple ($x, $y, $text)</a></strong><br />
710     </dt>
711 root 1.1 <dd>
712 root 1.19 Create a simple multi-line overlay box. See the next method for details.
713 root 1.1 </dd>
714     <p></p>
715 root 1.8 <dt><strong><a name="item_overlay">$term-&gt;overlay ($x, $y, $width, $height[, $rstyle[, $border]])</a></strong><br />
716 root 1.1 </dt>
717     <dd>
718     Create a new (empty) overlay at the given position with the given
719 root 1.8 width/height. <code>$rstyle</code> defines the initial rendition style
720     (default: <code>OVERLAY_RSTYLE</code>).
721     </dd>
722     <dd>
723     <p>If <code>$border</code> is <code>2</code> (default), then a decorative border will be put
724     around the box.</p>
725     </dd>
726     <dd>
727     <p>If either <code>$x</code> or <code>$y</code> is negative, then this is counted from the
728     right/bottom side, respectively.</p>
729 root 1.1 </dd>
730     <dd>
731 root 1.8 <p>This method returns an urxvt::overlay object. The overlay will be visible
732     as long as the perl object is referenced.</p>
733 root 1.1 </dd>
734     <dd>
735 root 1.9 <p>The methods currently supported on <code>urxvt::overlay</code> objects are:</p>
736 root 1.1 </dd>
737 root 1.9 <dl>
738 root 1.8 <dt><strong><a name="item_set">$overlay-&gt;set ($x, $y, $text, $rend)</a></strong><br />
739 root 1.1 </dt>
740     <dd>
741 root 1.8 Similar 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
742     text in rxvt-unicode's special encoding and an array of rendition values
743     at a specific position inside the overlay.
744 root 1.1 </dd>
745 root 1.3 <p></p>
746 root 1.9 <dt><strong><a name="item_hide">$overlay-&gt;hide</a></strong><br />
747     </dt>
748     <dd>
749     If visible, hide the overlay, but do not destroy it.
750     </dd>
751     <p></p>
752     <dt><strong><a name="item_show">$overlay-&gt;show</a></strong><br />
753     </dt>
754     <dd>
755     If hidden, display the overlay again.
756     </dd>
757     <p></p></dl>
758 root 1.16 <dt><strong>$popup = $term-&gt;popup ($event)</strong><br />
759 root 1.15 </dt>
760     <dd>
761     Creates a new <code>urxvt::popup</code> object that implements a popup menu. The
762     <code>$event</code> <em>must</em> be the event causing the menu to pop up (a button event,
763     currently).
764     </dd>
765     <p></p>
766 root 1.14 <dt><strong><a name="item_strwidth">$cellwidth = $term-&gt;strwidth ($string)</a></strong><br />
767 root 1.3 </dt>
768     <dd>
769     Returns the number of screen-cells this string would need. Correctly
770     accounts for wide and combining characters.
771     </dd>
772     <p></p>
773 root 1.14 <dt><strong><a name="item_locale_encode">$octets = $term-&gt;locale_encode ($string)</a></strong><br />
774 root 1.3 </dt>
775     <dd>
776     Convert the given text string into the corresponding locale encoding.
777     </dd>
778     <p></p>
779 root 1.14 <dt><strong><a name="item_locale_decode">$string = $term-&gt;locale_decode ($octets)</a></strong><br />
780 root 1.3 </dt>
781     <dd>
782     Convert the given locale-encoded octets into a perl string.
783     </dd>
784     <p></p>
785 root 1.19 <dt><strong><a name="item_scr_xor_span">$term-&gt;scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])</a></strong><br />
786     </dt>
787     <dd>
788     XORs the rendition values in the given span with the provided value
789     (default: <code>RS_RVid</code>). Useful in refresh hooks to provide effects similar
790     to the selection.
791     </dd>
792     <p></p>
793     <dt><strong><a name="item_scr_xor_rect">$term-&gt;scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, $rstyle2]])</a></strong><br />
794     </dt>
795     <dd>
796     Similar to <a href="#item_scr_xor_span"><code>scr_xor_span</code></a>, but xors a rectangle instead. Trailing
797     whitespace will additionally be xored with the <code>$rstyle2</code>, which defaults
798     to <code>RS_RVid | RS_Uline</code>, which removes reverse video again and underlines
799     it instead.
800     </dd>
801     <p></p>
802     <dt><strong><a name="item_scr_bell">$term-&gt;scr_bell</a></strong><br />
803     </dt>
804     <dd>
805     Ring the bell!
806     </dd>
807     <p></p>
808 root 1.14 <dt><strong><a name="item_scr_add_lines">$term-&gt;scr_add_lines ($string)</a></strong><br />
809     </dt>
810     <dd>
811     Write the given text string to the screen, as if output by the application
812     running inside the terminal. It may not contain command sequences (escape
813     codes), but is free to use line feeds, carriage returns and tabs. The
814     string is a normal text string, not in locale-dependent encoding.
815     </dd>
816     <dd>
817     <p>Normally its not a good idea to use this function, as programs might be
818     confused by changes in cursor position or scrolling. Its useful inside a
819     <code>on_add_lines</code> hook, though.</p>
820     </dd>
821     <p></p>
822     <dt><strong><a name="item_cmd_parse">$term-&gt;cmd_parse ($octets)</a></strong><br />
823     </dt>
824     <dd>
825     Similar to <a href="#item_scr_add_lines"><code>scr_add_lines</code></a>, but the argument must be in the
826     locale-specific encoding of the terminal and can contain command sequences
827     (escape codes) that will be interpreted.
828     </dd>
829     <p></p>
830 root 1.3 <dt><strong><a name="item_tt_write">$term-&gt;tt_write ($octets)</a></strong><br />
831     </dt>
832     <dd>
833     Write the octets given in <code>$data</code> to the tty (i.e. as program input). To
834 root 1.6 pass characters instead of octets, you should convert your strings first
835     to the locale-specific encoding using <a href="#item_locale_encode"><code>$term-&gt;locale_encode</code></a>.
836     </dd>
837     <p></p>
838 root 1.19 <dt><strong><a name="item_pty_ev_events">$old_events = $term-&gt;pty_ev_events ([$new_events])</a></strong><br />
839     </dt>
840     <dd>
841     Replaces the event mask of the pty watcher by the given event mask. Can
842     be used to suppress input and output handling to the pty/tty. See the
843     description of <a href="#item_events"><code>urxvt::timer-&gt;events</code></a>. Make sure to always restore
844     the previous value.
845     </dd>
846     <p></p>
847 root 1.14 <dt><strong><a name="item_parent">$windowid = $term-&gt;parent</a></strong><br />
848     </dt>
849     <dd>
850     Return the window id of the toplevel window.
851     </dd>
852     <p></p>
853     <dt><strong><a name="item_vt">$windowid = $term-&gt;vt</a></strong><br />
854     </dt>
855     <dd>
856     Return the window id of the terminal window.
857     </dd>
858     <p></p>
859 root 1.13 <dt><strong><a name="item_width">$window_width = $term-&gt;width</a></strong><br />
860     </dt>
861     <dt><strong><a name="item_height">$window_height = $term-&gt;height</a></strong><br />
862     </dt>
863     <dt><strong><a name="item_fwidth">$font_width = $term-&gt;fwidth</a></strong><br />
864 root 1.6 </dt>
865 root 1.13 <dt><strong><a name="item_fheight">$font_height = $term-&gt;fheight</a></strong><br />
866 root 1.6 </dt>
867 root 1.13 <dt><strong><a name="item_fbase">$font_ascent = $term-&gt;fbase</a></strong><br />
868     </dt>
869     <dt><strong><a name="item_nrow">$terminal_rows = $term-&gt;nrow</a></strong><br />
870     </dt>
871     <dt><strong><a name="item_ncol">$terminal_columns = $term-&gt;ncol</a></strong><br />
872     </dt>
873     <dt><strong><a name="item_focus">$has_focus = $term-&gt;focus</a></strong><br />
874     </dt>
875     <dt><strong><a name="item_mapped">$is_mapped = $term-&gt;mapped</a></strong><br />
876     </dt>
877     <dt><strong><a name="item_savelines">$max_scrollback = $term-&gt;saveLines</a></strong><br />
878     </dt>
879     <dt><strong><a name="item_total_rows">$nrow_plus_saveLines = $term-&gt;total_rows</a></strong><br />
880     </dt>
881     <dt><strong><a name="item_nsaved">$lines_in_scrollback = $term-&gt;nsaved</a></strong><br />
882 root 1.6 </dt>
883     <dd>
884 root 1.13 Return various integers describing terminal characteristics.
885 root 1.6 </dd>
886     <p></p>
887 root 1.19 <dt><strong><a name="item_locale">$lc_ctype = $term-&gt;locale</a></strong><br />
888     </dt>
889     <dd>
890     Returns the LC_CTYPE category string used by this rxvt-unicode.
891     </dd>
892     <p></p>
893     <dt><strong><a name="item_display_id">$x_display = $term-&gt;display_id</a></strong><br />
894     </dt>
895     <dd>
896     Return the DISPLAY used by rxvt-unicode.
897     </dd>
898     <p></p>
899 root 1.15 <dt><strong><a name="item_modlevel3mask">$modifiermask = $term-&gt;ModLevel3Mask</a></strong><br />
900     </dt>
901     <dt><strong><a name="item_modmetamask">$modifiermask = $term-&gt;ModMetaMask</a></strong><br />
902     </dt>
903     <dt><strong><a name="item_modnumlockmask">$modifiermask = $term-&gt;ModNumLockMask</a></strong><br />
904     </dt>
905     <dd>
906     Return the modifier masks corresponding to the ``ISO Level 3 Shift'' (often
907     AltGr), the meta key (often Alt) and the num lock key, if applicable.
908     </dd>
909     <p></p>
910 root 1.6 <dt><strong><a name="item_view_start">$view_start = $term-&gt;view_start ([$newvalue])</a></strong><br />
911     </dt>
912     <dd>
913     Returns the negative row number of the topmost line. Minimum value is
914     <code>0</code>, which displays the normal terminal contents. Larger values scroll
915     this many lines into the scrollback buffer.
916     </dd>
917     <p></p>
918     <dt><strong><a name="item_want_refresh">$term-&gt;want_refresh</a></strong><br />
919     </dt>
920     <dd>
921     Requests a screen refresh. At the next opportunity, rxvt-unicode will
922     compare the on-screen display with its stored representation. If they
923     differ, it redraws the differences.
924     </dd>
925     <dd>
926     <p>Used after changing terminal contents to display them.</p>
927     </dd>
928     <p></p>
929     <dt><strong><a name="item_row_t">$text = $term-&gt;ROW_t ($row_number[, $new_text[, $start_col]])</a></strong><br />
930     </dt>
931     <dd>
932     Returns the text of the entire row with number <code>$row_number</code>. Row <code>0</code>
933     is the topmost terminal line, row <code>$term-&gt;$ncol-1</code> is the bottommost
934     terminal line. The scrollback buffer starts at line <code>-1</code> and extends to
935 root 1.9 line <a href="#item_nsaved"><code>-$term-&gt;nsaved</code></a>. Nothing will be returned if a nonexistent line
936     is requested.
937 root 1.6 </dd>
938     <dd>
939     <p>If <code>$new_text</code> is specified, it will replace characters in the current
940     line, starting at column <code>$start_col</code> (default <code>0</code>), which is useful
941 root 1.8 to replace only parts of a line. The font index in the rendition will
942 root 1.6 automatically be updated.</p>
943     </dd>
944     <dd>
945 root 1.14 <p><a href="#item__24text"><code>$text</code></a> is in a special encoding: tabs and wide characters that use more
946 root 1.6 than one cell when displayed are padded with urxvt::NOCHAR characters
947     (<code>chr 65535</code>). Characters with combining characters and other characters
948     that do not fit into the normal tetx encoding will be replaced with
949     characters in the private use area.</p>
950     </dd>
951     <dd>
952     <p>You have to obey this encoding when changing text. The advantage is
953     that <code>substr</code> and similar functions work on screen cells and not on
954     characters.</p>
955     </dd>
956     <dd>
957 root 1.17 <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>
958 root 1.6 can be used to convert normal strings into this encoding and vice versa.</p>
959     </dd>
960     <p></p>
961     <dt><strong><a name="item_row_r">$rend = $term-&gt;ROW_r ($row_number[, $new_rend[, $start_col]])</a></strong><br />
962     </dt>
963     <dd>
964     Like <a href="#item_row_t"><code>$term-&gt;ROW_t</code></a>, but returns an arrayref with rendition
965     bitsets. Rendition bitsets contain information about colour, font, font
966     styles and similar information. See also <a href="#item_row_t"><code>$term-&gt;ROW_t</code></a>.
967     </dd>
968     <dd>
969     <p>When setting rendition, the font mask will be ignored.</p>
970     </dd>
971     <dd>
972 root 1.8 <p>See the section on RENDITION, above.</p>
973 root 1.6 </dd>
974     <p></p>
975     <dt><strong><a name="item_row_l">$length = $term-&gt;ROW_l ($row_number[, $new_length])</a></strong><br />
976     </dt>
977     <dd>
978 root 1.9 Returns the number of screen cells that are in use (``the line
979     length''). Unlike the urxvt core, this returns <a href="#item_ncol"><code>$term-&gt;ncol</code></a> if the
980     line is joined with the following one.
981     </dd>
982     <p></p>
983     <dt><strong><a name="item_is_longer">$bool = $term-&gt;is_longer ($row_number)</a></strong><br />
984     </dt>
985     <dd>
986     Returns true if the row is part of a multiple-row logical ``line'' (i.e.
987     joined with the following row), which means all characters are in use
988     and it is continued on the next row (and possibly a continuation of the
989     previous row(s)).
990 root 1.6 </dd>
991     <p></p>
992 root 1.9 <dt><strong><a name="item_line">$line = $term-&gt;line ($row_number)</a></strong><br />
993     </dt>
994     <dd>
995     Create and return a new <code>urxvt::line</code> object that stores information
996     about the logical line that row <code>$row_number</code> is part of. It supports the
997     following methods:
998     </dd>
999     <dl>
1000 root 1.14 <dt><strong><a name="item_t">$text = $line-&gt;t ([$new_text])</a></strong><br />
1001 root 1.9 </dt>
1002     <dd>
1003 root 1.14 Returns or replaces the full text of the line, similar to <a href="#item_row_t"><code>ROW_t</code></a>
1004 root 1.9 </dd>
1005     <p></p>
1006 root 1.14 <dt><strong><a name="item_r">$rend = $line-&gt;r ([$new_rend])</a></strong><br />
1007 root 1.9 </dt>
1008     <dd>
1009 root 1.14 Returns or replaces the full rendition array of the line, similar to <a href="#item_row_r"><code>ROW_r</code></a>
1010 root 1.9 </dd>
1011     <p></p>
1012     <dt><strong><a name="item_l">$length = $line-&gt;l</a></strong><br />
1013     </dt>
1014     <dd>
1015     Returns the length of the line in cells, similar to <a href="#item_row_l"><code>ROW_l</code></a>.
1016     </dd>
1017     <p></p>
1018     <dt><strong><a name="item_beg">$rownum = $line-&gt;beg</a></strong><br />
1019     </dt>
1020     <dt><strong><a name="item_end">$rownum = $line-&gt;end</a></strong><br />
1021     </dt>
1022     <dd>
1023     Return the row number of the first/last row of the line, respectively.
1024     </dd>
1025     <p></p>
1026     <dt><strong><a name="item_offset_of">$offset = $line-&gt;offset_of ($row, $col)</a></strong><br />
1027     </dt>
1028     <dd>
1029     Returns the character offset of the given row|col pair within the logical
1030     line.
1031     </dd>
1032     <p></p>
1033     <dt><strong><a name="item_coord_of">($row, $col) = $line-&gt;coord_of ($offset)</a></strong><br />
1034     </dt>
1035     <dd>
1036     Translates a string offset into terminal coordinates again.
1037     </dd>
1038     <p></p></dl>
1039 root 1.17 <dt><strong><a name="item_special_encode">$text = $term-&gt;special_encode $string</a></strong><br />
1040 root 1.6 </dt>
1041     <dd>
1042     Converts a perl string into the special encoding used by rxvt-unicode,
1043     where one character corresponds to one screen cell. See
1044     <a href="#item_row_t"><code>$term-&gt;ROW_t</code></a> for details.
1045     </dd>
1046     <p></p>
1047     <dt><strong><a name="item_special_decode">$string = $term-&gt;special_decode $text</a></strong><br />
1048     </dt>
1049     <dd>
1050     Converts rxvt-unicodes text reprsentation into a perl string. See
1051     <a href="#item_row_t"><code>$term-&gt;ROW_t</code></a> for details.
1052     </dd>
1053 root 1.17 <p></p>
1054     <dt><strong><a name="item_grab_button">$success = $term-&gt;grab_button ($button, $modifiermask)</a></strong><br />
1055     </dt>
1056     <dd>
1057 root 1.18 Registers a synchronous button grab. See the XGrabButton manpage.
1058 root 1.17 </dd>
1059     <p></p>
1060     <dt><strong><a name="item_grab">$success = $term-&gt;grab ($eventtime[, $sync])</a></strong><br />
1061     </dt>
1062     <dd>
1063     Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1064     synchronous (<code>$sync</code> is true). Also remembers the grab timestampe.
1065     </dd>
1066     <p></p>
1067     <dt><strong><a name="item_allow_events_async">$term-&gt;allow_events_async</a></strong><br />
1068     </dt>
1069     <dd>
1070     Calls XAllowEvents with AsyncBoth for the most recent grab.
1071     </dd>
1072     <p></p>
1073     <dt><strong><a name="item_allow_events_sync">$term-&gt;allow_events_sync</a></strong><br />
1074     </dt>
1075     <dd>
1076     Calls XAllowEvents with SyncBoth for the most recent grab.
1077     </dd>
1078     <p></p>
1079     <dt><strong><a name="item_allow_events_replay">$term-&gt;allow_events_replay</a></strong><br />
1080     </dt>
1081     <dd>
1082     Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most
1083     recent grab.
1084     </dd>
1085     <p></p>
1086     <dt><strong><a name="item_ungrab">$term-&gt;ungrab</a></strong><br />
1087     </dt>
1088     <dd>
1089     Calls XUngrab for the most recent grab. Is called automatically on
1090     evaluation errors, as it is better to lose the grab in the error case as
1091     the session.
1092     </dd>
1093 root 1.6 <p></p></dl>
1094     <p>
1095     </p>
1096 root 1.15 <h2><a name="the_urxvt__popup_class">The <code>urxvt::popup</code> Class</a></h2>
1097     <p>
1098     </p>
1099 root 1.1 <h2><a name="the_urxvt__timer_class">The <code>urxvt::timer</code> Class</a></h2>
1100     <p>This class implements timer watchers/events. Time is represented as a
1101     fractional number of seconds since the epoch. Example:</p>
1102     <pre>
1103 root 1.8 $term-&gt;{overlay} = $term-&gt;overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
1104 root 1.1 $term-&gt;{timer} = urxvt::timer
1105     -&gt;new
1106 root 1.8 -&gt;interval (1)
1107 root 1.1 -&gt;cb (sub {
1108 root 1.8 $term-&gt;{overlay}-&gt;set (0, 0,
1109     sprintf &quot;%2d:%02d:%02d&quot;, (localtime urxvt::NOW)[2,1,0]);
1110 root 1.1 });</pre>
1111     <dl>
1112     <dt><strong><a name="item__24timer__3d_new_urxvt_3a_3atimer">$timer = new urxvt::timer</a></strong><br />
1113     </dt>
1114     <dd>
1115 root 1.8 Create a new timer object in started state. It is scheduled to fire
1116     immediately.
1117 root 1.1 </dd>
1118     <p></p>
1119     <dt><strong><a name="item_cb">$timer = $timer-&gt;cb (sub { my ($timer) = @_; ... })</a></strong><br />
1120     </dt>
1121     <dd>
1122     Set the callback to be called when the timer triggers.
1123     </dd>
1124     <p></p>
1125     <dt><strong><a name="item_at">$tstamp = $timer-&gt;at</a></strong><br />
1126     </dt>
1127     <dd>
1128     Return the time this watcher will fire next.
1129     </dd>
1130     <p></p>
1131 root 1.8 <dt><strong>$timer = $timer-&gt;set ($tstamp)</strong><br />
1132 root 1.1 </dt>
1133     <dd>
1134     Set the time the event is generated to $tstamp.
1135     </dd>
1136     <p></p>
1137 root 1.8 <dt><strong><a name="item_interval">$timer = $timer-&gt;interval ($interval)</a></strong><br />
1138     </dt>
1139     <dd>
1140     Normally (and when <code>$interval</code> is <code>0</code>), the timer will automatically
1141     stop after it has fired once. If <code>$interval</code> is non-zero, then the timer
1142     is automatically rescheduled at the given intervals.
1143     </dd>
1144     <p></p>
1145 root 1.1 <dt><strong><a name="item_start">$timer = $timer-&gt;start</a></strong><br />
1146     </dt>
1147     <dd>
1148     Start the timer.
1149     </dd>
1150     <p></p>
1151     <dt><strong>$timer = $timer-&gt;start ($tstamp)</strong><br />
1152     </dt>
1153     <dd>
1154     Set the event trigger time to <code>$tstamp</code> and start the timer.
1155     </dd>
1156     <p></p>
1157     <dt><strong><a name="item_stop">$timer = $timer-&gt;stop</a></strong><br />
1158     </dt>
1159     <dd>
1160     Stop the timer.
1161     </dd>
1162     <p></p></dl>
1163     <p>
1164     </p>
1165     <h2><a name="the_urxvt__iow_class">The <code>urxvt::iow</code> Class</a></h2>
1166     <p>This class implements io watchers/events. Example:</p>
1167     <pre>
1168     $term-&gt;{socket} = ...
1169     $term-&gt;{iow} = urxvt::iow
1170     -&gt;new
1171     -&gt;fd (fileno $term-&gt;{socket})
1172 root 1.19 -&gt;events (urxvt::EVENT_READ)
1173 root 1.1 -&gt;start
1174     -&gt;cb (sub {
1175     my ($iow, $revents) = @_;
1176     # $revents must be 1 here, no need to check
1177     sysread $term-&gt;{socket}, my $buf, 8192
1178     or end-of-file;
1179     });</pre>
1180     <dl>
1181     <dt><strong><a name="item__24iow__3d_new_urxvt_3a_3aiow">$iow = new urxvt::iow</a></strong><br />
1182     </dt>
1183     <dd>
1184     Create a new io watcher object in stopped state.
1185     </dd>
1186     <p></p>
1187     <dt><strong>$iow = $iow-&gt;cb (sub { my ($iow, $reventmask) = @_; ... })</strong><br />
1188     </dt>
1189     <dd>
1190     Set the callback to be called when io events are triggered. <code>$reventmask</code>
1191     is a bitset as described in the <a href="#item_events"><code>events</code></a> method.
1192     </dd>
1193     <p></p>
1194     <dt><strong><a name="item_fd">$iow = $iow-&gt;fd ($fd)</a></strong><br />
1195     </dt>
1196     <dd>
1197     Set the filedescriptor (not handle) to watch.
1198     </dd>
1199     <p></p>
1200     <dt><strong><a name="item_events">$iow = $iow-&gt;events ($eventmask)</a></strong><br />
1201     </dt>
1202     <dd>
1203 root 1.19 Set the event mask to watch. The only allowed values are
1204     <code>urxvt::EVENT_READ</code> and <code>urxvt::EVENT_WRITE</code>, which might be ORed
1205     together, or <code>urxvt::EVENT_NONE</code>.
1206 root 1.1 </dd>
1207     <p></p>
1208     <dt><strong>$iow = $iow-&gt;start</strong><br />
1209     </dt>
1210     <dd>
1211     Start watching for requested events on the given handle.
1212     </dd>
1213     <p></p>
1214     <dt><strong>$iow = $iow-&gt;stop</strong><br />
1215     </dt>
1216     <dd>
1217     Stop watching for events on the given filehandle.
1218     </dd>
1219     <p></p></dl>
1220     <p>
1221     </p>
1222     <hr />
1223 root 1.2 <h1><a name="environment">ENVIRONMENT</a></h1>
1224     <p>
1225     </p>
1226     <h2><a name="urxvt_perl_verbosity">URXVT_PERL_VERBOSITY</a></h2>
1227     <p>This variable controls the verbosity level of the perl extension. Higher
1228     numbers indicate more verbose output.</p>
1229 root 1.10 <dl>
1230 root 1.17 <dt><strong><a name="item__3d_3d_0__2d_fatal_messages">== 0 - fatal messages</a></strong><br />
1231 root 1.10 </dt>
1232 root 1.17 <dt><strong><a name="item__3e_3d_3__2d_script_loading_and_management">&gt;= 3 - script loading and management</a></strong><br />
1233 root 1.10 </dt>
1234 root 1.17 <dt><strong><a name="item__3e_3d10__2d_all_events_received">&gt;=10 - all events received</a></strong><br />
1235 root 1.10 </dt>
1236     </dl>
1237 root 1.2 <p>
1238     </p>
1239     <hr />
1240 root 1.1 <h1><a name="author">AUTHOR</a></h1>
1241     <pre>
1242     Marc Lehmann &lt;pcg@goof.com&gt;
1243     <a href="http://software.schmorp.de/pkg/rxvt-unicode">http://software.schmorp.de/pkg/rxvt-unicode</a></pre>
1244    
1245     </body>
1246    
1247     </html>