ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/rxvt-unicode/doc/rxvtperl.3.man.in
Revision: 1.7
Committed: Tue Jan 3 01:45:12 2006 UTC (18 years, 6 months ago) by root
Branch: MAIN
Changes since 1.6: +3 -3 lines
Log Message:
*** empty log message ***

File Contents

# User Rev Content
1 root 1.1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
2     .\"
3     .\" Standard preamble:
4     .\" ========================================================================
5     .de Sh \" Subsection heading
6     .br
7     .if t .Sp
8     .ne 5
9     .PP
10     \fB\\$1\fR
11     .PP
12     ..
13     .de Sp \" Vertical space (when we can't use .PP)
14     .if t .sp .5v
15     .if n .sp
16     ..
17     .de Vb \" Begin verbatim text
18     .ft CW
19     .nf
20     .ne \\$1
21     ..
22     .de Ve \" End verbatim text
23     .ft R
24     .fi
25     ..
26     .\" Set up some character translations and predefined strings. \*(-- will
27     .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28     .\" double quote, and \*(R" will give a right double quote. | will give a
29     .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30     .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31     .\" expand to `' in nroff, nothing in troff, for use with C<>.
32     .tr \(*W-|\(bv\*(Tr
33     .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
34     .ie n \{\
35     . ds -- \(*W-
36     . ds PI pi
37     . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38     . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
39     . ds L" ""
40     . ds R" ""
41     . ds C` ""
42     . ds C' ""
43     'br\}
44     .el\{\
45     . ds -- \|\(em\|
46     . ds PI \(*p
47     . ds L" ``
48     . ds R" ''
49     'br\}
50     .\"
51     .\" If the F register is turned on, we'll generate index entries on stderr for
52     .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53     .\" entries marked with X<> in POD. Of course, you'll have to process the
54     .\" output yourself in some meaningful fashion.
55     .if \nF \{\
56     . de IX
57     . tm Index:\\$1\t\\n%\t"\\$2"
58     ..
59     . nr % 0
60     . rr F
61     .\}
62     .\"
63     .\" For nroff, turn off justification. Always turn off hyphenation; it makes
64     .\" way too many mistakes in technical documents.
65     .hy 0
66     .if n .na
67     .\"
68     .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69     .\" Fear. Run. Save yourself. No user-serviceable parts.
70     . \" fudge factors for nroff and troff
71     .if n \{\
72     . ds #H 0
73     . ds #V .8m
74     . ds #F .3m
75     . ds #[ \f1
76     . ds #] \fP
77     .\}
78     .if t \{\
79     . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80     . ds #V .6m
81     . ds #F 0
82     . ds #[ \&
83     . ds #] \&
84     .\}
85     . \" simple accents for nroff and troff
86     .if n \{\
87     . ds ' \&
88     . ds ` \&
89     . ds ^ \&
90     . ds , \&
91     . ds ~ ~
92     . ds /
93     .\}
94     .if t \{\
95     . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96     . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97     . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98     . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99     . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100     . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
101     .\}
102     . \" troff and (daisy-wheel) nroff accents
103     .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104     .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105     .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106     .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107     .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108     .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109     .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110     .ds ae a\h'-(\w'a'u*4/10)'e
111     .ds Ae A\h'-(\w'A'u*4/10)'E
112     . \" corrections for vroff
113     .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114     .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115     . \" for low resolution devices (crt and lpr)
116     .if \n(.H>23 .if \n(.V>19 \
117     \{\
118     . ds : e
119     . ds 8 ss
120     . ds o a
121     . ds d- d\h'-1'\(ga
122     . ds D- D\h'-1'\(hy
123     . ds th \o'bp'
124     . ds Th \o'LP'
125     . ds ae ae
126     . ds Ae AE
127     .\}
128     .rm #[ #] #H #V #F C
129     .\" ========================================================================
130     .\"
131     .IX Title "rxvt 3"
132 root 1.6 .TH rxvt 3 "2006-01-03" "6.2" "RXVT-UNICODE"
133 root 1.1 .SH "NAME"
134 root 1.5 @@RXVT_NAME@@perl \- rxvt\-unicode's embedded perl interpreter
135 root 1.1 .SH "SYNOPSIS"
136     .IX Header "SYNOPSIS"
137 root 1.5 .Vb 1
138     \& # create a file grab_test in $HOME:
139     .Ve
140 root 1.1 .PP
141     .Vb 4
142     \& sub on_sel_grab {
143     \& warn "you selected ", $_[0]->selection;
144     \& ()
145     \& }
146     .Ve
147     .PP
148     .Vb 1
149 root 1.5 \& # start a @@RXVT_NAME@@ using it:
150     .Ve
151     .PP
152     .Vb 1
153     \& @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test
154 root 1.1 .Ve
155     .SH "DESCRIPTION"
156     .IX Header "DESCRIPTION"
157 root 1.4 Everytime a terminal object gets created, scripts specified via the
158 root 1.5 \&\f(CW\*(C`perl\*(C'\fR resource are loaded and associated with it.
159     .PP
160     Scripts are compiled in a 'use strict' and 'use utf8' environment, and
161     thus must be encoded as \s-1UTF\-8\s0.
162 root 1.3 .PP
163     Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where
164 root 1.7 scripts will be shared (but not enabled) for all terminals.
165     .Sh "Prepackaged Extensions"
166     .IX Subsection "Prepackaged Extensions"
167 root 1.6 This section describes the extensiosn delivered with this version. You can
168     find them in \fI@@RXVT_LIBDIR@@/urxvt/perl/\fR.
169     .PP
170     You can activate them like this:
171     .PP
172     .Vb 1
173     \& @@RXVT_NAME@@ -pe <extensionname>
174     .Ve
175     .IP "selection" 4
176     .IX Item "selection"
177     Miscellaneous selection modifications.
178     .RS 4
179     .IP "rot13" 4
180     .IX Item "rot13"
181     Rot\-13 the selection when activated. Used via keyboard trigger:
182     .Sp
183     .Vb 1
184     \& URxvt.keysym.C-M-r: perl:selection:rot13
185     .Ve
186     .RE
187     .RS 4
188     .RE
189     .IP "digital-clock" 4
190     .IX Item "digital-clock"
191     Displays a very simple digital clock in the upper right corner of the
192     window. Illustrates overwriting the refresh callbacks to create your own
193     overlays or changes.
194     .IP "simple-overlay-clock" 4
195     .IX Item "simple-overlay-clock"
196     Displays a digital clock using the built-in overlay (colorful, useless).
197 root 1.3 .Sh "General \s-1API\s0 Considerations"
198     .IX Subsection "General API Considerations"
199     All objects (such as terminals, time watchers etc.) are typical
200     reference-to-hash objects. The hash can be used to store anything you
201     like. All members starting with an underscore (such as \f(CW\*(C`_ptr\*(C'\fR or
202     \&\f(CW\*(C`_hook\*(C'\fR) are reserved for internal uses and must not be accessed or
203     modified).
204     .PP
205     When objects are destroyed on the \*(C+ side, the perl object hashes are
206     emptied, so its best to store related objects such as time watchers and
207     the like inside the terminal object so they get destroyed as soon as the
208     terminal is destroyed.
209 root 1.1 .Sh "Hooks"
210     .IX Subsection "Hooks"
211     The following subroutines can be declared in loaded scripts, and will be called
212     whenever the relevant event happens.
213     .PP
214     All of them must return a boolean value. If it is true, then the event
215     counts as being \fIconsumed\fR, and the invocation of other hooks is skipped,
216     and the relevant action might not be carried out by the \*(C+ code.
217     .PP
218     When in doubt, return a false value (preferably \f(CW\*(C`()\*(C'\fR).
219     .ie n .IP "on_init $term" 4
220     .el .IP "on_init \f(CW$term\fR" 4
221     .IX Item "on_init $term"
222     Called after a new terminal object has been initialized, but before
223     windows are created or the command gets run.
224     .ie n .IP "on_reset $term" 4
225     .el .IP "on_reset \f(CW$term\fR" 4
226     .IX Item "on_reset $term"
227     Called after the screen is \*(L"reset\*(R" for any reason, such as resizing or
228     control sequences. Here is where you can react on changes to size-related
229     variables.
230     .ie n .IP "on_start $term" 4
231     .el .IP "on_start \f(CW$term\fR" 4
232     .IX Item "on_start $term"
233     Called at the very end of initialisation of a new terminal, just before
234     returning to the mainloop.
235     .ie n .IP "on_sel_make $term\fR, \f(CW$eventtime" 4
236     .el .IP "on_sel_make \f(CW$term\fR, \f(CW$eventtime\fR" 4
237     .IX Item "on_sel_make $term, $eventtime"
238     Called whenever a selection has been made by the user, but before the
239     selection text is copied, so changes to the beginning, end or type of the
240     selection will be honored.
241     .Sp
242     Returning a true value aborts selection making by urxvt, in which case you
243     have to make a selection yourself by calling \f(CW\*(C`$term\->selection_grab\*(C'\fR.
244     .ie n .IP "on_sel_grab $term\fR, \f(CW$eventtime" 4
245     .el .IP "on_sel_grab \f(CW$term\fR, \f(CW$eventtime\fR" 4
246     .IX Item "on_sel_grab $term, $eventtime"
247     Called whenever a selection has been copied, but before the selection is
248     requested from the server. The selection text can be queried and changed
249     by calling \f(CW\*(C`$term\->selection\*(C'\fR.
250     .Sp
251     Returning a true value aborts selection grabbing. It will still be hilighted.
252     .ie n .IP "on_focus_in $term" 4
253     .el .IP "on_focus_in \f(CW$term\fR" 4
254     .IX Item "on_focus_in $term"
255     Called whenever the window gets the keyboard focus, before urxvt does
256     focus in processing.
257     .ie n .IP "on_focus_out $term" 4
258     .el .IP "on_focus_out \f(CW$term\fR" 4
259     .IX Item "on_focus_out $term"
260     Called wheneever the window loses keyboard focus, before urxvt does focus
261     out processing.
262     .ie n .IP "on_view_change $term\fR, \f(CW$offset" 4
263     .el .IP "on_view_change \f(CW$term\fR, \f(CW$offset\fR" 4
264     .IX Item "on_view_change $term, $offset"
265     Called whenever the view offset changes, i..e the user or program
266     scrolls. Offset \f(CW0\fR means display the normal terminal, positive values
267     show this many lines of scrollback.
268     .ie n .IP "on_scroll_back $term\fR, \f(CW$lines\fR, \f(CW$saved" 4
269     .el .IP "on_scroll_back \f(CW$term\fR, \f(CW$lines\fR, \f(CW$saved\fR" 4
270     .IX Item "on_scroll_back $term, $lines, $saved"
271     Called whenever lines scroll out of the terminal area into the scrollback
272     buffer. \f(CW$lines\fR is the number of lines scrolled out and may be larger
273     than the scroll back buffer or the terminal.
274     .Sp
275     It is called before lines are scrolled out (so rows 0 .. min ($lines \- 1,
276     \&\f(CW$nrow\fR \- 1) represent the lines to be scrolled out). \f(CW$saved\fR is the total
277     number of lines that will be in the scrollback buffer.
278     .ie n .IP "on_tty_activity $term *NYI*" 4
279     .el .IP "on_tty_activity \f(CW$term\fR *NYI*" 4
280     .IX Item "on_tty_activity $term *NYI*"
281     Called whenever the program(s) running in the urxvt window send output.
282     .ie n .IP "on_refresh_begin $term" 4
283     .el .IP "on_refresh_begin \f(CW$term\fR" 4
284     .IX Item "on_refresh_begin $term"
285     Called just before the screen gets redrawn. Can be used for overlay
286     or similar effects by modify terminal contents in refresh_begin, and
287     restoring them in refresh_end. The built-in overlay and selection display
288     code is run after this hook, and takes precedence.
289     .ie n .IP "on_refresh_end $term" 4
290     .el .IP "on_refresh_end \f(CW$term\fR" 4
291     .IX Item "on_refresh_end $term"
292     Called just after the screen gets redrawn. See \f(CW\*(C`on_refresh_begin\*(C'\fR.
293 root 1.5 .ie n .IP "on_keyboard_command $term\fR, \f(CW$string" 4
294     .el .IP "on_keyboard_command \f(CW$term\fR, \f(CW$string\fR" 4
295     .IX Item "on_keyboard_command $term, $string"
296     Called whenever the user presses a key combination that has a
297     \&\f(CW\*(C`perl:string\*(C'\fR action bound to it (see description of the \fBkeysym\fR
298     resource in the @@RXVT_NAME@@(1) manpage).
299 root 1.1 .ie n .Sh "Functions in the ""urxvt"" Package"
300     .el .Sh "Functions in the \f(CWurxvt\fP Package"
301     .IX Subsection "Functions in the urxvt Package"
302     .ie n .IP "urxvt::fatal $errormessage" 4
303     .el .IP "urxvt::fatal \f(CW$errormessage\fR" 4
304     .IX Item "urxvt::fatal $errormessage"
305     Fatally aborts execution with the given error message. Avoid at all
306     costs! The only time this is acceptable is when the terminal process
307     starts up.
308     .ie n .IP "urxvt::warn $string" 4
309     .el .IP "urxvt::warn \f(CW$string\fR" 4
310     .IX Item "urxvt::warn $string"
311 root 1.3 Calls \f(CW\*(C`rxvt_warn\*(C'\fR with the given string which should not include a
312 root 1.1 newline. The module also overwrites the \f(CW\*(C`warn\*(C'\fR builtin with a function
313     that calls this function.
314     .Sp
315     Using this function has the advantage that its output ends up in the
316     correct place, e.g. on stderr of the connecting urxvtc client.
317     .IP "$time = urxvt::NOW" 4
318     .IX Item "$time = urxvt::NOW"
319     Returns the \*(L"current time\*(R" (as per the event loop).
320     .ie n .Sh "The ""urxvt::term"" Class"
321     .el .Sh "The \f(CWurxvt::term\fP Class"
322     .IX Subsection "The urxvt::term Class"
323 root 1.2 .ie n .IP "$value = $term\fR\->resource ($name[, \f(CW$newval])" 4
324     .el .IP "$value = \f(CW$term\fR\->resource ($name[, \f(CW$newval\fR])" 4
325     .IX Item "$value = $term->resource ($name[, $newval])"
326     Returns the current resource value associated with a given name and
327     optionally sets a new value. Setting values is most useful in the \f(CW\*(C`init\*(C'\fR
328     hook. Unset resources are returned and accepted as \f(CW\*(C`undef\*(C'\fR.
329     .Sp
330     The new value must be properly encoded to a suitable character encoding
331     before passing it to this method. Similarly, the returned value may need
332     to be converted from the used encoding to text.
333     .Sp
334     Resource names are as defined in \fIsrc/rsinc.h\fR. Colours can be specified
335     as resource names of the form \f(CW\*(C`color+<index>\*(C'\fR, e.g. \f(CW\*(C`color+5\*(C'\fR. (will
336     likely change).
337     .Sp
338     Please note that resource strings will currently only be freed when the
339     terminal is destroyed, so changing options frequently will eat memory.
340     .Sp
341     Here is a a likely non-exhaustive list of resource names, not all of which
342     are supported in every build, please see the source to see the actual
343     list:
344     .Sp
345     .Vb 12
346     \& answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
347     \& borderLess color cursorBlink cursorUnderline cutchars delete_key
348     \& display_name embed ext_bwidth fade font geometry hold iconName
349     \& imFont imLocale inputMethod insecure int_bwidth intensityStyles
350 root 1.4 \& italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
351     \& mouseWheelScrollPage name pastableTabs path perl_eval perl_ext
352 root 1.3 \& perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
353     \& reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
354     \& scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
355     \& scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
356     \& shade term_name title transparent transparent_all tripleclickwords
357     \& utmpInhibit visualBell
358 root 1.2 .Ve
359 root 1.1 .ie n .IP "($row, $col\fR) = \f(CW$term\fR\->selection_mark ([$row, \f(CW$col])" 4
360     .el .IP "($row, \f(CW$col\fR) = \f(CW$term\fR\->selection_mark ([$row, \f(CW$col\fR])" 4
361     .IX Item "($row, $col) = $term->selection_mark ([$row, $col])"
362     .PD 0
363     .ie n .IP "($row, $col\fR) = \f(CW$term\fR\->selection_beg ([$row, \f(CW$col])" 4
364     .el .IP "($row, \f(CW$col\fR) = \f(CW$term\fR\->selection_beg ([$row, \f(CW$col\fR])" 4
365     .IX Item "($row, $col) = $term->selection_beg ([$row, $col])"
366     .ie n .IP "($row, $col\fR) = \f(CW$term\fR\->selection_end ([$row, \f(CW$col])" 4
367     .el .IP "($row, \f(CW$col\fR) = \f(CW$term\fR\->selection_end ([$row, \f(CW$col\fR])" 4
368     .IX Item "($row, $col) = $term->selection_end ([$row, $col])"
369     .PD
370     Return the current values of the selection mark, begin or end positions,
371     and optionally set them to new values.
372     .ie n .IP "$success = $term\->selection_grab ($eventtime)" 4
373     .el .IP "$success = \f(CW$term\fR\->selection_grab ($eventtime)" 4
374     .IX Item "$success = $term->selection_grab ($eventtime)"
375     Try to request the primary selection from the server (for example, as set
376     by the next method).
377     .ie n .IP "$oldtext = $term\->selection ([$newtext])" 4
378     .el .IP "$oldtext = \f(CW$term\fR\->selection ([$newtext])" 4
379     .IX Item "$oldtext = $term->selection ([$newtext])"
380     Return the current selection text and optionally replace it by \f(CW$newtext\fR.
381     .ie n .IP "$term\->scr_overlay ($x, $y\fR, \f(CW$text)" 4
382     .el .IP "$term\->scr_overlay ($x, \f(CW$y\fR, \f(CW$text\fR)" 4
383     .IX Item "$term->scr_overlay ($x, $y, $text)"
384     Create a simple multi-line overlay box. See the next method for details.
385     .ie n .IP "$term\->scr_overlay_new ($x, $y\fR, \f(CW$width\fR, \f(CW$height)" 4
386     .el .IP "$term\->scr_overlay_new ($x, \f(CW$y\fR, \f(CW$width\fR, \f(CW$height\fR)" 4
387     .IX Item "$term->scr_overlay_new ($x, $y, $width, $height)"
388     Create a new (empty) overlay at the given position with the given
389     width/height. A border will be put around the box. If either \f(CW$x\fR or
390     \&\f(CW$y\fR is negative, then this is counted from the right/bottom side,
391     respectively.
392     .IP "$term\->scr_overlay_off" 4
393     .IX Item "$term->scr_overlay_off"
394     Switch the overlay off again.
395     .ie n .IP "$term\->scr_overlay_set_char ($x, $y\fR, \f(CW$char\fR, \f(CW$rend = \s-1OVERLAY_RSTYLE\s0)" 4
396     .el .IP "$term\->scr_overlay_set_char ($x, \f(CW$y\fR, \f(CW$char\fR, \f(CW$rend\fR = \s-1OVERLAY_RSTYLE\s0)" 4
397     .IX Item "$term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE)"
398     Put a single character (specified numerically) at the given overlay
399     position.
400     .ie n .IP "$term\->scr_overlay_set ($x, $y\fR, \f(CW$text)" 4
401     .el .IP "$term\->scr_overlay_set ($x, \f(CW$y\fR, \f(CW$text\fR)" 4
402     .IX Item "$term->scr_overlay_set ($x, $y, $text)"
403     Write a string at the given position into the overlay.
404 root 1.3 .ie n .IP "$cellwidth = $term\fR\->strwidth \f(CW$string" 4
405     .el .IP "$cellwidth = \f(CW$term\fR\->strwidth \f(CW$string\fR" 4
406     .IX Item "$cellwidth = $term->strwidth $string"
407     Returns the number of screen-cells this string would need. Correctly
408     accounts for wide and combining characters.
409     .ie n .IP "$octets = $term\fR\->locale_encode \f(CW$string" 4
410     .el .IP "$octets = \f(CW$term\fR\->locale_encode \f(CW$string\fR" 4
411     .IX Item "$octets = $term->locale_encode $string"
412     Convert the given text string into the corresponding locale encoding.
413     .ie n .IP "$string = $term\fR\->locale_decode \f(CW$octets" 4
414     .el .IP "$string = \f(CW$term\fR\->locale_decode \f(CW$octets\fR" 4
415     .IX Item "$string = $term->locale_decode $octets"
416     Convert the given locale-encoded octets into a perl string.
417     .IP "$term\->tt_write ($octets)" 4
418     .IX Item "$term->tt_write ($octets)"
419     Write the octets given in \f(CW$data\fR to the tty (i.e. as program input). To
420 root 1.6 pass characters instead of octets, you should convert your strings first
421     to the locale-specific encoding using \f(CW\*(C`$term\->locale_encode\*(C'\fR.
422     .ie n .IP "$nrow = $term\->nrow" 4
423     .el .IP "$nrow = \f(CW$term\fR\->nrow" 4
424     .IX Item "$nrow = $term->nrow"
425     .PD 0
426     .ie n .IP "$ncol = $term\->ncol" 4
427     .el .IP "$ncol = \f(CW$term\fR\->ncol" 4
428     .IX Item "$ncol = $term->ncol"
429     .PD
430     Return the number of rows/columns of the terminal window (i.e. as
431     specified by \f(CW\*(C`\-geometry\*(C'\fR, excluding any scrollback).
432     .ie n .IP "$nsaved = $term\->nsaved" 4
433     .el .IP "$nsaved = \f(CW$term\fR\->nsaved" 4
434     .IX Item "$nsaved = $term->nsaved"
435     Returns the number of lines in the scrollback buffer.
436     .ie n .IP "$view_start = $term\->view_start ([$newvalue])" 4
437     .el .IP "$view_start = \f(CW$term\fR\->view_start ([$newvalue])" 4
438     .IX Item "$view_start = $term->view_start ([$newvalue])"
439     Returns the negative row number of the topmost line. Minimum value is
440     \&\f(CW0\fR, which displays the normal terminal contents. Larger values scroll
441     this many lines into the scrollback buffer.
442     .IP "$term\->want_refresh" 4
443     .IX Item "$term->want_refresh"
444     Requests a screen refresh. At the next opportunity, rxvt-unicode will
445     compare the on-screen display with its stored representation. If they
446     differ, it redraws the differences.
447     .Sp
448     Used after changing terminal contents to display them.
449     .ie n .IP "$text = $term\fR\->ROW_t ($row_number[, \f(CW$new_text\fR[, \f(CW$start_col]])" 4
450     .el .IP "$text = \f(CW$term\fR\->ROW_t ($row_number[, \f(CW$new_text\fR[, \f(CW$start_col\fR]])" 4
451     .IX Item "$text = $term->ROW_t ($row_number[, $new_text[, $start_col]])"
452     Returns the text of the entire row with number \f(CW$row_number\fR. Row \f(CW0\fR
453     is the topmost terminal line, row \f(CW\*(C`$term\->$ncol\-1\*(C'\fR is the bottommost
454     terminal line. The scrollback buffer starts at line \f(CW\*(C`\-1\*(C'\fR and extends to
455     line \f(CW\*(C`\-$term\->nsaved\*(C'\fR.
456     .Sp
457     If \f(CW$new_text\fR is specified, it will replace characters in the current
458     line, starting at column \f(CW$start_col\fR (default \f(CW0\fR), which is useful
459     to replace only parts of a line. The font iindex in the rendition will
460     automatically be updated.
461     .Sp
462     \&\f(CW$text\fR is in a special encoding: tabs and wide characters that use more
463     than one cell when displayed are padded with urxvt::NOCHAR characters
464     (\f(CW\*(C`chr 65535\*(C'\fR). Characters with combining characters and other characters
465     that do not fit into the normal tetx encoding will be replaced with
466     characters in the private use area.
467     .Sp
468     You have to obey this encoding when changing text. The advantage is
469     that \f(CW\*(C`substr\*(C'\fR and similar functions work on screen cells and not on
470     characters.
471     .Sp
472     The methods \f(CW\*(C`$term\->special_encode\*(C'\fR and \f(CW\*(C`$term\->special_decode\*(C'\fR
473     can be used to convert normal strings into this encoding and vice versa.
474     .ie n .IP "$rend = $term\fR\->ROW_r ($row_number[, \f(CW$new_rend\fR[, \f(CW$start_col]])" 4
475     .el .IP "$rend = \f(CW$term\fR\->ROW_r ($row_number[, \f(CW$new_rend\fR[, \f(CW$start_col\fR]])" 4
476     .IX Item "$rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])"
477     Like \f(CW\*(C`$term\->ROW_t\*(C'\fR, but returns an arrayref with rendition
478     bitsets. Rendition bitsets contain information about colour, font, font
479     styles and similar information. See also \f(CW\*(C`$term\->ROW_t\*(C'\fR.
480     .Sp
481     When setting rendition, the font mask will be ignored.
482     .Sp
483     See the section on \s-1RENDITION\s0, below.
484     .ie n .IP "$length = $term\fR\->ROW_l ($row_number[, \f(CW$new_length])" 4
485     .el .IP "$length = \f(CW$term\fR\->ROW_l ($row_number[, \f(CW$new_length\fR])" 4
486     .IX Item "$length = $term->ROW_l ($row_number[, $new_length])"
487     Returns the number of screen cells that are in use (\*(L"the line length\*(R"). If
488     it is \f(CW\*(C`\-1\*(C'\fR, then the line is part of a multiple-row logical \*(L"line\*(R", which
489     means all characters are in use and it is continued on the next row.
490     .ie n .IP "$text = $term\fR\->special_encode \f(CW$string" 4
491     .el .IP "$text = \f(CW$term\fR\->special_encode \f(CW$string\fR" 4
492     .IX Item "$text = $term->special_encode $string"
493     Converts a perl string into the special encoding used by rxvt\-unicode,
494     where one character corresponds to one screen cell. See
495     \&\f(CW\*(C`$term\->ROW_t\*(C'\fR for details.
496     .ie n .IP "$string = $term\fR\->special_decode \f(CW$text" 4
497     .el .IP "$string = \f(CW$term\fR\->special_decode \f(CW$text\fR" 4
498     .IX Item "$string = $term->special_decode $text"
499     Converts rxvt-unicodes text reprsentation into a perl string. See
500     \&\f(CW\*(C`$term\->ROW_t\*(C'\fR for details.
501     .Sh "\s-1RENDITION\s0"
502     .IX Subsection "RENDITION"
503     Rendition bitsets contain information about colour, font, font styles and
504     similar information for each screen cell.
505     .PP
506     The following \*(L"macros\*(R" deal with changes in rendition sets. You should
507     never just create a bitset, you should always modify an existing one,
508     as they contain important information required for correct operation of
509     rxvt\-unicode.
510     .IP "$rend = urxvt::DEFAULT_RSTYLE" 4
511     .IX Item "$rend = urxvt::DEFAULT_RSTYLE"
512     Returns the default rendition, as used when the terminal is starting up or
513     being reset. Useful as a base
514 root 1.1 .ie n .Sh "The ""urxvt::timer"" Class"
515     .el .Sh "The \f(CWurxvt::timer\fP Class"
516     .IX Subsection "The urxvt::timer Class"
517     This class implements timer watchers/events. Time is represented as a
518     fractional number of seconds since the epoch. Example:
519     .PP
520     .Vb 11
521     \& # create a digital clock display in upper right corner
522     \& $term->{timer} = urxvt::timer
523     \& ->new
524     \& ->start (urxvt::NOW)
525     \& ->cb (sub {
526     \& my ($timer) = @_;
527     \& my $time = $timer->at;
528     \& $timer->start ($time + 1);
529     \& $self->scr_overlay (-1, 0,
530     \& POSIX::strftime "%H:%M:%S", localtime $time);
531     \& });
532     .Ve
533     .IP "$timer = new urxvt::timer" 4
534     .IX Item "$timer = new urxvt::timer"
535     Create a new timer object in stopped state.
536     .ie n .IP "$timer = $timer\fR\->cb (sub { my ($timer) = \f(CW@_; ... })" 4
537     .el .IP "$timer = \f(CW$timer\fR\->cb (sub { my ($timer) = \f(CW@_\fR; ... })" 4
538     .IX Item "$timer = $timer->cb (sub { my ($timer) = @_; ... })"
539     Set the callback to be called when the timer triggers.
540     .ie n .IP "$tstamp = $timer\->at" 4
541     .el .IP "$tstamp = \f(CW$timer\fR\->at" 4
542     .IX Item "$tstamp = $timer->at"
543     Return the time this watcher will fire next.
544     .ie n .IP "$timer = $timer\->set ($tstamp)" 4
545     .el .IP "$timer = \f(CW$timer\fR\->set ($tstamp)" 4
546     .IX Item "$timer = $timer->set ($tstamp)"
547     Set the time the event is generated to \f(CW$tstamp\fR.
548     .ie n .IP "$timer = $timer\->start" 4
549     .el .IP "$timer = \f(CW$timer\fR\->start" 4
550     .IX Item "$timer = $timer->start"
551     Start the timer.
552     .ie n .IP "$timer = $timer\->start ($tstamp)" 4
553     .el .IP "$timer = \f(CW$timer\fR\->start ($tstamp)" 4
554     .IX Item "$timer = $timer->start ($tstamp)"
555     Set the event trigger time to \f(CW$tstamp\fR and start the timer.
556     .ie n .IP "$timer = $timer\->stop" 4
557     .el .IP "$timer = \f(CW$timer\fR\->stop" 4
558     .IX Item "$timer = $timer->stop"
559     Stop the timer.
560     .ie n .Sh "The ""urxvt::iow"" Class"
561     .el .Sh "The \f(CWurxvt::iow\fP Class"
562     .IX Subsection "The urxvt::iow Class"
563     This class implements io watchers/events. Example:
564     .PP
565     .Vb 12
566     \& $term->{socket} = ...
567     \& $term->{iow} = urxvt::iow
568     \& ->new
569     \& ->fd (fileno $term->{socket})
570     \& ->events (1) # wait for read data
571     \& ->start
572     \& ->cb (sub {
573     \& my ($iow, $revents) = @_;
574     \& # $revents must be 1 here, no need to check
575     \& sysread $term->{socket}, my $buf, 8192
576     \& or end-of-file;
577     \& });
578     .Ve
579     .IP "$iow = new urxvt::iow" 4
580     .IX Item "$iow = new urxvt::iow"
581     Create a new io watcher object in stopped state.
582     .ie n .IP "$iow = $iow\fR\->cb (sub { my ($iow, \f(CW$reventmask\fR) = \f(CW@_; ... })" 4
583     .el .IP "$iow = \f(CW$iow\fR\->cb (sub { my ($iow, \f(CW$reventmask\fR) = \f(CW@_\fR; ... })" 4
584     .IX Item "$iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })"
585     Set the callback to be called when io events are triggered. \f(CW$reventmask\fR
586     is a bitset as described in the \f(CW\*(C`events\*(C'\fR method.
587     .ie n .IP "$iow = $iow\->fd ($fd)" 4
588     .el .IP "$iow = \f(CW$iow\fR\->fd ($fd)" 4
589     .IX Item "$iow = $iow->fd ($fd)"
590     Set the filedescriptor (not handle) to watch.
591     .ie n .IP "$iow = $iow\->events ($eventmask)" 4
592     .el .IP "$iow = \f(CW$iow\fR\->events ($eventmask)" 4
593     .IX Item "$iow = $iow->events ($eventmask)"
594     Set the event mask to watch. Bit #0 (value \f(CW1\fR) enables watching for read
595     data, Bit #1 (value \f(CW2\fR) enables watching for write data.
596     .ie n .IP "$iow = $iow\->start" 4
597     .el .IP "$iow = \f(CW$iow\fR\->start" 4
598     .IX Item "$iow = $iow->start"
599     Start watching for requested events on the given handle.
600     .ie n .IP "$iow = $iow\->stop" 4
601     .el .IP "$iow = \f(CW$iow\fR\->stop" 4
602     .IX Item "$iow = $iow->stop"
603     Stop watching for events on the given filehandle.
604 root 1.2 .SH "ENVIRONMENT"
605     .IX Header "ENVIRONMENT"
606     .Sh "\s-1URXVT_PERL_VERBOSITY\s0"
607     .IX Subsection "URXVT_PERL_VERBOSITY"
608     This variable controls the verbosity level of the perl extension. Higher
609     numbers indicate more verbose output.
610     .IP "0 \- only fatal messages" 4
611     .IX Item "0 - only fatal messages"
612     .PD 0
613     .IP "3 \- script loading and management" 4
614     .IX Item "3 - script loading and management"
615     .IP "10 \- all events received" 4
616     .IX Item "10 - all events received"
617     .PD
618 root 1.1 .SH "AUTHOR"
619     .IX Header "AUTHOR"
620     .Vb 2
621     \& Marc Lehmann <pcg@goof.com>
622     \& http://software.schmorp.de/pkg/rxvt-unicode
623     .Ve