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.9 by root, Wed Jan 4 00:12:12 2006 UTC vs.
Revision 1.12 by root, Sat Jan 7 04:19:43 2006 UTC

… …
44 44
45 URxvt.keysym.C-M-r: perl:selection:rot13 45 URxvt.keysym.C-M-r: perl:selection:rot13
46 46
47 digital-clock 47 digital-clock
48 Displays a digital clock using the built-in overlay. 48 Displays a digital clock using the built-in overlay.
49
50 mark-urls
51 Uses per-line display filtering ("on_line_update") to underline
52 urls.
53
54 block-graphics-to-ascii
55 A not very useful example of filtering all text output to the
56 terminal, by replacing all line-drawing characters (U+2500 ..
57 U+259F) by a similar-looking ascii character.
49 58
50 example-refresh-hooks 59 example-refresh-hooks
51 Displays a very simple digital clock in the upper right corner of 60 Displays a very simple digital clock in the upper right corner of
52 the window. Illustrates overwriting the refresh callbacks to create 61 the window. Illustrates overwriting the refresh callbacks to create
53 your own overlays or changes. 62 your own overlays or changes.
… …
62 When objects are destroyed on the C++ side, the perl object hashes are 71 When objects are destroyed on the C++ side, the perl object hashes are
63 emptied, so its best to store related objects such as time watchers and 72 emptied, so its best to store related objects such as time watchers and
64 the like inside the terminal object so they get destroyed as soon as the 73 the like inside the terminal object so they get destroyed as soon as the
65 terminal is destroyed. 74 terminal is destroyed.
66 75
76 Argument names also often indicate the type of a parameter. Here are
77 some hints on what they mean:
78
79 $text
80 Rxvt-unicodes special way of encoding text, where one "unicode"
81 character always represents one screen cell. See row_t for a
82 discussion of this format.
83
84 $string
85 A perl text string, with an emphasis on *text*. It can store all
86 unicode characters and is to be distinguished with text encoded in a
87 specific encoding (often locale-specific) and binary data.
88
89 $octets
90 Either binary data or - more common - a text string encoded in a
91 locale-specific way.
92
67 Hooks 93 Hooks
68 The following subroutines can be declared in loaded scripts, and will be 94 The following subroutines can be declared in extension files, and will
69 called whenever the relevant event happens. 95 be called whenever the relevant event happens.
70 96
71 The first argument passed to them is an object private to each terminal 97 The first argument passed to them is an object private to each terminal
72 and extension package. You can call all "urxvt::term" methods on it, but 98 and extension package. You can call all "urxvt::term" methods on it, but
73 its not a real "urxvt::term" object. Instead, the real "urxvt::term" 99 its not a real "urxvt::term" object. Instead, the real "urxvt::term"
74 object that is shared between all packages is stored in the "term" 100 object that is shared between all packages is stored in the "term"
… …
81 107
82 When in doubt, return a false value (preferably "()"). 108 When in doubt, return a false value (preferably "()").
83 109
84 on_init $term 110 on_init $term
85 Called after a new terminal object has been initialized, but before 111 Called after a new terminal object has been initialized, but before
86 windows are created or the command gets run. 112 windows are created or the command gets run. Most methods are unsafe
113 to call or deliver senseless data, as terminal size and other
114 characteristics have not yet been determined. You can safely query
115 and change resources, though.
87 116
88 on_reset $term 117 on_reset $term
89 Called after the screen is "reset" for any reason, such as resizing 118 Called after the screen is "reset" for any reason, such as resizing
90 or control sequences. Here is where you can react on changes to 119 or control sequences. Here is where you can react on changes to
91 size-related variables. 120 size-related variables.
… …
155 184
156 Be careful not ever to trust (in a security sense) the data you 185 Be careful not ever to trust (in a security sense) the data you
157 receive, as its source can not easily be controleld (e-mail content, 186 receive, as its source can not easily be controleld (e-mail content,
158 messages from other users on the same system etc.). 187 messages from other users on the same system etc.).
159 188
189 on_add_lines $term, $string
190 Called whenever text is about to be output, with the text as
191 argument. You can filter/change and output the text yourself by
192 returning a true value and calling "$term->scr_add_lines" yourself.
193 Please note that this might be very slow, however, as your hook is
194 called for all text being output.
195
196 on_line_update $term, $row
197 Called whenever a line was updated or changed. Can be used to filter
198 screen output (e.g. underline urls or other useless stuff). Only
199 lines that are being shown will be filtered, and, due to performance
200 reasons, not always immediately.
201
202 The row number is always the topmost row of the line if the line
203 spans multiple rows.
204
205 Please note that, if you change the line, then the hook might get
206 called later with the already-modified line (e.g. if unrelated parts
207 change), so you cannot just toggle rendition bits, but only set
208 them.
209
160 on_refresh_begin $term 210 on_refresh_begin $term
161 Called just before the screen gets redrawn. Can be used for overlay 211 Called just before the screen gets redrawn. Can be used for overlay
162 or similar effects by modify terminal contents in refresh_begin, and 212 or similar effects by modify terminal contents in refresh_begin, and
163 restoring them in refresh_end. The built-in overlay and selection 213 restoring them in refresh_end. The built-in overlay and selection
164 display code is run after this hook, and takes precedence. 214 display code is run after this hook, and takes precedence.
… …
169 on_keyboard_command $term, $string 219 on_keyboard_command $term, $string
170 Called whenever the user presses a key combination that has a 220 Called whenever the user presses a key combination that has a
171 "perl:string" action bound to it (see description of the keysym 221 "perl:string" action bound to it (see description of the keysym
172 resource in the rxvt(1) manpage). 222 resource in the rxvt(1) manpage).
173 223
224 on_key_press $term, $event, $octets
225 on_key_release $term, $event
226 on_button_press $term, $event
227 on_button_release $term, $event
228 on_motion_notify $term, $event
229 Called whenever the corresponding X event is received for the
230 terminal If the hook returns true, then the even will be ignored by
231 rxvt-unicode.
232
233 The event is a hash with most values as named by Xlib (see the
234 XEvent manpage), with the additional members "row" and "col", which
235 are the row and column under the mouse cursor.
236
237 "on_key_press" additionally receives the string rxvt-unicode would
238 output, if any, in locale-specific encoding.
239
240 subwindow.
241
174 Variables in the "urxvt" Package 242 Variables in the "urxvt" Package
175 $urxvt::TERM 243 $urxvt::TERM
176 The current terminal. Whenever a callback/Hook is bein executed,
177 this variable stores the current "urxvt::term" object. 244 The current terminal. This variable stores the current "urxvt::term"
245 object, whenever a callback/hook is executing.
178 246
179 Functions in the "urxvt" Package 247 Functions in the "urxvt" Package
248 $term = new urxvt [arg...]
249 Creates a new terminal, very similar as if you had started it with
250 "system $binfile, arg...". Croaks (and probably outputs an error
251 message) if the new instance couldn't be created. Returns "undef" if
252 the new instance didn't initialise perl, and the terminal object
253 otherwise. The "init" and "start" hooks will be called during the
254 call.
255
180 urxvt::fatal $errormessage 256 urxvt::fatal $errormessage
181 Fatally aborts execution with the given error message. Avoid at all 257 Fatally aborts execution with the given error message. Avoid at all
182 costs! The only time this is acceptable is when the terminal process 258 costs! The only time this is acceptable is when the terminal process
183 starts up. 259 starts up.
184 260
… …
231 307
232 $rend = urxvt::SET_CUSTOM ($rend, $new_value) 308 $rend = urxvt::SET_CUSTOM ($rend, $new_value)
233 Change the custom value. 309 Change the custom value.
234 310
235 The "urxvt::term" Class 311 The "urxvt::term" Class
312 $term->destroy
313 Destroy the terminal object (close the window, free resources etc.).
314
236 $value = $term->resource ($name[, $newval]) 315 $value = $term->resource ($name[, $newval])
237 Returns the current resource value associated with a given name and 316 Returns the current resource value associated with a given name and
238 optionally sets a new value. Setting values is most useful in the 317 optionally sets a new value. Setting values is most useful in the
239 "init" hook. Unset resources are returned and accepted as "undef". 318 "init" hook. Unset resources are returned and accepted as "undef".
240 319
… …
257 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 336 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
258 borderLess color cursorBlink cursorUnderline cutchars delete_key 337 borderLess color cursorBlink cursorUnderline cutchars delete_key
259 display_name embed ext_bwidth fade font geometry hold iconName 338 display_name embed ext_bwidth fade font geometry hold iconName
260 imFont imLocale inputMethod insecure int_bwidth intensityStyles 339 imFont imLocale inputMethod insecure int_bwidth intensityStyles
261 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier 340 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
262 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext 341 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2
263 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 342 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
264 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 343 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
265 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 344 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
266 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 345 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
267 shade term_name title transparent transparent_all tripleclickwords 346 shade term_name title transparent transparent_all tripleclickwords
268 utmpInhibit visualBell 347 utmpInhibit visualBell
269 348
349 $rend = $term->rstyle ([$new_rstyle])
350 Return and optionally change the current rendition. Text that is
351 output by the terminal application will use this style.
352
353 ($row, $col) = $term->screen_cur ([$row, $col])
354 Return the current coordinates of the text cursor position and
355 optionally set it (which is usually bad as applications don't expect
356 that).
357
270 ($row, $col) = $term->selection_mark ([$row, $col]) 358 ($row, $col) = $term->selection_mark ([$row, $col])
271 ($row, $col) = $term->selection_beg ([$row, $col]) 359 ($row, $col) = $term->selection_beg ([$row, $col])
272 ($row, $col) = $term->selection_end ([$row, $col]) 360 ($row, $col) = $term->selection_end ([$row, $col])
273 Return the current values of the selection mark, begin or end 361 Return the current values of the selection mark, begin or end
274 positions, and optionally set them to new values. 362 positions, and optionally set them to new values.
… …
280 $oldtext = $term->selection ([$newtext]) 368 $oldtext = $term->selection ([$newtext])
281 Return the current selection text and optionally replace it by 369 Return the current selection text and optionally replace it by
282 $newtext. 370 $newtext.
283 371
284 #=item $term->overlay ($x, $y, $text) # #Create a simple multi-line 372 #=item $term->overlay ($x, $y, $text) # #Create a simple multi-line
285 overlay box. See the next method for details. # #=cut 373 overlay box. See the next method for details. # #=cut # #sub
286
287 sub urxvt::term::scr_overlay { die; my ($self, $x, $y, $text) = @_; 374 urxvt::term::scr_overlay { # my ($self, $x, $y, $text) = @_; # # my
288 375 @lines = split /\n/, $text; # # my $w = 0; # for (map
289 my @lines = split /\n/, $text; 376 $self->strwidth ($_), @lines) { # $w = $_ if $w < $_; # } # #
290
291 my $w = 0;
292 for (map $self->strwidth ($_), @lines) {
293 $w = $_ if $w < $_;
294 }
295
296 $self->scr_overlay_new ($x, $y, $w, scalar @lines); 377 $self->scr_overlay_new ($x, $y, $w, scalar @lines); #
297 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 378 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; #}
298 }
299 379
300 $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 380 $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
301 Create a new (empty) overlay at the given position with the given 381 Create a new (empty) overlay at the given position with the given
302 width/height. $rstyle defines the initial rendition style (default: 382 width/height. $rstyle defines the initial rendition style (default:
303 "OVERLAY_RSTYLE"). 383 "OVERLAY_RSTYLE").
… …
322 If visible, hide the overlay, but do not destroy it. 402 If visible, hide the overlay, but do not destroy it.
323 403
324 $overlay->show 404 $overlay->show
325 If hidden, display the overlay again. 405 If hidden, display the overlay again.
326 406
327 $cellwidth = $term->strwidth $string 407 $cellwidth = $term->strwidth ($string)
328 Returns the number of screen-cells this string would need. Correctly 408 Returns the number of screen-cells this string would need. Correctly
329 accounts for wide and combining characters. 409 accounts for wide and combining characters.
330 410
331 $octets = $term->locale_encode $string 411 $octets = $term->locale_encode ($string)
332 Convert the given text string into the corresponding locale 412 Convert the given text string into the corresponding locale
333 encoding. 413 encoding.
334 414
335 $string = $term->locale_decode $octets 415 $string = $term->locale_decode ($octets)
336 Convert the given locale-encoded octets into a perl string. 416 Convert the given locale-encoded octets into a perl string.
417
418 $term->scr_add_lines ($string)
419 Write the given text string to the screen, as if output by the
420 application running inside the terminal. It may not contain command
421 sequences (escape codes), but is free to use line feeds, carriage
422 returns and tabs. The string is a normal text string, not in
423 locale-dependent encoding.
424
425 Normally its not a good idea to use this function, as programs might
426 be confused by changes in cursor position or scrolling. Its useful
427 inside a "on_add_lines" hook, though.
428
429 $term->cmd_parse ($octets)
430 Similar to "scr_add_lines", but the argument must be in the
431 locale-specific encoding of the terminal and can contain command
432 sequences (escape codes) that will be interpreted.
337 433
338 $term->tt_write ($octets) 434 $term->tt_write ($octets)
339 Write the octets given in $data to the tty (i.e. as program input). 435 Write the octets given in $data to the tty (i.e. as program input).
340 To pass characters instead of octets, you should convert your 436 To pass characters instead of octets, you should convert your
341 strings first to the locale-specific encoding using 437 strings first to the locale-specific encoding using
342 "$term->locale_encode". 438 "$term->locale_encode".
343 439
440 $windowid = $term->parent
441 Return the window id of the toplevel window.
442
443 $windowid = $term->vt
444 Return the window id of the terminal window.
445
446 $window_width = $term->width
447 $window_height = $term->height
448 $font_width = $term->fwidth
449 $font_height = $term->fheight
450 $font_ascent = $term->fbase
344 $nrow = $term->nrow 451 $terminal_rows = $term->nrow
345 $ncol = $term->ncol 452 $terminal_columns = $term->ncol
346 Return the number of rows/columns of the terminal window (i.e. as 453 $has_focus = $term->focus
347 specified by "-geometry", excluding any scrollback).
348
349 $nsaved = $term->nsaved 454 $is_mapped = $term->mapped
350 Returns the number of lines in the scrollback buffer. 455 $max_scrollback = $term->saveLines
456 $nrow_plus_saveLines = $term->total_rows
457 $lines_in_scrollback = $term->nsaved
458 Return various integers describing terminal characteristics.
351 459
352 $view_start = $term->view_start ([$newvalue]) 460 $view_start = $term->view_start ([$newvalue])
353 Returns the negative row number of the topmost line. Minimum value 461 Returns the negative row number of the topmost line. Minimum value
354 is 0, which displays the normal terminal contents. Larger values 462 is 0, which displays the normal terminal contents. Larger values
355 scroll this many lines into the scrollback buffer. 463 scroll this many lines into the scrollback buffer.
… …
409 $line = $term->line ($row_number) 517 $line = $term->line ($row_number)
410 Create and return a new "urxvt::line" object that stores information 518 Create and return a new "urxvt::line" object that stores information
411 about the logical line that row $row_number is part of. It supports 519 about the logical line that row $row_number is part of. It supports
412 the following methods: 520 the following methods:
413 521
414 $text = $line->t 522 $text = $line->t ([$new_text])
415 Returns the full text of the line, similar to "ROW_t" 523 Returns or replaces the full text of the line, similar to
524 "ROW_t"
416 525
417 $rend = $line->r 526 $rend = $line->r ([$new_rend])
418 Returns the full rendition array of the line, similar to "ROW_r" 527 Returns or replaces the full rendition array of the line,
528 similar to "ROW_r"
419 529
420 $length = $line->l 530 $length = $line->l
421 Returns the length of the line in cells, similar to "ROW_l". 531 Returns the length of the line in cells, similar to "ROW_l".
422 532
423 $rownum = $line->beg 533 $rownum = $line->beg

Diff Legend

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