ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/rxvt-unicode/doc/rxvtperl.3.txt
(Generate patch)

Comparing rxvt-unicode/doc/rxvtperl.3.txt (file contents):
Revision 1.6 by root, Tue Jan 3 04:20:37 2006 UTC vs.
Revision 1.14 by root, Sun Jan 8 06:35:38 2006 UTC

… …
12 # start a rxvt using it: 12 # start a rxvt using it:
13 13
14 rxvt --perl-lib $HOME -pe grab_test 14 rxvt --perl-lib $HOME -pe grab_test
15 15
16DESCRIPTION 16DESCRIPTION
17 Everytime a terminal object gets created, scripts specified via the 17 Everytime a terminal object gets created, extension scripts specified
18 "perl" resource are loaded and associated with it. 18 via the "perl" resource are loaded and associated with it.
19 19
20 Scripts are compiled in a 'use strict' and 'use utf8' environment, and 20 Scripts are compiled in a 'use strict' and 'use utf8' environment, and
21 thus must be encoded as UTF-8. 21 thus must be encoded as UTF-8.
22 22
23 Each script will only ever be loaded once, even in rxvtd, where scripts 23 Each script will only ever be loaded once, even in rxvtd, where scripts
… …
29 29
30 You can activate them like this: 30 You can activate them like this:
31 31
32 rxvt -pe <extensionname> 32 rxvt -pe <extensionname>
33 33
34 selection 34 selection (enabled by default)
35 Miscellaneous selection modifications. 35 Intelligent selection. This extension tries to be more intelligent
36 when the user extends selections (double-click). Right now, it tries
37 to select urls and complete shell-quoted arguments, which is very
38 convenient, too, if your ls supports "--quoting-style=shell".
39
40 It also offers the following bindable event:
36 41
37 rot13 42 rot13
38 Rot-13 the selection when activated. Used via keyboard trigger: 43 Rot-13 the selection when activated. Used via keyboard trigger:
39 44
40 URxvt.keysym.C-M-r: perl:selection:rot13 45 URxvt.keysym.C-M-r: perl:selection:rot13
41 46
47 option-popup (enabled by default)
48 Binds a popup menu to Ctrl-Button3 that lets you toggle (some)
49 options at runtime.
50
42 digital-clock 51 digital-clock
43 Displays a digital clock using the built-in overlay. 52 Displays a digital clock using the built-in overlay.
53
54 mark-urls
55 Uses per-line display filtering ("on_line_update") to underline
56 urls.
57
58 block-graphics-to-ascii
59 A not very useful example of filtering all text output to the
60 terminal, by replacing all line-drawing characters (U+2500 ..
61 U+259F) by a similar-looking ascii character.
44 62
45 example-refresh-hooks 63 example-refresh-hooks
46 Displays a very simple digital clock in the upper right corner of 64 Displays a very simple digital clock in the upper right corner of
47 the window. Illustrates overwriting the refresh callbacks to create 65 the window. Illustrates overwriting the refresh callbacks to create
48 your own overlays or changes. 66 your own overlays or changes.
49 67
50 General API Considerations 68 General API Considerations
51 All objects (such as terminals, time watchers etc.) are typical 69 All objects (such as terminals, time watchers etc.) are typical
52 reference-to-hash objects. The hash can be used to store anything you 70 reference-to-hash objects. The hash can be used to store anything you
53 like. All members starting with an underscore (such as "_ptr" or 71 like. All members starting with an underscore (such as "_ptr" or
54 "_hook") are reserved for internal uses and must not be accessed or 72 "_hook") are reserved for internal uses and MUST NOT be accessed or
55 modified). 73 modified).
56 74
57 When objects are destroyed on the C++ side, the perl object hashes are 75 When objects are destroyed on the C++ side, the perl object hashes are
58 emptied, so its best to store related objects such as time watchers and 76 emptied, so its best to store related objects such as time watchers and
59 the like inside the terminal object so they get destroyed as soon as the 77 the like inside the terminal object so they get destroyed as soon as the
60 terminal is destroyed. 78 terminal is destroyed.
61 79
80 Argument names also often indicate the type of a parameter. Here are
81 some hints on what they mean:
82
83 $text
84 Rxvt-unicodes special way of encoding text, where one "unicode"
85 character always represents one screen cell. See row_t for a
86 discussion of this format.
87
88 $string
89 A perl text string, with an emphasis on *text*. It can store all
90 unicode characters and is to be distinguished with text encoded in a
91 specific encoding (often locale-specific) and binary data.
92
93 $octets
94 Either binary data or - more common - a text string encoded in a
95 locale-specific way.
96
62 Hooks 97 Hooks
63 The following subroutines can be declared in loaded scripts, and will be 98 The following subroutines can be declared in extension files, and will
64 called whenever the relevant event happens. 99 be called whenever the relevant event happens.
100
101 The first argument passed to them is an object private to each terminal
102 and extension package. You can call all "urxvt::term" methods on it, but
103 its not a real "urxvt::term" object. Instead, the real "urxvt::term"
104 object that is shared between all packages is stored in the "term"
105 member. It is, however, blessed intot he package of the extension
106 script, so for all practical purposes you can treat an extension script
107 as a class.
65 108
66 All of them must return a boolean value. If it is true, then the event 109 All of them must return a boolean value. If it is true, then the event
67 counts as being *consumed*, and the invocation of other hooks is 110 counts as being *consumed*, and the invocation of other hooks is
68 skipped, and the relevant action might not be carried out by the C++ 111 skipped, and the relevant action might not be carried out by the C++
69 code. 112 code.
70 113
71 When in doubt, return a false value (preferably "()"). 114 When in doubt, return a false value (preferably "()").
72 115
73 on_init $term 116 on_init $term
74 Called after a new terminal object has been initialized, but before 117 Called after a new terminal object has been initialized, but before
75 windows are created or the command gets run. 118 windows are created or the command gets run. Most methods are unsafe
119 to call or deliver senseless data, as terminal size and other
120 characteristics have not yet been determined. You can safely query
121 and change resources, though.
76 122
77 on_reset $term 123 on_reset $term
78 Called after the screen is "reset" for any reason, such as resizing 124 Called after the screen is "reset" for any reason, such as resizing
79 or control sequences. Here is where you can react on changes to 125 or control sequences. Here is where you can react on changes to
80 size-related variables. 126 size-related variables.
… …
98 queried and changed by calling "$term->selection". 144 queried and changed by calling "$term->selection".
99 145
100 Returning a true value aborts selection grabbing. It will still be 146 Returning a true value aborts selection grabbing. It will still be
101 hilighted. 147 hilighted.
102 148
103 on_focus_in $term 149 on_sel_extend $term
104 Called whenever the window gets the keyboard focus, before urxvt 150 Called whenever the user tries to extend the selection (e.g. with a
105 does focus in processing. 151 double click) and is either supposed to return false (normal
152 operation), or should extend the selection itelf and return true to
153 suppress the built-in processing.
106 154
107 on_focus_out $term 155 See the selection example extension.
108 Called wheneever the window loses keyboard focus, before urxvt does
109 focus out processing.
110 156
111 on_view_change $term, $offset 157 on_view_change $term, $offset
112 Called whenever the view offset changes, i..e the user or program 158 Called whenever the view offset changes, i..e the user or program
113 scrolls. Offset 0 means display the normal terminal, positive values 159 scrolls. Offset 0 means display the normal terminal, positive values
114 show this many lines of scrollback. 160 show this many lines of scrollback.
… …
123 the total number of lines that will be in the scrollback buffer. 169 the total number of lines that will be in the scrollback buffer.
124 170
125 on_tty_activity $term *NYI* 171 on_tty_activity $term *NYI*
126 Called whenever the program(s) running in the urxvt window send 172 Called whenever the program(s) running in the urxvt window send
127 output. 173 output.
174
175 on_osc_seq $term, $string
176 Called whenever the ESC ] 777 ; string ST command sequence (OSC =
177 operating system command) is processed. Cursor position and other
178 state information is up-to-date when this happens. For
179 interoperability, the string should start with the extension name
180 and a colon, to distinguish it from commands for other extensions,
181 and this might be enforced in the future.
182
183 Be careful not ever to trust (in a security sense) the data you
184 receive, as its source can not easily be controleld (e-mail content,
185 messages from other users on the same system etc.).
186
187 on_add_lines $term, $string
188 Called whenever text is about to be output, with the text as
189 argument. You can filter/change and output the text yourself by
190 returning a true value and calling "$term->scr_add_lines" yourself.
191 Please note that this might be very slow, however, as your hook is
192 called for all text being output.
193
194 on_line_update $term, $row
195 Called whenever a line was updated or changed. Can be used to filter
196 screen output (e.g. underline urls or other useless stuff). Only
197 lines that are being shown will be filtered, and, due to performance
198 reasons, not always immediately.
199
200 The row number is always the topmost row of the line if the line
201 spans multiple rows.
202
203 Please note that, if you change the line, then the hook might get
204 called later with the already-modified line (e.g. if unrelated parts
205 change), so you cannot just toggle rendition bits, but only set
206 them.
128 207
129 on_refresh_begin $term 208 on_refresh_begin $term
130 Called just before the screen gets redrawn. Can be used for overlay 209 Called just before the screen gets redrawn. Can be used for overlay
131 or similar effects by modify terminal contents in refresh_begin, and 210 or similar effects by modify terminal contents in refresh_begin, and
132 restoring them in refresh_end. The built-in overlay and selection 211 restoring them in refresh_end. The built-in overlay and selection
… …
138 on_keyboard_command $term, $string 217 on_keyboard_command $term, $string
139 Called whenever the user presses a key combination that has a 218 Called whenever the user presses a key combination that has a
140 "perl:string" action bound to it (see description of the keysym 219 "perl:string" action bound to it (see description of the keysym
141 resource in the rxvt(1) manpage). 220 resource in the rxvt(1) manpage).
142 221
222 on_focus_in $term
223 Called whenever the window gets the keyboard focus, before
224 rxvt-unicode does focus in processing.
225
226 on_focus_out $term
227 Called wheneever the window loses keyboard focus, before
228 rxvt-unicode does focus out processing.
229
230 on_key_press $term, $event, $octets
231 on_key_release $term, $event
232 on_button_press $term, $event
233 on_button_release $term, $event
234 on_motion_notify $term, $event
235 on_map_notify $term, $event
236 on_unmap_notify $term, $event
237 Called whenever the corresponding X event is received for the
238 terminal If the hook returns true, then the even will be ignored by
239 rxvt-unicode.
240
241 The event is a hash with most values as named by Xlib (see the
242 XEvent manpage), with the additional members "row" and "col", which
243 are the row and column under the mouse cursor.
244
245 "on_key_press" additionally receives the string rxvt-unicode would
246 output, if any, in locale-specific encoding.
247
248 subwindow.
249
250 Variables in the "urxvt" Package
251 $urxvt::TERM
252 The current terminal. This variable stores the current "urxvt::term"
253 object, whenever a callback/hook is executing.
254
143 Functions in the "urxvt" Package 255 Functions in the "urxvt" Package
256 $term = new urxvt [arg...]
257 Creates a new terminal, very similar as if you had started it with
258 "system $binfile, arg...". Croaks (and probably outputs an error
259 message) if the new instance couldn't be created. Returns "undef" if
260 the new instance didn't initialise perl, and the terminal object
261 otherwise. The "init" and "start" hooks will be called during the
262 call.
263
144 urxvt::fatal $errormessage 264 urxvt::fatal $errormessage
145 Fatally aborts execution with the given error message. Avoid at all 265 Fatally aborts execution with the given error message. Avoid at all
146 costs! The only time this is acceptable is when the terminal process 266 costs! The only time this is acceptable is when the terminal process
147 starts up. 267 starts up.
148 268
… …
155 correct place, e.g. on stderr of the connecting urxvtc client. 275 correct place, e.g. on stderr of the connecting urxvtc client.
156 276
157 $time = urxvt::NOW 277 $time = urxvt::NOW
158 Returns the "current time" (as per the event loop). 278 Returns the "current time" (as per the event loop).
159 279
280 urxvt::CurrentTime
281 urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask,
282 Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask,
283 Button5Mask, AnyModifier
284 Various constants for use in X calls and event processing.
285
160 RENDITION 286 RENDITION
161 Rendition bitsets contain information about colour, font, font styles 287 Rendition bitsets contain information about colour, font, font styles
162 and similar information for each screen cell. 288 and similar information for each screen cell.
163 289
164 The following "macros" deal with changes in rendition sets. You should 290 The following "macros" deal with changes in rendition sets. You should
… …
194 initially zero. 320 initially zero.
195 321
196 $rend = urxvt::SET_CUSTOM ($rend, $new_value) 322 $rend = urxvt::SET_CUSTOM ($rend, $new_value)
197 Change the custom value. 323 Change the custom value.
198 324
325 The "urxvt::anyevent" Class
326 The sole purpose of this class is to deliver an interface to the
327 "AnyEvent" module - any module using it will work inside urxvt without
328 further work. The only exception is that you cannot wait on condition
329 variables, but non-blocking condvar use is ok. What this means is that
330 you cannot use blocking APIs, but the non-blocking variant should work.
331
199 The "urxvt::term" Class 332 The "urxvt::term" Class
333 $term->destroy
334 Destroy the terminal object (close the window, free resources etc.).
335
336 $isset = $term->option ($optval[, $set])
337 Returns true if the option specified by $optval is enabled, and
338 optionally change it. All option values are stored by name in the
339 hash %urxvt::OPTION. Options not enabled in this binary are not in
340 the hash.
341
342 Here is a a likely non-exhaustive list of option names, please see
343 the source file /src/optinc.h to see the actual list:
344
345 borderLess console cursorBlink cursorUnderline hold iconic insecure
346 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
347 pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating
348 scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer
349 secondaryScreen secondaryScroll skipBuiltinGlyphs transparent
350 tripleclickwords utmpInhibit visualBell
351
200 $value = $term->resource ($name[, $newval]) 352 $value = $term->resource ($name[, $newval])
201 Returns the current resource value associated with a given name and 353 Returns the current resource value associated with a given name and
202 optionally sets a new value. Setting values is most useful in the 354 optionally sets a new value. Setting values is most useful in the
203 "init" hook. Unset resources are returned and accepted as "undef". 355 "init" hook. Unset resources are returned and accepted as "undef".
204 356
… …
213 Please note that resource strings will currently only be freed when 365 Please note that resource strings will currently only be freed when
214 the terminal is destroyed, so changing options frequently will eat 366 the terminal is destroyed, so changing options frequently will eat
215 memory. 367 memory.
216 368
217 Here is a a likely non-exhaustive list of resource names, not all of 369 Here is a a likely non-exhaustive list of resource names, not all of
218 which are supported in every build, please see the source to see the 370 which are supported in every build, please see the source file
219 actual list: 371 /src/rsinc.h to see the actual list:
220 372
221 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 373 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
222 borderLess color cursorBlink cursorUnderline cutchars delete_key 374 borderLess color cursorBlink cursorUnderline cutchars delete_key
223 display_name embed ext_bwidth fade font geometry hold iconName 375 display_name embed ext_bwidth fade font geometry hold iconName
224 imFont imLocale inputMethod insecure int_bwidth intensityStyles 376 imFont imLocale inputMethod insecure int_bwidth intensityStyles
225 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier 377 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
226 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext 378 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2
227 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 379 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
228 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 380 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
229 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 381 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
230 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 382 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
231 shade term_name title transparent transparent_all tripleclickwords 383 shade term_name title transparent transparent_all tripleclickwords
232 utmpInhibit visualBell 384 utmpInhibit visualBell
233 385
386 $rend = $term->rstyle ([$new_rstyle])
387 Return and optionally change the current rendition. Text that is
388 output by the terminal application will use this style.
389
390 ($row, $col) = $term->screen_cur ([$row, $col])
391 Return the current coordinates of the text cursor position and
392 optionally set it (which is usually bad as applications don't expect
393 that).
394
234 ($row, $col) = $term->selection_mark ([$row, $col]) 395 ($row, $col) = $term->selection_mark ([$row, $col])
235 ($row, $col) = $term->selection_beg ([$row, $col]) 396 ($row, $col) = $term->selection_beg ([$row, $col])
236 ($row, $col) = $term->selection_end ([$row, $col]) 397 ($row, $col) = $term->selection_end ([$row, $col])
237 Return the current values of the selection mark, begin or end 398 Return the current values of the selection mark, begin or end
238 positions, and optionally set them to new values. 399 positions, and optionally set them to new values.
… …
244 $oldtext = $term->selection ([$newtext]) 405 $oldtext = $term->selection ([$newtext])
245 Return the current selection text and optionally replace it by 406 Return the current selection text and optionally replace it by
246 $newtext. 407 $newtext.
247 408
248 #=item $term->overlay ($x, $y, $text) # #Create a simple multi-line 409 #=item $term->overlay ($x, $y, $text) # #Create a simple multi-line
249 overlay box. See the next method for details. # #=cut 410 overlay box. See the next method for details. # #=cut # #sub
250
251 sub urxvt::term::scr_overlay { die; my ($self, $x, $y, $text) = @_; 411 urxvt::term::scr_overlay { # my ($self, $x, $y, $text) = @_; # # my
252 412 @lines = split /\n/, $text; # # my $w = 0; # for (map
253 my @lines = split /\n/, $text; 413 $self->strwidth ($_), @lines) { # $w = $_ if $w < $_; # } # #
254
255 my $w = 0;
256 for (map $self->strwidth ($_), @lines) {
257 $w = $_ if $w < $_;
258 }
259
260 $self->scr_overlay_new ($x, $y, $w, scalar @lines); 414 $self->scr_overlay_new ($x, $y, $w, scalar @lines); #
261 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 415 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; #}
262 }
263 416
264 $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 417 $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
265 Create a new (empty) overlay at the given position with the given 418 Create a new (empty) overlay at the given position with the given
266 width/height. $rstyle defines the initial rendition style (default: 419 width/height. $rstyle defines the initial rendition style (default:
267 "OVERLAY_RSTYLE"). 420 "OVERLAY_RSTYLE").
… …
273 right/bottom side, respectively. 426 right/bottom side, respectively.
274 427
275 This method returns an urxvt::overlay object. The overlay will be 428 This method returns an urxvt::overlay object. The overlay will be
276 visible as long as the perl object is referenced. 429 visible as long as the perl object is referenced.
277 430
278 Currently, the only method on the "urxvt::overlay" object is "set": 431 The methods currently supported on "urxvt::overlay" objects are:
279 432
280 $overlay->set ($x, $y, $text, $rend) 433 $overlay->set ($x, $y, $text, $rend)
281 Similar to "$term->ROW_t" and "$term->ROW_r" in that it puts text in 434 Similar to "$term->ROW_t" and "$term->ROW_r" in that it puts
282 rxvt-unicode's special encoding and an array of rendition values at 435 text in rxvt-unicode's special encoding and an array of
283 a specific position inside the overlay. 436 rendition values at a specific position inside the overlay.
284 437
438 $overlay->hide
439 If visible, hide the overlay, but do not destroy it.
440
441 $overlay->show
442 If hidden, display the overlay again.
443
444 $popup = $term->popup ($event)
445 Creates a new "urxvt::popup" object that implements a popup menu.
446 The $event *must* be the event causing the menu to pop up (a button
447 event, currently).
448
285 $cellwidth = $term->strwidth $string 449 $cellwidth = $term->strwidth ($string)
286 Returns the number of screen-cells this string would need. Correctly 450 Returns the number of screen-cells this string would need. Correctly
287 accounts for wide and combining characters. 451 accounts for wide and combining characters.
288 452
289 $octets = $term->locale_encode $string 453 $octets = $term->locale_encode ($string)
290 Convert the given text string into the corresponding locale 454 Convert the given text string into the corresponding locale
291 encoding. 455 encoding.
292 456
293 $string = $term->locale_decode $octets 457 $string = $term->locale_decode ($octets)
294 Convert the given locale-encoded octets into a perl string. 458 Convert the given locale-encoded octets into a perl string.
459
460 $term->scr_add_lines ($string)
461 Write the given text string to the screen, as if output by the
462 application running inside the terminal. It may not contain command
463 sequences (escape codes), but is free to use line feeds, carriage
464 returns and tabs. The string is a normal text string, not in
465 locale-dependent encoding.
466
467 Normally its not a good idea to use this function, as programs might
468 be confused by changes in cursor position or scrolling. Its useful
469 inside a "on_add_lines" hook, though.
470
471 $term->cmd_parse ($octets)
472 Similar to "scr_add_lines", but the argument must be in the
473 locale-specific encoding of the terminal and can contain command
474 sequences (escape codes) that will be interpreted.
295 475
296 $term->tt_write ($octets) 476 $term->tt_write ($octets)
297 Write the octets given in $data to the tty (i.e. as program input). 477 Write the octets given in $data to the tty (i.e. as program input).
298 To pass characters instead of octets, you should convert your 478 To pass characters instead of octets, you should convert your
299 strings first to the locale-specific encoding using 479 strings first to the locale-specific encoding using
300 "$term->locale_encode". 480 "$term->locale_encode".
301 481
482 $windowid = $term->parent
483 Return the window id of the toplevel window.
484
485 $windowid = $term->vt
486 Return the window id of the terminal window.
487
488 $window_width = $term->width
489 $window_height = $term->height
490 $font_width = $term->fwidth
491 $font_height = $term->fheight
492 $font_ascent = $term->fbase
302 $nrow = $term->nrow 493 $terminal_rows = $term->nrow
303 $ncol = $term->ncol 494 $terminal_columns = $term->ncol
304 Return the number of rows/columns of the terminal window (i.e. as 495 $has_focus = $term->focus
305 specified by "-geometry", excluding any scrollback).
306
307 $nsaved = $term->nsaved 496 $is_mapped = $term->mapped
308 Returns the number of lines in the scrollback buffer. 497 $max_scrollback = $term->saveLines
498 $nrow_plus_saveLines = $term->total_rows
499 $lines_in_scrollback = $term->nsaved
500 Return various integers describing terminal characteristics.
501
502 $modifiermask = $term->ModLevel3Mask
503 $modifiermask = $term->ModMetaMask
504 $modifiermask = $term->ModNumLockMask
505 Return the modifier masks corresponding to the "ISO Level 3 Shift"
506 (often AltGr), the meta key (often Alt) and the num lock key, if
507 applicable.
309 508
310 $view_start = $term->view_start ([$newvalue]) 509 $view_start = $term->view_start ([$newvalue])
311 Returns the negative row number of the topmost line. Minimum value 510 Returns the negative row number of the topmost line. Minimum value
312 is 0, which displays the normal terminal contents. Larger values 511 is 0, which displays the normal terminal contents. Larger values
313 scroll this many lines into the scrollback buffer. 512 scroll this many lines into the scrollback buffer.
… …
321 520
322 $text = $term->ROW_t ($row_number[, $new_text[, $start_col]]) 521 $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
323 Returns the text of the entire row with number $row_number. Row 0 is 522 Returns the text of the entire row with number $row_number. Row 0 is
324 the topmost terminal line, row "$term->$ncol-1" is the bottommost 523 the topmost terminal line, row "$term->$ncol-1" is the bottommost
325 terminal line. The scrollback buffer starts at line -1 and extends 524 terminal line. The scrollback buffer starts at line -1 and extends
326 to line "-$term->nsaved". 525 to line "-$term->nsaved". Nothing will be returned if a nonexistent
526 line is requested.
327 527
328 If $new_text is specified, it will replace characters in the current 528 If $new_text is specified, it will replace characters in the current
329 line, starting at column $start_col (default 0), which is useful to 529 line, starting at column $start_col (default 0), which is useful to
330 replace only parts of a line. The font index in the rendition will 530 replace only parts of a line. The font index in the rendition will
331 automatically be updated. 531 automatically be updated.
… …
352 552
353 See the section on RENDITION, above. 553 See the section on RENDITION, above.
354 554
355 $length = $term->ROW_l ($row_number[, $new_length]) 555 $length = $term->ROW_l ($row_number[, $new_length])
356 Returns the number of screen cells that are in use ("the line 556 Returns the number of screen cells that are in use ("the line
357 length"). If it is -1, then the line is part of a multiple-row 557 length"). Unlike the urxvt core, this returns "$term->ncol" if the
358 logical "line", which means all characters are in use and it is 558 line is joined with the following one.
359 continued on the next row.
360 559
560 $bool = $term->is_longer ($row_number)
561 Returns true if the row is part of a multiple-row logical "line"
562 (i.e. joined with the following row), which means all characters are
563 in use and it is continued on the next row (and possibly a
564 continuation of the previous row(s)).
565
566 $line = $term->line ($row_number)
567 Create and return a new "urxvt::line" object that stores information
568 about the logical line that row $row_number is part of. It supports
569 the following methods:
570
571 $text = $line->t ([$new_text])
572 Returns or replaces the full text of the line, similar to
573 "ROW_t"
574
575 $rend = $line->r ([$new_rend])
576 Returns or replaces the full rendition array of the line,
577 similar to "ROW_r"
578
579 $length = $line->l
580 Returns the length of the line in cells, similar to "ROW_l".
581
582 $rownum = $line->beg
583 $rownum = $line->end
584 Return the row number of the first/last row of the line,
585 respectively.
586
587 $offset = $line->offset_of ($row, $col)
588 Returns the character offset of the given row|col pair within
589 the logical line.
590
591 ($row, $col) = $line->coord_of ($offset)
592 Translates a string offset into terminal coordinates again.
593
594 ($row, $col) = $line->coord_of ($offset) =item $text =
361 $text = $term->special_encode $string 595 $term->special_encode $string
362 Converts a perl string into the special encoding used by 596 Converts a perl string into the special encoding used by
363 rxvt-unicode, where one character corresponds to one screen cell. 597 rxvt-unicode, where one character corresponds to one screen cell.
364 See "$term->ROW_t" for details. 598 See "$term->ROW_t" for details.
365 599
366 $string = $term->special_decode $text 600 $string = $term->special_decode $text
367 Converts rxvt-unicodes text reprsentation into a perl string. See 601 Converts rxvt-unicodes text reprsentation into a perl string. See
368 "$term->ROW_t" for details. 602 "$term->ROW_t" for details.
369 603
604 The "urxvt::popup" Class
370 The "urxvt::timer" Class 605 The "urxvt::timer" Class
371 This class implements timer watchers/events. Time is represented as a 606 This class implements timer watchers/events. Time is represented as
372 fractional number of seconds since the epoch. Example: 607 a fractional number of seconds since the epoch. Example:
373 608
374 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0); 609 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
375 $term->{timer} = urxvt::timer 610 $term->{timer} = urxvt::timer
376 ->new 611 ->new
377 ->interval (1) 612 ->interval (1)
378 ->cb (sub { 613 ->cb (sub {
379 $term->{overlay}->set (0, 0, 614 $term->{overlay}->set (0, 0,
380 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]); 615 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
381 }); 616 });
382 617
383 $timer = new urxvt::timer 618 $timer = new urxvt::timer
384 Create a new timer object in started state. It is scheduled to fire 619 Create a new timer object in started state. It is scheduled to
385 immediately. 620 fire immediately.
386 621
387 $timer = $timer->cb (sub { my ($timer) = @_; ... }) 622 $timer = $timer->cb (sub { my ($timer) = @_; ... })
388 Set the callback to be called when the timer triggers. 623 Set the callback to be called when the timer triggers.
389 624
390 $tstamp = $timer->at 625 $tstamp = $timer->at
391 Return the time this watcher will fire next. 626 Return the time this watcher will fire next.
392 627
393 $timer = $timer->set ($tstamp) 628 $timer = $timer->set ($tstamp)
394 Set the time the event is generated to $tstamp. 629 Set the time the event is generated to $tstamp.
395 630
396 $timer = $timer->interval ($interval) 631 $timer = $timer->interval ($interval)
397 Normally (and when $interval is 0), the timer will automatically 632 Normally (and when $interval is 0), the timer will automatically
398 stop after it has fired once. If $interval is non-zero, then the 633 stop after it has fired once. If $interval is non-zero, then the
399 timer is automatically rescheduled at the given intervals. 634 timer is automatically rescheduled at the given intervals.
400 635
401 $timer = $timer->start 636 $timer = $timer->start
402 Start the timer. 637 Start the timer.
403 638
404 $timer = $timer->start ($tstamp) 639 $timer = $timer->start ($tstamp)
405 Set the event trigger time to $tstamp and start the timer. 640 Set the event trigger time to $tstamp and start the timer.
406 641
407 $timer = $timer->stop 642 $timer = $timer->stop
408 Stop the timer. 643 Stop the timer.
409 644
410 The "urxvt::iow" Class 645 The "urxvt::iow" Class
411 This class implements io watchers/events. Example: 646 This class implements io watchers/events. Example:
412 647
413 $term->{socket} = ... 648 $term->{socket} = ...
414 $term->{iow} = urxvt::iow 649 $term->{iow} = urxvt::iow
415 ->new 650 ->new
416 ->fd (fileno $term->{socket}) 651 ->fd (fileno $term->{socket})
417 ->events (1) # wait for read data 652 ->events (1) # wait for read data
418 ->start 653 ->start
419 ->cb (sub { 654 ->cb (sub {
420 my ($iow, $revents) = @_; 655 my ($iow, $revents) = @_;
421 # $revents must be 1 here, no need to check 656 # $revents must be 1 here, no need to check
422 sysread $term->{socket}, my $buf, 8192 657 sysread $term->{socket}, my $buf, 8192
423 or end-of-file; 658 or end-of-file;
424 }); 659 });
425 660
426 $iow = new urxvt::iow 661 $iow = new urxvt::iow
427 Create a new io watcher object in stopped state. 662 Create a new io watcher object in stopped state.
428 663
429 $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... }) 664 $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
430 Set the callback to be called when io events are triggered. 665 Set the callback to be called when io events are triggered.
431 $reventmask is a bitset as described in the "events" method. 666 $reventmask is a bitset as described in the "events" method.
432 667
433 $iow = $iow->fd ($fd) 668 $iow = $iow->fd ($fd)
434 Set the filedescriptor (not handle) to watch. 669 Set the filedescriptor (not handle) to watch.
435 670
436 $iow = $iow->events ($eventmask) 671 $iow = $iow->events ($eventmask)
437 Set the event mask to watch. Bit #0 (value 1) enables watching for 672 Set the event mask to watch. Bit #0 (value 1) enables watching
438 read data, Bit #1 (value 2) enables watching for write data. 673 for read data, Bit #1 (value 2) enables watching for write data.
439 674
440 $iow = $iow->start 675 $iow = $iow->start
441 Start watching for requested events on the given handle. 676 Start watching for requested events on the given handle.
442 677
443 $iow = $iow->stop 678 $iow = $iow->stop
444 Stop watching for events on the given filehandle. 679 Stop watching for events on the given filehandle.
445 680
446ENVIRONMENT 681ENVIRONMENT
447 URXVT_PERL_VERBOSITY 682 URXVT_PERL_VERBOSITY
448 This variable controls the verbosity level of the perl extension. Higher 683 This variable controls the verbosity level of the perl extension.
449 numbers indicate more verbose output. 684 Higher numbers indicate more verbose output.
450 685
451 0 - only fatal messages 686 =0 - only fatal messages
452 3 - script loading and management 687 =3 - script loading and management
453 10 - all events received 688 =10 - all events received
454 689
455AUTHOR 690AUTHOR
456 Marc Lehmann <pcg@goof.com> 691 Marc Lehmann <pcg@goof.com>
457 http://software.schmorp.de/pkg/rxvt-unicode 692 http://software.schmorp.de/pkg/rxvt-unicode
458 693

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines