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