ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/cvsroot/rxvt-unicode/doc/rxvtperl.3.html
Revision: 1.34
Committed: Fri Jan 20 16:02:20 2006 UTC (20 years, 8 months ago) by root
Content type: text/html
Branch: MAIN
Changes since 1.33: +142 -12 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 root 1.30 <title>rxvtperl - rxvt-unicode's embedded perl interpreter</title>
5 root 1.1 <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 root 1.34 <li><a href="#the_urxvt__iw_class">The <code>urxvt::iw</code> Class</a></li>
34     <li><a href="#the_urxvt__pw_class">The <code>urxvt::pw</code> Class</a></li>
35 root 1.1 </ul>
36    
37 root 1.2 <li><a href="#environment">ENVIRONMENT</a></li>
38     <ul>
39    
40     <li><a href="#urxvt_perl_verbosity">URXVT_PERL_VERBOSITY</a></li>
41     </ul>
42    
43 root 1.1 <li><a href="#author">AUTHOR</a></li>
44     </ul>
45     <!-- INDEX END -->
46    
47     <hr />
48     <p>
49     </p>
50 root 1.7 <hr />
51 root 1.1 <h1><a name="name">NAME</a></h1>
52 root 1.30 <p>rxvtperl - rxvt-unicode's embedded perl interpreter</p>
53 root 1.1 <p>
54     </p>
55     <hr />
56     <h1><a name="synopsis">SYNOPSIS</a></h1>
57 root 1.5 <pre>
58     # create a file grab_test in $HOME:</pre>
59 root 1.1 <pre>
60     sub on_sel_grab {
61     warn &quot;you selected &quot;, $_[0]-&gt;selection;
62     ()
63     }</pre>
64     <pre>
65 root 1.30 # start a rxvt using it:</pre>
66 root 1.5 <pre>
67 root 1.30 rxvt --perl-lib $HOME -pe grab_test</pre>
68 root 1.1 <p>
69     </p>
70     <hr />
71     <h1><a name="description">DESCRIPTION</a></h1>
72 root 1.15 <p>Everytime a terminal object gets created, extension scripts specified via
73     the <code>perl</code> resource are loaded and associated with it.</p>
74 root 1.5 <p>Scripts are compiled in a 'use strict' and 'use utf8' environment, and
75     thus must be encoded as UTF-8.</p>
76 root 1.30 <p>Each script will only ever be loaded once, even in rxvtd, where
77 root 1.7 scripts will be shared (but not enabled) for all terminals.</p>
78 root 1.3 <p>
79     </p>
80 root 1.20 <hr />
81     <h1><a name="prepackaged_extensions">PREPACKAGED EXTENSIONS</a></h1>
82     <p>This section describes the extensions delivered with this release. You can
83 root 1.30 find them in <em>/opt/rxvt/lib/urxvt/perl/</em>.</p>
84 root 1.6 <p>You can activate them like this:</p>
85     <pre>
86 root 1.30 rxvt -pe &lt;extensionname&gt;</pre>
87 root 1.34 <p>Or by adding them to the resource for extensions loaded by default:</p>
88     <pre>
89     URxvt.perl-ext-common: default,automove-background,selection-autotransform</pre>
90 root 1.6 <dl>
91 root 1.16 <dt><strong><a name="item_selection">selection (enabled by default)</a></strong><br />
92 root 1.6 </dt>
93     <dd>
94 root 1.20 (More) intelligent selection. This extension tries to be more intelligent
95 root 1.25 when the user extends selections (double-click and further clicks). Right
96     now, it tries to select words, urls and complete shell-quoted
97     arguments, which is very convenient, too, if your <em>ls</em> supports
98     <code>--quoting-style=shell</code>.
99     </dd>
100     <dd>
101     <p>A double-click usually selects the word under the cursor, further clicks
102     will enlarge the selection.</p>
103 root 1.9 </dd>
104     <dd>
105 root 1.26 <p>The selection works by trying to match a number of regexes and displaying
106     them in increasing order of length. You can add your own regexes by
107     specifying resources of the form:</p>
108     </dd>
109     <dd>
110     <pre>
111     URxvt.selection.pattern-0: perl-regex
112     URxvt.selection.pattern-1: perl-regex
113     ...</pre>
114     </dd>
115     <dd>
116     <p>The index number (0, 1...) must not have any holes, and each regex must
117     contain at least one pair of capturing parentheses, which will be used for
118     the match. For example, the followign adds a regex that matches everything
119     between two vertical bars:</p>
120     </dd>
121     <dd>
122     <pre>
123     URxvt.selection.pattern-0: \\|([^|]+)\\|</pre>
124     </dd>
125     <dd>
126     <p>You can look at the source of the selection extension to see more
127     interesting uses, such as parsing a line from beginning to end.</p>
128     </dd>
129     <dd>
130 root 1.31 <p>This extension also offers following bindable keyboard commands:</p>
131 root 1.6 </dd>
132     <dl>
133     <dt><strong><a name="item_rot13">rot13</a></strong><br />
134     </dt>
135     <dd>
136     Rot-13 the selection when activated. Used via keyboard trigger:
137     </dd>
138     <dd>
139     <pre>
140     URxvt.keysym.C-M-r: perl:selection:rot13</pre>
141     </dd>
142     <p></p></dl>
143 root 1.16 <dt><strong><a name="item_popup">option-popup (enabled by default)</a></strong><br />
144     </dt>
145     <dd>
146 root 1.17 Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at
147 root 1.16 runtime.
148     </dd>
149     <p></p>
150 root 1.17 <dt><strong>selection-popup (enabled by default)</strong><br />
151     </dt>
152     <dd>
153     Binds a popup menu to Ctrl-Button3 that lets you convert the selection
154 root 1.20 text into various other formats/action (such as uri unescaping, perl
155     evalution, web-browser starting etc.), depending on content.
156 root 1.17 </dd>
157 root 1.33 <dd>
158     <p>Other extensions can extend this popup menu by pushing a code reference
159     onto <code>@{ $term-</code>{selection_popup_hook} }&gt;, that is called whenever the
160     popup is displayed.</p>
161     </dd>
162     <dd>
163     <p>It's sole argument is the popup menu, which can be modified. The selection
164     is in <code>$_</code>, which can be used to decide wether to add something or not.
165     It should either return nothing or a string and a code reference. The
166     string will be used as button text and the code reference will be called
167     when the button gets activated and should transform <code>$_</code>.</p>
168     </dd>
169     <dd>
170     <p>The following will add an entry <code>a to b</code> that transforms all <code>a</code>s in
171     the selection to <code>b</code>s, but only if the selection currently contains any
172     <code>a</code>s:</p>
173     </dd>
174     <dd>
175     <pre>
176     push @{ $self-&gt;{term}{selection_popup_hook} }, sub {
177     /a/ ? (&quot;a to be&quot; =&gt; sub { s/a/b/g }
178     : ()
179     };</pre>
180     </dd>
181 root 1.17 <p></p>
182 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 />
183     </dt>
184     <dd>
185     Adds regex search functionality to the scrollback buffer, triggered
186 root 1.25 by a hotkey (default: <code>M-s</code>). While in search mode, normal terminal
187     input/output is suspended and a regex is displayed at the bottom of the
188     screen.
189 root 1.19 </dd>
190     <dd>
191 root 1.25 <p>Inputting characters appends them to the regex and continues incremental
192     search. <code>BackSpace</code> removes a character from the regex, <code>Up</code> and <code>Down</code>
193     search upwards/downwards in the scrollback buffer, <code>End</code> jumps to the
194     bottom. <code>Escape</code> leaves search mode and returns to the point where search
195     was started, while <code>Enter</code> or <code>Return</code> stay at the current position and
196     additionally stores the first match in the current line into the primary
197     selection.</p>
198 root 1.19 </dd>
199     <p></p>
200 root 1.26 <dt><strong><a name="item_selection_2dautotransform">selection-autotransform</a></strong><br />
201 root 1.6 </dt>
202     <dd>
203 root 1.26 This selection allows you to do automatic transforms on a selection
204     whenever a selection is made.
205     </dd>
206     <dd>
207     <p>It works by specifying perl snippets (most useful is a single <code>s///</code>
208     operator) that modify <code>$_</code> as resources:</p>
209     </dd>
210     <dd>
211     <pre>
212     URxvt.selection-autotransform.0: transform
213     URxvt.selection-autotransform.1: transform
214     ...</pre>
215     </dd>
216     <dd>
217     <p>For example, the following will transform selections of the form
218     <code>filename:number</code>, often seen in compiler messages, into <code>vi +$filename
219     $word</code>:</p>
220     </dd>
221     <dd>
222     <pre>
223 root 1.29 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/</pre>
224 root 1.26 </dd>
225     <dd>
226     <p>And this example matches the same,but replaces it with vi-commands you can
227     paste directly into your (vi :) editor:</p>
228     </dd>
229     <dd>
230     <pre>
231 root 1.33 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/</pre>
232 root 1.6 </dd>
233 root 1.27 <dd>
234     <p>Of course, this can be modified to suit your needs and your editor :)</p>
235     </dd>
236 root 1.28 <dd>
237     <p>To expand the example above to typical perl error messages (``XXX at
238     FILENAME line YYY.''), you need a slightly more elaborate solution:</p>
239     </dd>
240     <dd>
241     <pre>
242 root 1.33 URxvt.selection.pattern-0: ( at .*? line \\d+[,.])
243     URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/</pre>
244 root 1.28 </dd>
245     <dd>
246     <p>The first line tells the selection code to treat the unchanging part of
247     every error message as a selection pattern, and the second line transforms
248     the message into vi commands to load the file.</p>
249     </dd>
250 root 1.6 <p></p>
251 root 1.34 <dt><strong><a name="item_tabbed">tabbed</a></strong><br />
252     </dt>
253     <dd>
254     This transforms the terminal into a tabbar with additional terminals, that
255     is, it implements what is commonly refered to as ``tabbed terminal''. The topmost line
256     displays a ``[NEW]'' button, which, when clicked, will add a new tab, followed by one
257     button per tab.
258     </dd>
259     <dd>
260     <p>Clicking a button will activate that tab. Pressing Shift-Left and
261     Shift-Right will switch to the tab left or right of the current one.</p>
262     </dd>
263     <p></p>
264 root 1.14 <dt><strong><a name="item_mark_2durls">mark-urls</a></strong><br />
265     </dt>
266     <dd>
267 root 1.24 Uses per-line display filtering (<code>on_line_update</code>) to underline urls and
268 root 1.25 make them clickable. When middle-clicked, the program specified in the
269     resource <code>urlLauncher</code> (default <code>x-www-browser</code>) will be started with
270     the URL as first argument.
271 root 1.14 </dd>
272     <p></p>
273 root 1.33 <dt><strong><a name="item_automove_2dbackground">automove-background</a></strong><br />
274     </dt>
275     <dd>
276     This is basically a one-line extension that dynamically changes the background pixmap offset
277     to the window position, in effect creating the same effect as pseudo transparency with
278     a custom pixmap. No scaling is supported in this mode. Exmaple:
279     </dd>
280     <dd>
281     <pre>
282     rxvt -pixmap background.xpm -pe automove-background</pre>
283     </dd>
284     <p></p>
285 root 1.14 <dt><strong><a name="item_block_2dgraphics_2dto_2dascii">block-graphics-to-ascii</a></strong><br />
286     </dt>
287     <dd>
288     A not very useful example of filtering all text output to the terminal,
289     by replacing all line-drawing characters (U+2500 .. U+259F) by a
290     similar-looking ascii character.
291     </dd>
292     <p></p>
293 root 1.26 <dt><strong><a name="item_digital_2dclock">digital-clock</a></strong><br />
294     </dt>
295     <dd>
296     Displays a digital clock using the built-in overlay.
297     </dd>
298     <p></p>
299 root 1.8 <dt><strong><a name="item_example_2drefresh_2dhooks">example-refresh-hooks</a></strong><br />
300 root 1.6 </dt>
301     <dd>
302 root 1.8 Displays a very simple digital clock in the upper right corner of the
303     window. Illustrates overwriting the refresh callbacks to create your own
304     overlays or changes.
305 root 1.6 </dd>
306 root 1.32 <p></p>
307     <dt><strong><a name="item_selection_2dpastebin">selection-pastebin</a></strong><br />
308     </dt>
309     <dd>
310     This is a little rarely useful extension that Uploads the selection as
311     textfile to a remote site (or does other things). (The implementation is
312     not currently secure for use in a multiuser environment as it writes to
313     <em>/tmp</em> directly.).
314     </dd>
315     <dd>
316     <p>It listens to the <code>selection-pastebin:remote-pastebin</code> keyboard command,
317     i.e.</p>
318     </dd>
319     <dd>
320     <pre>
321     URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin</pre>
322     </dd>
323     <dd>
324     <p>Pressing this combination runs a command with <code>%</code> replaced by the name of
325     the textfile. This command can be set via a resource:</p>
326     </dd>
327     <dd>
328     <pre>
329     URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.</pre>
330     </dd>
331     <dd>
332     <p>And the default is likely not useful to anybody but the few people around
333     here :)</p>
334     </dd>
335     <dd>
336     <p>The name of the textfile is the hex encoded md5 sum of the selection, so
337     the same content should lead to the same filename.</p>
338     </dd>
339     <dd>
340     <p>After a successful upload the selection will be replaced by the text given
341     in the <code>selection-pastebin-url</code> resource (again, the % is the placeholder
342     for the filename):</p>
343     </dd>
344     <dd>
345     <pre>
346     URxvt.selection-pastebin.url: <a href="http://www.ta-sa.org/files/txt/%">http://www.ta-sa.org/files/txt/%</a></pre>
347     </dd>
348 root 1.6 <p></p></dl>
349     <p>
350     </p>
351 root 1.20 <hr />
352     <h1><a name="api_documentation">API DOCUMENTATION</a></h1>
353     <p>
354     </p>
355 root 1.3 <h2><a name="general_api_considerations">General API Considerations</a></h2>
356     <p>All objects (such as terminals, time watchers etc.) are typical
357     reference-to-hash objects. The hash can be used to store anything you
358     like. All members starting with an underscore (such as <code>_ptr</code> or
359 root 1.9 <code>_hook</code>) are reserved for internal uses and <strong>MUST NOT</strong> be accessed or
360 root 1.3 modified).</p>
361     <p>When objects are destroyed on the C++ side, the perl object hashes are
362     emptied, so its best to store related objects such as time watchers and
363     the like inside the terminal object so they get destroyed as soon as the
364     terminal is destroyed.</p>
365 root 1.14 <p>Argument names also often indicate the type of a parameter. Here are some
366     hints on what they mean:</p>
367     <dl>
368     <dt><strong><a name="item__24text">$text</a></strong><br />
369     </dt>
370     <dd>
371     Rxvt-unicodes special way of encoding text, where one ``unicode'' character
372 root 1.23 always represents one screen cell. See <a href="#item_row_t">ROW_t</a> for a discussion of this format.
373 root 1.14 </dd>
374     <p></p>
375     <dt><strong><a name="item__24string">$string</a></strong><br />
376     </dt>
377     <dd>
378     A perl text string, with an emphasis on <em>text</em>. It can store all unicode
379     characters and is to be distinguished with text encoded in a specific
380     encoding (often locale-specific) and binary data.
381     </dd>
382     <p></p>
383     <dt><strong><a name="item__24octets">$octets</a></strong><br />
384     </dt>
385     <dd>
386     Either binary data or - more common - a text string encoded in a
387     locale-specific way.
388     </dd>
389     <p></p></dl>
390 root 1.1 <p>
391     </p>
392 root 1.19 <h2><a name="extension_objects">Extension Objects</a></h2>
393     <p>Very perl extension is a perl class. A separate perl object is created
394     for each terminal and each extension and passed as the first parameter to
395     hooks. So extensions can use their <code>$self</code> object without having to think
396     about other extensions, with the exception of methods and members that
397     begin with an underscore character <code>_</code>: these are reserved for internal
398     use.</p>
399     <p>Although it isn't a <code>urxvt::term</code> object, you can call all methods of the
400     <code>urxvt::term</code> class on this object.</p>
401     <p>It has the following methods and data members:</p>
402     <dl>
403     <dt><strong><a name="item__24urxvt_term__3d__24self_2d_3e_7bterm_7d">$urxvt_term = $self-&gt;{term}</a></strong><br />
404     </dt>
405     <dd>
406     Returns the <code>urxvt::term</code> object associated with this instance of the
407     extension. This member <em>must not</em> be changed in any way.
408     </dd>
409     <p></p>
410     <dt><strong><a name="item_enable">$self-&gt;enable ($hook_name =&gt; $cb, [$hook_name =&gt; $cb..])</a></strong><br />
411     </dt>
412     <dd>
413     Dynamically enable the given hooks (named without the <code>on_</code> prefix) for
414     this extension, replacing any previous hook. This is useful when you want
415     to overwrite time-critical hooks only temporarily.
416     </dd>
417     <p></p>
418     <dt><strong><a name="item_disable">$self-&gt;disable ($hook_name[, $hook_name..])</a></strong><br />
419     </dt>
420     <dd>
421     Dynamically disable the given hooks.
422     </dd>
423     <p></p></dl>
424     <p>
425     </p>
426 root 1.1 <h2><a name="hooks">Hooks</a></h2>
427 root 1.14 <p>The following subroutines can be declared in extension files, and will be
428 root 1.9 called whenever the relevant event happens.</p>
429 root 1.19 <p>The first argument passed to them is an extension oject as described in
430     the in the <code>Extension Objects</code> section.</p>
431 root 1.34 <p><strong>All</strong> of these hooks must return a boolean value. If any of the called
432     hooks returns true, then the event counts as being <em>consumed</em>, and the
433     relevant action might not be carried out by the C++ code.</p>
434 root 1.19 <p><em>When in doubt, return a false value (preferably <code>()</code>). </em>&gt;</p>
435 root 1.1 <dl>
436     <dt><strong><a name="item_on_init__24term">on_init $term</a></strong><br />
437     </dt>
438     <dd>
439     Called after a new terminal object has been initialized, but before
440 root 1.14 windows are created or the command gets run. Most methods are unsafe to
441     call or deliver senseless data, as terminal size and other characteristics
442 root 1.34 have not yet been determined. You can safely query and change resources
443     and options, though. For many purposes the <code>on_start</code> hook is a better
444     place.
445     </dd>
446     <p></p>
447     <dt><strong><a name="item_on_start__24term">on_start $term</a></strong><br />
448     </dt>
449     <dd>
450     Called at the very end of initialisation of a new terminal, just before
451     trying to map (display) the toplevel and returning to the mainloop.
452     </dd>
453     <p></p>
454     <dt><strong><a name="item_on_destroy__24term">on_destroy $term</a></strong><br />
455     </dt>
456     <dd>
457     Called whenever something tries to destroy terminal, before doing anything
458     yet. If this hook returns true, then destruction is skipped, but this is
459     rarely a good idea.
460 root 1.1 </dd>
461     <p></p>
462     <dt><strong><a name="item_on_reset__24term">on_reset $term</a></strong><br />
463     </dt>
464     <dd>
465     Called after the screen is ``reset'' for any reason, such as resizing or
466     control sequences. Here is where you can react on changes to size-related
467     variables.
468     </dd>
469     <p></p>
470 root 1.33 <dt><strong><a name="item_on_child_start__24term_2c__24pid">on_child_start $term, $pid</a></strong><br />
471     </dt>
472     <dd>
473     Called just after the child process has been <code>fork</code>ed.
474     </dd>
475     <p></p>
476     <dt><strong><a name="item_on_child_exit__24term_2c__24status">on_child_exit $term, $status</a></strong><br />
477     </dt>
478     <dd>
479     Called just after the child process has exited. <code>$status</code> is the status
480     from <code>waitpid</code>.
481     </dd>
482     <p></p>
483 root 1.1 <dt><strong><a name="item_on_sel_make__24term_2c__24eventtime">on_sel_make $term, $eventtime</a></strong><br />
484     </dt>
485     <dd>
486     Called whenever a selection has been made by the user, but before the
487     selection text is copied, so changes to the beginning, end or type of the
488     selection will be honored.
489     </dd>
490     <dd>
491     <p>Returning a true value aborts selection making by urxvt, in which case you
492     have to make a selection yourself by calling <a href="#item_selection_grab"><code>$term-&gt;selection_grab</code></a>.</p>
493     </dd>
494     <p></p>
495     <dt><strong><a name="item_on_sel_grab__24term_2c__24eventtime">on_sel_grab $term, $eventtime</a></strong><br />
496     </dt>
497     <dd>
498     Called whenever a selection has been copied, but before the selection is
499     requested from the server. The selection text can be queried and changed
500     by calling <a href="#item_selection"><code>$term-&gt;selection</code></a>.
501     </dd>
502     <dd>
503     <p>Returning a true value aborts selection grabbing. It will still be hilighted.</p>
504     </dd>
505     <p></p>
506 root 1.9 <dt><strong><a name="item_on_sel_extend__24term">on_sel_extend $term</a></strong><br />
507     </dt>
508     <dd>
509     Called whenever the user tries to extend the selection (e.g. with a double
510     click) and is either supposed to return false (normal operation), or
511     should extend the selection itelf and return true to suppress the built-in
512 root 1.25 processing. This can happen multiple times, as long as the callback
513     returns true, it will be called on every further click by the user and is
514     supposed to enlarge the selection more and more, if possible.
515 root 1.9 </dd>
516     <dd>
517     <p>See the <em>selection</em> example extension.</p>
518     </dd>
519     <p></p>
520 root 1.1 <dt><strong><a name="item_on_view_change__24term_2c__24offset">on_view_change $term, $offset</a></strong><br />
521     </dt>
522     <dd>
523     Called whenever the view offset changes, i..e the user or program
524     scrolls. Offset <code>0</code> means display the normal terminal, positive values
525     show this many lines of scrollback.
526     </dd>
527     <p></p>
528     <dt><strong><a name="item_on_scroll_back__24term_2c__24lines_2c__24saved">on_scroll_back $term, $lines, $saved</a></strong><br />
529     </dt>
530     <dd>
531     Called whenever lines scroll out of the terminal area into the scrollback
532     buffer. <code>$lines</code> is the number of lines scrolled out and may be larger
533     than the scroll back buffer or the terminal.
534     </dd>
535     <dd>
536     <p>It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
537     $nrow - 1) represent the lines to be scrolled out). <code>$saved</code> is the total
538     number of lines that will be in the scrollback buffer.</p>
539     </dd>
540     <p></p>
541 root 1.11 <dt><strong><a name="item_on_osc_seq__24term_2c__24string">on_osc_seq $term, $string</a></strong><br />
542     </dt>
543     <dd>
544     Called whenever the <strong>ESC ] 777 ; string ST</strong> command sequence (OSC =
545     operating system command) is processed. Cursor position and other state
546     information is up-to-date when this happens. For interoperability, the
547     string should start with the extension name and a colon, to distinguish
548     it from commands for other extensions, and this might be enforced in the
549     future.
550     </dd>
551     <dd>
552     <p>Be careful not ever to trust (in a security sense) the data you receive,
553     as its source can not easily be controleld (e-mail content, messages from
554     other users on the same system etc.).</p>
555     </dd>
556     <p></p>
557 root 1.14 <dt><strong><a name="item_on_add_lines__24term_2c__24string">on_add_lines $term, $string</a></strong><br />
558     </dt>
559     <dd>
560     Called whenever text is about to be output, with the text as argument. You
561     can filter/change and output the text yourself by returning a true value
562     and calling <a href="#item_scr_add_lines"><code>$term-&gt;scr_add_lines</code></a> yourself. Please note that this
563     might be very slow, however, as your hook is called for <strong>all</strong> text being
564     output.
565     </dd>
566     <p></p>
567 root 1.19 <dt><strong><a name="item_on_tt_write__24term_2c__24octets">on_tt_write $term, $octets</a></strong><br />
568     </dt>
569     <dd>
570     Called whenever some data is written to the tty/pty and can be used to
571     suppress or filter tty input.
572     </dd>
573     <p></p>
574 root 1.14 <dt><strong><a name="item_on_line_update__24term_2c__24row">on_line_update $term, $row</a></strong><br />
575     </dt>
576     <dd>
577     Called whenever a line was updated or changed. Can be used to filter
578     screen output (e.g. underline urls or other useless stuff). Only lines
579     that are being shown will be filtered, and, due to performance reasons,
580     not always immediately.
581     </dd>
582     <dd>
583     <p>The row number is always the topmost row of the line if the line spans
584     multiple rows.</p>
585     </dd>
586     <dd>
587     <p>Please note that, if you change the line, then the hook might get called
588     later with the already-modified line (e.g. if unrelated parts change), so
589     you cannot just toggle rendition bits, but only set them.</p>
590     </dd>
591     <p></p>
592 root 1.1 <dt><strong><a name="item_on_refresh_begin__24term">on_refresh_begin $term</a></strong><br />
593     </dt>
594     <dd>
595     Called just before the screen gets redrawn. Can be used for overlay
596     or similar effects by modify terminal contents in refresh_begin, and
597     restoring them in refresh_end. The built-in overlay and selection display
598     code is run after this hook, and takes precedence.
599     </dd>
600     <p></p>
601     <dt><strong><a name="item_on_refresh_end__24term">on_refresh_end $term</a></strong><br />
602     </dt>
603     <dd>
604     Called just after the screen gets redrawn. See <code>on_refresh_begin</code>.
605     </dd>
606 root 1.5 <p></p>
607     <dt><strong><a name="item_on_keyboard_command__24term_2c__24string">on_keyboard_command $term, $string</a></strong><br />
608     </dt>
609     <dd>
610     Called whenever the user presses a key combination that has a
611     <code>perl:string</code> action bound to it (see description of the <strong>keysym</strong>
612 root 1.30 resource in the <code>rxvt(1)</code> manpage).
613 root 1.29 </dd>
614     <p></p>
615     <dt><strong><a name="item_on_x_event__24term_2c__24event">on_x_event $term, $event</a></strong><br />
616     </dt>
617     <dd>
618     Called on every X event received on the vt window (and possibly other
619     windows). Should only be used as a last resort. Most event structure
620     members are not passed.
621 root 1.5 </dd>
622 root 1.14 <p></p>
623 root 1.15 <dt><strong><a name="item_on_focus_in__24term">on_focus_in $term</a></strong><br />
624     </dt>
625     <dd>
626     Called whenever the window gets the keyboard focus, before rxvt-unicode
627     does focus in processing.
628     </dd>
629     <p></p>
630     <dt><strong><a name="item_on_focus_out__24term">on_focus_out $term</a></strong><br />
631     </dt>
632     <dd>
633     Called wheneever the window loses keyboard focus, before rxvt-unicode does
634     focus out processing.
635     </dd>
636     <p></p>
637 root 1.33 <dt><strong><a name="item_on_configure_notify__24term_2c__24event">on_configure_notify $term, $event</a></strong><br />
638     </dt>
639 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 />
640 root 1.14 </dt>
641 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 />
642 root 1.14 </dt>
643     <dt><strong><a name="item_on_button_press__24term_2c__24event">on_button_press $term, $event</a></strong><br />
644     </dt>
645     <dt><strong><a name="item_on_button_release__24term_2c__24event">on_button_release $term, $event</a></strong><br />
646     </dt>
647     <dt><strong><a name="item_on_motion_notify__24term_2c__24event">on_motion_notify $term, $event</a></strong><br />
648     </dt>
649 root 1.15 <dt><strong><a name="item_on_map_notify__24term_2c__24event">on_map_notify $term, $event</a></strong><br />
650     </dt>
651     <dt><strong><a name="item_on_unmap_notify__24term_2c__24event">on_unmap_notify $term, $event</a></strong><br />
652     </dt>
653 root 1.14 <dd>
654     Called whenever the corresponding X event is received for the terminal If
655     the hook returns true, then the even will be ignored by rxvt-unicode.
656     </dd>
657     <dd>
658     <p>The event is a hash with most values as named by Xlib (see the XEvent
659     manpage), with the additional members <code>row</code> and <code>col</code>, which are the row
660     and column under the mouse cursor.</p>
661     </dd>
662     <dd>
663     <p><code>on_key_press</code> additionally receives the string rxvt-unicode would
664     output, if any, in locale-specific encoding.</p>
665     </dd>
666     <dd>
667     <p>subwindow.</p>
668     </dd>
669 root 1.34 <p></p>
670     <dt><strong><a name="item_on_client_message__24term_2c__24event">on_client_message $term, $event</a></strong><br />
671     </dt>
672     <dt><strong><a name="item_on_wm_protocols__24term_2c__24event">on_wm_protocols $term, $event</a></strong><br />
673     </dt>
674     <dt><strong><a name="item_on_wm_delete_window__24term_2c__24event">on_wm_delete_window $term, $event</a></strong><br />
675     </dt>
676     <dd>
677     Called when various types of ClientMessage events are received (all with
678     format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
679     </dd>
680 root 1.1 <p></p></dl>
681     <p>
682     </p>
683 root 1.9 <h2><a name="variables_in_the_urxvt_package">Variables in the <code>urxvt</code> Package</a></h2>
684     <dl>
685 root 1.21 <dt><strong><a name="item__24urxvt_3a_3alibdir">$urxvt::LIBDIR</a></strong><br />
686     </dt>
687     <dd>
688     The rxvt-unicode library directory, where, among other things, the perl
689     modules and scripts are stored.
690     </dd>
691     <p></p>
692     <dt><strong><a name="item__24urxvt_3a_3aresclass_2c__24urxvt_3a_3aresclass">$urxvt::RESCLASS, $urxvt::RESCLASS</a></strong><br />
693     </dt>
694     <dd>
695     The resource class and name rxvt-unicode uses to look up X resources.
696     </dd>
697     <p></p>
698     <dt><strong><a name="item__24urxvt_3a_3arxvtname">$urxvt::RXVTNAME</a></strong><br />
699     </dt>
700     <dd>
701     The basename of the installed binaries, usually <code>urxvt</code>.
702     </dd>
703     <p></p>
704 root 1.9 <dt><strong><a name="item__24urxvt_3a_3aterm">$urxvt::TERM</a></strong><br />
705     </dt>
706     <dd>
707 root 1.14 The current terminal. This variable stores the current <code>urxvt::term</code>
708     object, whenever a callback/hook is executing.
709 root 1.9 </dd>
710 root 1.34 <p></p>
711     <dt><strong><a name="item__40urxvt_3a_3aterm_init">@urxvt::TERM_INIT</a></strong><br />
712     </dt>
713     <dd>
714     All coderefs in this array will be called as methods of the next newly
715     created <code>urxvt::term</code> object (during the <code>on_init</code> phase). The array
716     gets cleared before the codereferences that were in it are being executed,
717     so coderefs can push themselves onto it again if they so desire.
718     </dd>
719     <dd>
720     <p>This complements to the perl-eval commandline option, but gets executed
721     first.</p>
722     </dd>
723     <p></p>
724     <dt><strong><a name="item__40urxvt_3a_3aterm_ext">@urxvt::TERM_EXT</a></strong><br />
725     </dt>
726     <dd>
727     Works similar to <code>@TERM_INIT</code>, but contains perl package/class names, which
728     get registered as normal extensions after calling the hooks in <code>@TERM_INIT</code>
729     but before other extensions. Gets cleared just like <code>@TERM_INIT</code>.
730     </dd>
731 root 1.23 <p></p></dl>
732 root 1.9 <p>
733     </p>
734 root 1.1 <h2><a name="functions_in_the_urxvt_package">Functions in the <code>urxvt</code> Package</a></h2>
735     <dl>
736     <dt><strong><a name="item_urxvt_3a_3afatal__24errormessage">urxvt::fatal $errormessage</a></strong><br />
737     </dt>
738     <dd>
739     Fatally aborts execution with the given error message. Avoid at all
740     costs! The only time this is acceptable is when the terminal process
741     starts up.
742     </dd>
743     <p></p>
744     <dt><strong><a name="item_urxvt_3a_3awarn__24string">urxvt::warn $string</a></strong><br />
745     </dt>
746     <dd>
747 root 1.3 Calls <code>rxvt_warn</code> with the given string which should not include a
748 root 1.1 newline. The module also overwrites the <code>warn</code> builtin with a function
749     that calls this function.
750     </dd>
751     <dd>
752     <p>Using this function has the advantage that its output ends up in the
753     correct place, e.g. on stderr of the connecting urxvtc client.</p>
754     </dd>
755 root 1.22 <dd>
756     <p>Messages have a size limit of 1023 bytes currently.</p>
757     </dd>
758 root 1.1 <p></p>
759     <dt><strong><a name="item__24time__3d_urxvt_3a_3anow">$time = urxvt::NOW</a></strong><br />
760     </dt>
761     <dd>
762     Returns the ``current time'' (as per the event loop).
763     </dd>
764 root 1.15 <p></p>
765     <dt><strong><a name="item_urxvt_3a_3acurrenttime">urxvt::CurrentTime</a></strong><br />
766     </dt>
767     <dt><strong><a name="item_urxvt_3a_3ashiftmask_2c_lockmask_2c_controlmask_2c">urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
768     Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
769     Button4Mask, Button5Mask, AnyModifier</a></strong><br />
770     </dt>
771 root 1.29 <dt><strong><a name="item_urxvt_3a_3anoeventmask_2c_keypressmask_2c_keyrelea">urxvt::NoEventMask, KeyPressMask, KeyReleaseMask,
772     ButtonPressMask, ButtonReleaseMask, EnterWindowMask, LeaveWindowMask,
773     PointerMotionMask, PointerMotionHintMask, Button1MotionMask, Button2MotionMask,
774     Button3MotionMask, Button4MotionMask, Button5MotionMask, ButtonMotionMask,
775     KeymapStateMask, ExposureMask, VisibilityChangeMask, StructureNotifyMask,
776     ResizeRedirectMask, SubstructureNotifyMask, SubstructureRedirectMask,
777     FocusChangeMask, PropertyChangeMask, ColormapChangeMask, OwnerGrabButtonMask</a></strong><br />
778     </dt>
779     <dt><strong><a name="item_urxvt_3a_3akeypress_2c_keyrelease_2c_buttonpress_2">urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify,
780     EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose,
781     GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify, DestroyNotify,
782     UnmapNotify, MapNotify, MapRequest, ReparentNotify, ConfigureNotify,
783     ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify,
784     CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest,
785     SelectionNotify, ColormapNotify, ClientMessage, MappingNotify</a></strong><br />
786     </dt>
787 root 1.15 <dd>
788 root 1.16 Various constants for use in X calls and event processing.
789 root 1.15 </dd>
790 root 1.1 <p></p></dl>
791     <p>
792     </p>
793 root 1.8 <h2><a name="rendition">RENDITION</a></h2>
794     <p>Rendition bitsets contain information about colour, font, font styles and
795     similar information for each screen cell.</p>
796     <p>The following ``macros'' deal with changes in rendition sets. You should
797     never just create a bitset, you should always modify an existing one,
798     as they contain important information required for correct operation of
799     rxvt-unicode.</p>
800     <dl>
801     <dt><strong><a name="item__24rend__3d_urxvt_3a_3adefault_rstyle">$rend = urxvt::DEFAULT_RSTYLE</a></strong><br />
802     </dt>
803     <dd>
804     Returns the default rendition, as used when the terminal is starting up or
805     being reset. Useful as a base to start when creating renditions.
806     </dd>
807     <p></p>
808     <dt><strong><a name="item__24rend__3d_urxvt_3a_3aoverlay_rstyle">$rend = urxvt::OVERLAY_RSTYLE</a></strong><br />
809     </dt>
810     <dd>
811     Return the rendition mask used for overlays by default.
812     </dd>
813     <p></p>
814     <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 />
815     </dt>
816     <dd>
817     Return the bit that enabled bold, italic, blink, reverse-video and
818     underline, respectively. To enable such a style, just logically OR it into
819     the bitset.
820     </dd>
821     <p></p>
822     <dt><strong><a name="item__24foreground__3d_urxvt_3a_3aget_basefg__24rend">$foreground = urxvt::GET_BASEFG $rend</a></strong><br />
823     </dt>
824     <dt><strong><a name="item__24background__3d_urxvt_3a_3aget_basebg__24rend">$background = urxvt::GET_BASEBG $rend</a></strong><br />
825     </dt>
826     <dd>
827     Return the foreground/background colour index, respectively.
828     </dd>
829     <p></p>
830 root 1.21 <dt><strong><a name="item__24rend__3d_urxvt_3a_3aset_fgcolor__24rend_2c__24n">$rend = urxvt::SET_FGCOLOR $rend, $new_colour</a></strong><br />
831 root 1.8 </dt>
832 root 1.21 <dt><strong><a name="item__24rend__3d_urxvt_3a_3aset_bgcolor__24rend_2c__24n">$rend = urxvt::SET_BGCOLOR $rend, $new_colour</a></strong><br />
833 root 1.8 </dt>
834     <dd>
835     Replace the foreground/background colour in the rendition mask with the
836     specified one.
837     </dd>
838     <p></p>
839 root 1.21 <dt><strong><a name="item__24value__3d_urxvt_3a_3aget_custom__24rend">$value = urxvt::GET_CUSTOM $rend</a></strong><br />
840 root 1.8 </dt>
841     <dd>
842     Return the ``custom'' value: Every rendition has 5 bits for use by
843     extensions. They can be set and changed as you like and are initially
844     zero.
845     </dd>
846     <p></p>
847 root 1.21 <dt><strong><a name="item__24rend__3d_urxvt_3a_3aset_custom__24rend_2c__24ne">$rend = urxvt::SET_CUSTOM $rend, $new_value</a></strong><br />
848 root 1.8 </dt>
849     <dd>
850     Change the custom value.
851     </dd>
852     <p></p></dl>
853     <p>
854     </p>
855 root 1.16 <h2><a name="the_urxvt__anyevent_class">The <code>urxvt::anyevent</code> Class</a></h2>
856     <p>The sole purpose of this class is to deliver an interface to the
857     <code>AnyEvent</code> module - any module using it will work inside urxvt without
858 root 1.21 further programming. The only exception is that you cannot wait on
859     condition variables, but non-blocking condvar use is ok. What this means
860     is that you cannot use blocking APIs, but the non-blocking variant should
861     work.</p>
862 root 1.16 <p>
863     </p>
864 root 1.1 <h2><a name="the_urxvt__term_class">The <code>urxvt::term</code> Class</a></h2>
865     <dl>
866 root 1.22 <dt><strong><a name="item__24term__3d_new_urxvt_3a_3aterm__24envhashref_2c__">$term = new urxvt::term $envhashref, $rxvtname, [arg...]</a></strong><br />
867     </dt>
868     <dd>
869     Creates a new terminal, very similar as if you had started it with system
870 root 1.23 <code>$rxvtname, arg...</code>. <code>$envhashref</code> must be a reference to a <code>%ENV</code>-like
871     hash which defines the environment of the new terminal.
872 root 1.22 </dd>
873     <dd>
874 root 1.23 <p>Croaks (and probably outputs an error message) if the new instance
875 root 1.22 couldn't be created. Returns <code>undef</code> if the new instance didn't
876     initialise perl, and the terminal object otherwise. The <code>init</code> and
877     <a href="#item_start"><code>start</code></a> hooks will be called during this call.</p>
878     </dd>
879     <p></p>
880 root 1.14 <dt><strong><a name="item_destroy">$term-&gt;destroy</a></strong><br />
881     </dt>
882     <dd>
883 root 1.21 Destroy the terminal object (close the window, free resources
884 root 1.30 etc.). Please note that rxvt will not exit as long as any event
885 root 1.21 watchers (timers, io watchers) are still active.
886 root 1.14 </dd>
887     <p></p>
888 root 1.33 <dt><strong><a name="item_exec_async">$term-&gt;exec_async ($cmd[, @args])</a></strong><br />
889     </dt>
890     <dd>
891     Works like the combination of the <code>fork</code>/<code>exec</code> builtins, which executes
892     (``starts'') programs in the background. This function takes care of setting
893     the user environment before exec'ing the command (e.g. <code>PATH</code>) and should
894     be preferred over explicit calls to <code>exec</code> or <code>system</code>.
895     </dd>
896     <dd>
897     <p>Returns the pid of the subprocess or <code>undef</code> on error.</p>
898     </dd>
899     <p></p>
900 root 1.15 <dt><strong><a name="item_option">$isset = $term-&gt;option ($optval[, $set])</a></strong><br />
901     </dt>
902     <dd>
903     Returns true if the option specified by <code>$optval</code> is enabled, and
904     optionally change it. All option values are stored by name in the hash
905     <code>%urxvt::OPTION</code>. Options not enabled in this binary are not in the hash.
906     </dd>
907     <dd>
908     <p>Here is a a likely non-exhaustive list of option names, please see the
909     source file <em>/src/optinc.h</em> to see the actual list:</p>
910     </dd>
911     <dd>
912     <pre>
913     borderLess console cursorBlink cursorUnderline hold iconic insecure
914     intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
915 root 1.33 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
916     scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput
917     scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs
918     transparent tripleclickwords utmpInhibit visualBell</pre>
919 root 1.15 </dd>
920     <p></p>
921 root 1.2 <dt><strong><a name="item_resource">$value = $term-&gt;resource ($name[, $newval])</a></strong><br />
922     </dt>
923     <dd>
924     Returns the current resource value associated with a given name and
925     optionally sets a new value. Setting values is most useful in the <code>init</code>
926     hook. Unset resources are returned and accepted as <code>undef</code>.
927     </dd>
928     <dd>
929     <p>The new value must be properly encoded to a suitable character encoding
930     before passing it to this method. Similarly, the returned value may need
931     to be converted from the used encoding to text.</p>
932     </dd>
933     <dd>
934     <p>Resource names are as defined in <em>src/rsinc.h</em>. Colours can be specified
935     as resource names of the form <code>color+&lt;index&gt;</code>, e.g. <code>color+5</code>. (will
936     likely change).</p>
937     </dd>
938     <dd>
939     <p>Please note that resource strings will currently only be freed when the
940     terminal is destroyed, so changing options frequently will eat memory.</p>
941     </dd>
942     <dd>
943     <p>Here is a a likely non-exhaustive list of resource names, not all of which
944 root 1.15 are supported in every build, please see the source file <em>/src/rsinc.h</em>
945     to see the actual list:</p>
946 root 1.2 </dd>
947     <dd>
948     <pre>
949     answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
950     borderLess color cursorBlink cursorUnderline cutchars delete_key
951     display_name embed ext_bwidth fade font geometry hold iconName
952     imFont imLocale inputMethod insecure int_bwidth intensityStyles
953 root 1.33 italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier
954     mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
955     perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
956     preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
957     scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
958     scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
959     secondaryScreen secondaryScroll selectstyle shade term_name title
960     transient_for transparent transparent_all tripleclickwords utmpInhibit
961     visualBell</pre>
962 root 1.2 </dd>
963     <p></p>
964 root 1.24 <dt><strong><a name="item_x_resource">$value = $term-&gt;x_resource ($pattern)</a></strong><br />
965     </dt>
966     <dd>
967     Returns the X-Resource for the given pattern, excluding the program or
968     class name, i.e. <a href="#item_x_resource"><code>$term-&gt;x_resource (&quot;boldFont&quot;)</code></a> should return the
969     same value as used by this instance of rxvt-unicode. Returns <code>undef</code> if no
970     resource with that pattern exists.
971     </dd>
972     <dd>
973     <p>This method should only be called during the <code>on_start</code> hook, as there is
974     only one resource database per display, and later invocations might return
975     the wrong resources.</p>
976     </dd>
977     <p></p>
978 root 1.19 <dt><strong><a name="item_parse_keysym">$success = $term-&gt;parse_keysym ($keysym_spec, $command_string)</a></strong><br />
979     </dt>
980     <dd>
981     Adds a keymap translation exactly as specified via a resource. See the
982 root 1.30 <code>keysym</code> resource in the <code>rxvt(1)</code> manpage.
983 root 1.19 </dd>
984     <p></p>
985 root 1.14 <dt><strong><a name="item_rstyle">$rend = $term-&gt;rstyle ([$new_rstyle])</a></strong><br />
986 root 1.13 </dt>
987     <dd>
988 root 1.14 Return and optionally change the current rendition. Text that is output by
989     the terminal application will use this style.
990 root 1.13 </dd>
991     <p></p>
992     <dt><strong><a name="item_screen_cur">($row, $col) = $term-&gt;screen_cur ([$row, $col])</a></strong><br />
993     </dt>
994     <dd>
995     Return the current coordinates of the text cursor position and optionally
996     set it (which is usually bad as applications don't expect that).
997     </dd>
998     <p></p>
999 root 1.1 <dt><strong><a name="item_selection_mark">($row, $col) = $term-&gt;selection_mark ([$row, $col])</a></strong><br />
1000     </dt>
1001     <dt><strong><a name="item_selection_beg">($row, $col) = $term-&gt;selection_beg ([$row, $col])</a></strong><br />
1002     </dt>
1003     <dt><strong><a name="item_selection_end">($row, $col) = $term-&gt;selection_end ([$row, $col])</a></strong><br />
1004     </dt>
1005     <dd>
1006     Return the current values of the selection mark, begin or end positions,
1007     and optionally set them to new values.
1008     </dd>
1009     <p></p>
1010 root 1.25 <dt><strong><a name="item_selection_make">$term-&gt;selection_make ($eventtime[, $rectangular])</a></strong><br />
1011     </dt>
1012     <dd>
1013     Tries to make a selection as set by <a href="#item_selection_beg"><code>selection_beg</code></a> and
1014     <a href="#item_selection_end"><code>selection_end</code></a>. If <code>$rectangular</code> is true (default: false), a
1015     rectangular selection will be made. This is the prefered function to make
1016     a selection.
1017     </dd>
1018     <p></p>
1019 root 1.1 <dt><strong><a name="item_selection_grab">$success = $term-&gt;selection_grab ($eventtime)</a></strong><br />
1020     </dt>
1021     <dd>
1022 root 1.25 Try to request the primary selection text from the server (for example, as
1023     set by the next method). No visual feedback will be given. This function
1024     is mostly useful from within <code>on_sel_grab</code> hooks.
1025 root 1.1 </dd>
1026     <p></p>
1027 root 1.6 <dt><strong>$oldtext = $term-&gt;selection ([$newtext])</strong><br />
1028 root 1.1 </dt>
1029     <dd>
1030     Return the current selection text and optionally replace it by <code>$newtext</code>.
1031     </dd>
1032 root 1.19 <p></p>
1033     <dt><strong><a name="item_overlay_simple">$term-&gt;overlay_simple ($x, $y, $text)</a></strong><br />
1034     </dt>
1035 root 1.1 <dd>
1036 root 1.19 Create a simple multi-line overlay box. See the next method for details.
1037 root 1.1 </dd>
1038     <p></p>
1039 root 1.8 <dt><strong><a name="item_overlay">$term-&gt;overlay ($x, $y, $width, $height[, $rstyle[, $border]])</a></strong><br />
1040 root 1.1 </dt>
1041     <dd>
1042     Create a new (empty) overlay at the given position with the given
1043 root 1.8 width/height. <code>$rstyle</code> defines the initial rendition style
1044     (default: <code>OVERLAY_RSTYLE</code>).
1045     </dd>
1046     <dd>
1047     <p>If <code>$border</code> is <code>2</code> (default), then a decorative border will be put
1048     around the box.</p>
1049     </dd>
1050     <dd>
1051     <p>If either <code>$x</code> or <code>$y</code> is negative, then this is counted from the
1052     right/bottom side, respectively.</p>
1053 root 1.1 </dd>
1054     <dd>
1055 root 1.8 <p>This method returns an urxvt::overlay object. The overlay will be visible
1056     as long as the perl object is referenced.</p>
1057 root 1.1 </dd>
1058     <dd>
1059 root 1.9 <p>The methods currently supported on <code>urxvt::overlay</code> objects are:</p>
1060 root 1.1 </dd>
1061 root 1.9 <dl>
1062 root 1.8 <dt><strong><a name="item_set">$overlay-&gt;set ($x, $y, $text, $rend)</a></strong><br />
1063 root 1.1 </dt>
1064     <dd>
1065 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
1066     text in rxvt-unicode's special encoding and an array of rendition values
1067     at a specific position inside the overlay.
1068 root 1.1 </dd>
1069 root 1.3 <p></p>
1070 root 1.9 <dt><strong><a name="item_hide">$overlay-&gt;hide</a></strong><br />
1071     </dt>
1072     <dd>
1073     If visible, hide the overlay, but do not destroy it.
1074     </dd>
1075     <p></p>
1076     <dt><strong><a name="item_show">$overlay-&gt;show</a></strong><br />
1077     </dt>
1078     <dd>
1079     If hidden, display the overlay again.
1080     </dd>
1081     <p></p></dl>
1082 root 1.16 <dt><strong>$popup = $term-&gt;popup ($event)</strong><br />
1083 root 1.15 </dt>
1084     <dd>
1085     Creates a new <code>urxvt::popup</code> object that implements a popup menu. The
1086     <code>$event</code> <em>must</em> be the event causing the menu to pop up (a button event,
1087     currently).
1088     </dd>
1089     <p></p>
1090 root 1.14 <dt><strong><a name="item_strwidth">$cellwidth = $term-&gt;strwidth ($string)</a></strong><br />
1091 root 1.3 </dt>
1092     <dd>
1093     Returns the number of screen-cells this string would need. Correctly
1094     accounts for wide and combining characters.
1095     </dd>
1096     <p></p>
1097 root 1.14 <dt><strong><a name="item_locale_encode">$octets = $term-&gt;locale_encode ($string)</a></strong><br />
1098 root 1.3 </dt>
1099     <dd>
1100     Convert the given text string into the corresponding locale encoding.
1101     </dd>
1102     <p></p>
1103 root 1.14 <dt><strong><a name="item_locale_decode">$string = $term-&gt;locale_decode ($octets)</a></strong><br />
1104 root 1.3 </dt>
1105     <dd>
1106     Convert the given locale-encoded octets into a perl string.
1107     </dd>
1108     <p></p>
1109 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 />
1110     </dt>
1111     <dd>
1112     XORs the rendition values in the given span with the provided value
1113 root 1.25 (default: <code>RS_RVid</code>), which <em>MUST NOT</em> contain font styles. Useful in
1114     refresh hooks to provide effects similar to the selection.
1115 root 1.19 </dd>
1116     <p></p>
1117     <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 />
1118     </dt>
1119     <dd>
1120     Similar to <a href="#item_scr_xor_span"><code>scr_xor_span</code></a>, but xors a rectangle instead. Trailing
1121     whitespace will additionally be xored with the <code>$rstyle2</code>, which defaults
1122     to <code>RS_RVid | RS_Uline</code>, which removes reverse video again and underlines
1123 root 1.25 it instead. Both styles <em>MUST NOT</em> contain font styles.
1124 root 1.19 </dd>
1125     <p></p>
1126     <dt><strong><a name="item_scr_bell">$term-&gt;scr_bell</a></strong><br />
1127     </dt>
1128     <dd>
1129     Ring the bell!
1130     </dd>
1131     <p></p>
1132 root 1.14 <dt><strong><a name="item_scr_add_lines">$term-&gt;scr_add_lines ($string)</a></strong><br />
1133     </dt>
1134     <dd>
1135     Write the given text string to the screen, as if output by the application
1136     running inside the terminal. It may not contain command sequences (escape
1137     codes), but is free to use line feeds, carriage returns and tabs. The
1138     string is a normal text string, not in locale-dependent encoding.
1139     </dd>
1140     <dd>
1141     <p>Normally its not a good idea to use this function, as programs might be
1142     confused by changes in cursor position or scrolling. Its useful inside a
1143     <code>on_add_lines</code> hook, though.</p>
1144     </dd>
1145     <p></p>
1146     <dt><strong><a name="item_cmd_parse">$term-&gt;cmd_parse ($octets)</a></strong><br />
1147     </dt>
1148     <dd>
1149     Similar to <a href="#item_scr_add_lines"><code>scr_add_lines</code></a>, but the argument must be in the
1150     locale-specific encoding of the terminal and can contain command sequences
1151     (escape codes) that will be interpreted.
1152     </dd>
1153     <p></p>
1154 root 1.3 <dt><strong><a name="item_tt_write">$term-&gt;tt_write ($octets)</a></strong><br />
1155     </dt>
1156     <dd>
1157     Write the octets given in <code>$data</code> to the tty (i.e. as program input). To
1158 root 1.6 pass characters instead of octets, you should convert your strings first
1159     to the locale-specific encoding using <a href="#item_locale_encode"><code>$term-&gt;locale_encode</code></a>.
1160     </dd>
1161     <p></p>
1162 root 1.19 <dt><strong><a name="item_pty_ev_events">$old_events = $term-&gt;pty_ev_events ([$new_events])</a></strong><br />
1163     </dt>
1164     <dd>
1165     Replaces the event mask of the pty watcher by the given event mask. Can
1166     be used to suppress input and output handling to the pty/tty. See the
1167     description of <a href="#item_events"><code>urxvt::timer-&gt;events</code></a>. Make sure to always restore
1168     the previous value.
1169     </dd>
1170     <p></p>
1171 root 1.14 <dt><strong><a name="item_parent">$windowid = $term-&gt;parent</a></strong><br />
1172     </dt>
1173     <dd>
1174     Return the window id of the toplevel window.
1175     </dd>
1176     <p></p>
1177     <dt><strong><a name="item_vt">$windowid = $term-&gt;vt</a></strong><br />
1178     </dt>
1179     <dd>
1180     Return the window id of the terminal window.
1181     </dd>
1182     <p></p>
1183 root 1.29 <dt><strong><a name="item_vt_emask_add">$term-&gt;vt_emask_add ($x_event_mask)</a></strong><br />
1184     </dt>
1185     <dd>
1186     Adds the specified events to the vt event mask. Useful e.g. when you want
1187     to receive pointer events all the times:
1188     </dd>
1189     <dd>
1190     <pre>
1191     $term-&gt;vt_emask_add (urxvt::PointerMotionMask);</pre>
1192     </dd>
1193     <p></p>
1194 root 1.13 <dt><strong><a name="item_width">$window_width = $term-&gt;width</a></strong><br />
1195     </dt>
1196     <dt><strong><a name="item_height">$window_height = $term-&gt;height</a></strong><br />
1197     </dt>
1198     <dt><strong><a name="item_fwidth">$font_width = $term-&gt;fwidth</a></strong><br />
1199 root 1.6 </dt>
1200 root 1.13 <dt><strong><a name="item_fheight">$font_height = $term-&gt;fheight</a></strong><br />
1201 root 1.6 </dt>
1202 root 1.13 <dt><strong><a name="item_fbase">$font_ascent = $term-&gt;fbase</a></strong><br />
1203     </dt>
1204     <dt><strong><a name="item_nrow">$terminal_rows = $term-&gt;nrow</a></strong><br />
1205     </dt>
1206     <dt><strong><a name="item_ncol">$terminal_columns = $term-&gt;ncol</a></strong><br />
1207     </dt>
1208     <dt><strong><a name="item_focus">$has_focus = $term-&gt;focus</a></strong><br />
1209     </dt>
1210     <dt><strong><a name="item_mapped">$is_mapped = $term-&gt;mapped</a></strong><br />
1211     </dt>
1212     <dt><strong><a name="item_savelines">$max_scrollback = $term-&gt;saveLines</a></strong><br />
1213     </dt>
1214     <dt><strong><a name="item_total_rows">$nrow_plus_saveLines = $term-&gt;total_rows</a></strong><br />
1215     </dt>
1216 root 1.30 <dt><strong><a name="item_top_row">$topmost_scrollback_row = $term-&gt;top_row</a></strong><br />
1217 root 1.6 </dt>
1218     <dd>
1219 root 1.13 Return various integers describing terminal characteristics.
1220 root 1.6 </dd>
1221     <p></p>
1222 root 1.22 <dt><strong><a name="item_display_id">$x_display = $term-&gt;display_id</a></strong><br />
1223     </dt>
1224     <dd>
1225     Return the DISPLAY used by rxvt-unicode.
1226     </dd>
1227     <p></p>
1228 root 1.19 <dt><strong><a name="item_locale">$lc_ctype = $term-&gt;locale</a></strong><br />
1229     </dt>
1230     <dd>
1231     Returns the LC_CTYPE category string used by this rxvt-unicode.
1232     </dd>
1233     <p></p>
1234 root 1.22 <dt><strong><a name="item_env">$env = $term-&gt;env</a></strong><br />
1235 root 1.19 </dt>
1236     <dd>
1237 root 1.22 Returns a copy of the environment in effect for the terminal as a hashref
1238     similar to <code>\%ENV</code>.
1239 root 1.19 </dd>
1240     <p></p>
1241 root 1.15 <dt><strong><a name="item_modlevel3mask">$modifiermask = $term-&gt;ModLevel3Mask</a></strong><br />
1242     </dt>
1243     <dt><strong><a name="item_modmetamask">$modifiermask = $term-&gt;ModMetaMask</a></strong><br />
1244     </dt>
1245     <dt><strong><a name="item_modnumlockmask">$modifiermask = $term-&gt;ModNumLockMask</a></strong><br />
1246     </dt>
1247     <dd>
1248     Return the modifier masks corresponding to the ``ISO Level 3 Shift'' (often
1249     AltGr), the meta key (often Alt) and the num lock key, if applicable.
1250     </dd>
1251     <p></p>
1252 root 1.6 <dt><strong><a name="item_view_start">$view_start = $term-&gt;view_start ([$newvalue])</a></strong><br />
1253     </dt>
1254     <dd>
1255 root 1.30 Returns the row number of the topmost displayed line. Maximum value is
1256     <code>0</code>, which displays the normal terminal contents. Lower values scroll
1257 root 1.6 this many lines into the scrollback buffer.
1258     </dd>
1259     <p></p>
1260     <dt><strong><a name="item_want_refresh">$term-&gt;want_refresh</a></strong><br />
1261     </dt>
1262     <dd>
1263     Requests a screen refresh. At the next opportunity, rxvt-unicode will
1264     compare the on-screen display with its stored representation. If they
1265     differ, it redraws the differences.
1266     </dd>
1267     <dd>
1268     <p>Used after changing terminal contents to display them.</p>
1269     </dd>
1270     <p></p>
1271     <dt><strong><a name="item_row_t">$text = $term-&gt;ROW_t ($row_number[, $new_text[, $start_col]])</a></strong><br />
1272     </dt>
1273     <dd>
1274     Returns the text of the entire row with number <code>$row_number</code>. Row <code>0</code>
1275     is the topmost terminal line, row <code>$term-&gt;$ncol-1</code> is the bottommost
1276     terminal line. The scrollback buffer starts at line <code>-1</code> and extends to
1277 root 1.30 line <code>-$term-&gt;nsaved</code>. Nothing will be returned if a nonexistent line
1278 root 1.9 is requested.
1279 root 1.6 </dd>
1280     <dd>
1281     <p>If <code>$new_text</code> is specified, it will replace characters in the current
1282     line, starting at column <code>$start_col</code> (default <code>0</code>), which is useful
1283 root 1.8 to replace only parts of a line. The font index in the rendition will
1284 root 1.6 automatically be updated.</p>
1285     </dd>
1286     <dd>
1287 root 1.14 <p><a href="#item__24text"><code>$text</code></a> is in a special encoding: tabs and wide characters that use more
1288 root 1.6 than one cell when displayed are padded with urxvt::NOCHAR characters
1289     (<code>chr 65535</code>). Characters with combining characters and other characters
1290     that do not fit into the normal tetx encoding will be replaced with
1291     characters in the private use area.</p>
1292     </dd>
1293     <dd>
1294     <p>You have to obey this encoding when changing text. The advantage is
1295     that <code>substr</code> and similar functions work on screen cells and not on
1296     characters.</p>
1297     </dd>
1298     <dd>
1299 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>
1300 root 1.6 can be used to convert normal strings into this encoding and vice versa.</p>
1301     </dd>
1302     <p></p>
1303     <dt><strong><a name="item_row_r">$rend = $term-&gt;ROW_r ($row_number[, $new_rend[, $start_col]])</a></strong><br />
1304     </dt>
1305     <dd>
1306     Like <a href="#item_row_t"><code>$term-&gt;ROW_t</code></a>, but returns an arrayref with rendition
1307     bitsets. Rendition bitsets contain information about colour, font, font
1308     styles and similar information. See also <a href="#item_row_t"><code>$term-&gt;ROW_t</code></a>.
1309     </dd>
1310     <dd>
1311     <p>When setting rendition, the font mask will be ignored.</p>
1312     </dd>
1313     <dd>
1314 root 1.8 <p>See the section on RENDITION, above.</p>
1315 root 1.6 </dd>
1316     <p></p>
1317     <dt><strong><a name="item_row_l">$length = $term-&gt;ROW_l ($row_number[, $new_length])</a></strong><br />
1318     </dt>
1319     <dd>
1320 root 1.9 Returns the number of screen cells that are in use (``the line
1321     length''). Unlike the urxvt core, this returns <a href="#item_ncol"><code>$term-&gt;ncol</code></a> if the
1322     line is joined with the following one.
1323     </dd>
1324     <p></p>
1325     <dt><strong><a name="item_is_longer">$bool = $term-&gt;is_longer ($row_number)</a></strong><br />
1326     </dt>
1327     <dd>
1328     Returns true if the row is part of a multiple-row logical ``line'' (i.e.
1329     joined with the following row), which means all characters are in use
1330     and it is continued on the next row (and possibly a continuation of the
1331     previous row(s)).
1332 root 1.6 </dd>
1333     <p></p>
1334 root 1.9 <dt><strong><a name="item_line">$line = $term-&gt;line ($row_number)</a></strong><br />
1335     </dt>
1336     <dd>
1337     Create and return a new <code>urxvt::line</code> object that stores information
1338     about the logical line that row <code>$row_number</code> is part of. It supports the
1339     following methods:
1340     </dd>
1341     <dl>
1342 root 1.14 <dt><strong><a name="item_t">$text = $line-&gt;t ([$new_text])</a></strong><br />
1343 root 1.9 </dt>
1344     <dd>
1345 root 1.14 Returns or replaces the full text of the line, similar to <a href="#item_row_t"><code>ROW_t</code></a>
1346 root 1.9 </dd>
1347     <p></p>
1348 root 1.14 <dt><strong><a name="item_r">$rend = $line-&gt;r ([$new_rend])</a></strong><br />
1349 root 1.9 </dt>
1350     <dd>
1351 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>
1352 root 1.9 </dd>
1353     <p></p>
1354     <dt><strong><a name="item_l">$length = $line-&gt;l</a></strong><br />
1355     </dt>
1356     <dd>
1357     Returns the length of the line in cells, similar to <a href="#item_row_l"><code>ROW_l</code></a>.
1358     </dd>
1359     <p></p>
1360     <dt><strong><a name="item_beg">$rownum = $line-&gt;beg</a></strong><br />
1361     </dt>
1362     <dt><strong><a name="item_end">$rownum = $line-&gt;end</a></strong><br />
1363     </dt>
1364     <dd>
1365     Return the row number of the first/last row of the line, respectively.
1366     </dd>
1367     <p></p>
1368     <dt><strong><a name="item_offset_of">$offset = $line-&gt;offset_of ($row, $col)</a></strong><br />
1369     </dt>
1370     <dd>
1371     Returns the character offset of the given row|col pair within the logical
1372 root 1.25 line. Works for rows outside the line, too, and returns corresponding
1373     offsets outside the string.
1374 root 1.9 </dd>
1375     <p></p>
1376     <dt><strong><a name="item_coord_of">($row, $col) = $line-&gt;coord_of ($offset)</a></strong><br />
1377     </dt>
1378     <dd>
1379     Translates a string offset into terminal coordinates again.
1380     </dd>
1381     <p></p></dl>
1382 root 1.17 <dt><strong><a name="item_special_encode">$text = $term-&gt;special_encode $string</a></strong><br />
1383 root 1.6 </dt>
1384     <dd>
1385     Converts a perl string into the special encoding used by rxvt-unicode,
1386     where one character corresponds to one screen cell. See
1387     <a href="#item_row_t"><code>$term-&gt;ROW_t</code></a> for details.
1388     </dd>
1389     <p></p>
1390     <dt><strong><a name="item_special_decode">$string = $term-&gt;special_decode $text</a></strong><br />
1391     </dt>
1392     <dd>
1393     Converts rxvt-unicodes text reprsentation into a perl string. See
1394     <a href="#item_row_t"><code>$term-&gt;ROW_t</code></a> for details.
1395     </dd>
1396 root 1.17 <p></p>
1397     <dt><strong><a name="item_grab_button">$success = $term-&gt;grab_button ($button, $modifiermask)</a></strong><br />
1398     </dt>
1399     <dd>
1400 root 1.18 Registers a synchronous button grab. See the XGrabButton manpage.
1401 root 1.17 </dd>
1402     <p></p>
1403     <dt><strong><a name="item_grab">$success = $term-&gt;grab ($eventtime[, $sync])</a></strong><br />
1404     </dt>
1405     <dd>
1406     Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1407     synchronous (<code>$sync</code> is true). Also remembers the grab timestampe.
1408     </dd>
1409     <p></p>
1410     <dt><strong><a name="item_allow_events_async">$term-&gt;allow_events_async</a></strong><br />
1411     </dt>
1412     <dd>
1413     Calls XAllowEvents with AsyncBoth for the most recent grab.
1414     </dd>
1415     <p></p>
1416     <dt><strong><a name="item_allow_events_sync">$term-&gt;allow_events_sync</a></strong><br />
1417     </dt>
1418     <dd>
1419     Calls XAllowEvents with SyncBoth for the most recent grab.
1420     </dd>
1421     <p></p>
1422     <dt><strong><a name="item_allow_events_replay">$term-&gt;allow_events_replay</a></strong><br />
1423     </dt>
1424     <dd>
1425     Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most
1426     recent grab.
1427     </dd>
1428     <p></p>
1429     <dt><strong><a name="item_ungrab">$term-&gt;ungrab</a></strong><br />
1430     </dt>
1431     <dd>
1432     Calls XUngrab for the most recent grab. Is called automatically on
1433     evaluation errors, as it is better to lose the grab in the error case as
1434     the session.
1435     </dd>
1436 root 1.6 <p></p></dl>
1437     <p>
1438     </p>
1439 root 1.15 <h2><a name="the_urxvt__popup_class">The <code>urxvt::popup</code> Class</a></h2>
1440 root 1.21 <dl>
1441     <dt><strong><a name="item_add_title">$popup-&gt;add_title ($title)</a></strong><br />
1442     </dt>
1443     <dd>
1444     Adds a non-clickable title to the popup.
1445     </dd>
1446     <p></p>
1447     <dt><strong><a name="item_add_separator">$popup-&gt;add_separator ([$sepchr])</a></strong><br />
1448     </dt>
1449     <dd>
1450     Creates a separator, optionally using the character given as <code>$sepchr</code>.
1451     </dd>
1452     <p></p>
1453     <dt><strong><a name="item_add_button">$popup-&gt;add_button ($text, $cb)</a></strong><br />
1454     </dt>
1455     <dd>
1456     Adds a clickable button to the popup. <code>$cb</code> is called whenever it is
1457     selected.
1458     </dd>
1459     <p></p>
1460     <dt><strong><a name="item_add_toggle">$popup-&gt;add_toggle ($text, $cb, $initial_value)</a></strong><br />
1461     </dt>
1462     <dd>
1463     Adds a toggle/checkbox item to the popup. Teh callback gets called
1464     whenever it gets toggled, with a boolean indicating its value as its first
1465     argument.
1466     </dd>
1467     <p></p>
1468     <dt><strong>$popup-&gt;show</strong><br />
1469     </dt>
1470     <dd>
1471     Displays the popup (which is initially hidden).
1472     </dd>
1473     <p></p></dl>
1474 root 1.15 <p>
1475     </p>
1476 root 1.1 <h2><a name="the_urxvt__timer_class">The <code>urxvt::timer</code> Class</a></h2>
1477     <p>This class implements timer watchers/events. Time is represented as a
1478     fractional number of seconds since the epoch. Example:</p>
1479     <pre>
1480 root 1.8 $term-&gt;{overlay} = $term-&gt;overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
1481 root 1.1 $term-&gt;{timer} = urxvt::timer
1482     -&gt;new
1483 root 1.8 -&gt;interval (1)
1484 root 1.1 -&gt;cb (sub {
1485 root 1.8 $term-&gt;{overlay}-&gt;set (0, 0,
1486     sprintf &quot;%2d:%02d:%02d&quot;, (localtime urxvt::NOW)[2,1,0]);
1487 root 1.1 });</pre>
1488     <dl>
1489     <dt><strong><a name="item__24timer__3d_new_urxvt_3a_3atimer">$timer = new urxvt::timer</a></strong><br />
1490     </dt>
1491     <dd>
1492 root 1.8 Create a new timer object in started state. It is scheduled to fire
1493     immediately.
1494 root 1.1 </dd>
1495     <p></p>
1496     <dt><strong><a name="item_cb">$timer = $timer-&gt;cb (sub { my ($timer) = @_; ... })</a></strong><br />
1497     </dt>
1498     <dd>
1499     Set the callback to be called when the timer triggers.
1500     </dd>
1501     <p></p>
1502     <dt><strong><a name="item_at">$tstamp = $timer-&gt;at</a></strong><br />
1503     </dt>
1504     <dd>
1505     Return the time this watcher will fire next.
1506     </dd>
1507     <p></p>
1508 root 1.8 <dt><strong>$timer = $timer-&gt;set ($tstamp)</strong><br />
1509 root 1.1 </dt>
1510     <dd>
1511     Set the time the event is generated to $tstamp.
1512     </dd>
1513     <p></p>
1514 root 1.8 <dt><strong><a name="item_interval">$timer = $timer-&gt;interval ($interval)</a></strong><br />
1515     </dt>
1516     <dd>
1517     Normally (and when <code>$interval</code> is <code>0</code>), the timer will automatically
1518     stop after it has fired once. If <code>$interval</code> is non-zero, then the timer
1519     is automatically rescheduled at the given intervals.
1520     </dd>
1521     <p></p>
1522 root 1.1 <dt><strong><a name="item_start">$timer = $timer-&gt;start</a></strong><br />
1523     </dt>
1524     <dd>
1525     Start the timer.
1526     </dd>
1527     <p></p>
1528     <dt><strong>$timer = $timer-&gt;start ($tstamp)</strong><br />
1529     </dt>
1530     <dd>
1531     Set the event trigger time to <code>$tstamp</code> and start the timer.
1532     </dd>
1533     <p></p>
1534 root 1.33 <dt><strong><a name="item_after">$timer = $timer-&gt;after ($delay)</a></strong><br />
1535     </dt>
1536     <dd>
1537     Like <a href="#item_start"><code>start</code></a>, but sets the expiry timer to c&lt;urxvt::NOW + $delay&gt;.
1538     </dd>
1539     <p></p>
1540 root 1.1 <dt><strong><a name="item_stop">$timer = $timer-&gt;stop</a></strong><br />
1541     </dt>
1542     <dd>
1543     Stop the timer.
1544     </dd>
1545     <p></p></dl>
1546     <p>
1547     </p>
1548     <h2><a name="the_urxvt__iow_class">The <code>urxvt::iow</code> Class</a></h2>
1549     <p>This class implements io watchers/events. Example:</p>
1550     <pre>
1551     $term-&gt;{socket} = ...
1552     $term-&gt;{iow} = urxvt::iow
1553     -&gt;new
1554     -&gt;fd (fileno $term-&gt;{socket})
1555 root 1.19 -&gt;events (urxvt::EVENT_READ)
1556 root 1.1 -&gt;start
1557     -&gt;cb (sub {
1558     my ($iow, $revents) = @_;
1559     # $revents must be 1 here, no need to check
1560     sysread $term-&gt;{socket}, my $buf, 8192
1561     or end-of-file;
1562     });</pre>
1563     <dl>
1564     <dt><strong><a name="item__24iow__3d_new_urxvt_3a_3aiow">$iow = new urxvt::iow</a></strong><br />
1565     </dt>
1566     <dd>
1567     Create a new io watcher object in stopped state.
1568     </dd>
1569     <p></p>
1570     <dt><strong>$iow = $iow-&gt;cb (sub { my ($iow, $reventmask) = @_; ... })</strong><br />
1571     </dt>
1572     <dd>
1573     Set the callback to be called when io events are triggered. <code>$reventmask</code>
1574     is a bitset as described in the <a href="#item_events"><code>events</code></a> method.
1575     </dd>
1576     <p></p>
1577     <dt><strong><a name="item_fd">$iow = $iow-&gt;fd ($fd)</a></strong><br />
1578     </dt>
1579     <dd>
1580     Set the filedescriptor (not handle) to watch.
1581     </dd>
1582     <p></p>
1583     <dt><strong><a name="item_events">$iow = $iow-&gt;events ($eventmask)</a></strong><br />
1584     </dt>
1585     <dd>
1586 root 1.19 Set the event mask to watch. The only allowed values are
1587     <code>urxvt::EVENT_READ</code> and <code>urxvt::EVENT_WRITE</code>, which might be ORed
1588     together, or <code>urxvt::EVENT_NONE</code>.
1589 root 1.1 </dd>
1590     <p></p>
1591     <dt><strong>$iow = $iow-&gt;start</strong><br />
1592     </dt>
1593     <dd>
1594     Start watching for requested events on the given handle.
1595     </dd>
1596     <p></p>
1597     <dt><strong>$iow = $iow-&gt;stop</strong><br />
1598     </dt>
1599     <dd>
1600     Stop watching for events on the given filehandle.
1601     </dd>
1602     <p></p></dl>
1603     <p>
1604     </p>
1605 root 1.34 <h2><a name="the_urxvt__iw_class">The <code>urxvt::iw</code> Class</a></h2>
1606     <p>This class implements idle watchers, that get called automatically when
1607     the process is idle. They should return as fast as possible, after doing
1608     some useful work.</p>
1609     <dl>
1610     <dt><strong><a name="item__24iw__3d_new_urxvt_3a_3aiw">$iw = new urxvt::iw</a></strong><br />
1611     </dt>
1612     <dd>
1613     Create a new idle watcher object in stopped state.
1614     </dd>
1615     <p></p>
1616     <dt><strong>$iw = $iw-&gt;cb (sub { my ($iw) = @_; ... })</strong><br />
1617     </dt>
1618     <dd>
1619     Set the callback to be called when the watcher triggers.
1620     </dd>
1621     <p></p>
1622     <dt><strong>$timer = $timer-&gt;start</strong><br />
1623     </dt>
1624     <dd>
1625     Start the watcher.
1626     </dd>
1627     <p></p>
1628     <dt><strong>$timer = $timer-&gt;stop</strong><br />
1629     </dt>
1630     <dd>
1631     Stop the watcher.
1632     </dd>
1633     <p></p></dl>
1634     <p>
1635     </p>
1636     <h2><a name="the_urxvt__pw_class">The <code>urxvt::pw</code> Class</a></h2>
1637     <p>This class implements process watchers. They create an event whenever a
1638     process exits, after which they stop automatically.</p>
1639     <pre>
1640     my $pid = fork;
1641     ...
1642     $term-&gt;{pw} = urxvt::pw
1643     -&gt;new
1644     -&gt;start ($pid)
1645     -&gt;cb (sub {
1646     my ($pw, $exit_status) = @_;
1647     ...
1648     });</pre>
1649     <dl>
1650     <dt><strong><a name="item__24pw__3d_new_urxvt_3a_3apw">$pw = new urxvt::pw</a></strong><br />
1651     </dt>
1652     <dd>
1653     Create a new process watcher in stopped state.
1654     </dd>
1655     <p></p>
1656     <dt><strong>$pw = $pw-&gt;cb (sub { my ($pw, $exit_status) = @_; ... })</strong><br />
1657     </dt>
1658     <dd>
1659     Set the callback to be called when the timer triggers.
1660     </dd>
1661     <p></p>
1662     <dt><strong>$pw = $timer-&gt;start ($pid)</strong><br />
1663     </dt>
1664     <dd>
1665     Tells the wqtcher to start watching for process <code>$pid</code>.
1666     </dd>
1667     <p></p>
1668     <dt><strong>$pw = $pw-&gt;stop</strong><br />
1669     </dt>
1670     <dd>
1671     Stop the watcher.
1672     </dd>
1673     <p></p></dl>
1674     <p>
1675     </p>
1676 root 1.1 <hr />
1677 root 1.2 <h1><a name="environment">ENVIRONMENT</a></h1>
1678     <p>
1679     </p>
1680     <h2><a name="urxvt_perl_verbosity">URXVT_PERL_VERBOSITY</a></h2>
1681     <p>This variable controls the verbosity level of the perl extension. Higher
1682     numbers indicate more verbose output.</p>
1683 root 1.10 <dl>
1684 root 1.17 <dt><strong><a name="item__3d_3d_0__2d_fatal_messages">== 0 - fatal messages</a></strong><br />
1685 root 1.10 </dt>
1686 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 />
1687 root 1.10 </dt>
1688 root 1.25 <dt><strong><a name="item__3e_3d10__2d_all_called_hooks">&gt;=10 - all called hooks</a></strong><br />
1689     </dt>
1690     <dt><strong><a name="item__3e_3d11__2d_hook_reutrn_values">&gt;=11 - hook reutrn values</a></strong><br />
1691 root 1.10 </dt>
1692     </dl>
1693 root 1.2 <p>
1694     </p>
1695     <hr />
1696 root 1.1 <h1><a name="author">AUTHOR</a></h1>
1697     <pre>
1698     Marc Lehmann &lt;pcg@goof.com&gt;
1699     <a href="http://software.schmorp.de/pkg/rxvt-unicode">http://software.schmorp.de/pkg/rxvt-unicode</a></pre>
1700    
1701     </body>
1702    
1703     </html>