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.10 by root, Wed Jan 4 05:35:34 2006 UTC vs.
Revision 1.16 by root, Mon Jan 9 07:17:24 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 Intelligent selection. This extension tries to be more intelligent 35 Intelligent selection. This extension tries to be more intelligent
36 when the user extends selections (double-click). Right now, it tries 36 when the user extends selections (double-click). Right now, it tries
37 to select urls and complete shell-quoted arguments, which is very 37 to select urls and complete shell-quoted arguments, which is very
38 convenient, too, if your ls supports "--quoting-style=shell". 38 convenient, too, if your ls supports "--quoting-style=shell".
39 39
… …
42 rot13 42 rot13
43 Rot-13 the selection when activated. Used via keyboard trigger: 43 Rot-13 the selection when activated. Used via keyboard trigger:
44 44
45 URxvt.keysym.C-M-r: perl:selection:rot13 45 URxvt.keysym.C-M-r: perl:selection:rot13
46 46
47 option-popup (enabled by default)
48 Binds a popup menu to Ctrl-Button2 that lets you toggle (some)
49 options at runtime.
50
51 selection-popup (enabled by default)
52 Binds a popup menu to Ctrl-Button3 that lets you convert the
53 selection text into various other formats/action.
54
47 digital-clock 55 digital-clock
48 Displays a digital clock using the built-in overlay. 56 Displays a digital clock using the built-in overlay.
57
58 mark-urls
59 Uses per-line display filtering ("on_line_update") to underline
60 urls.
61
62 block-graphics-to-ascii
63 A not very useful example of filtering all text output to the
64 terminal, by replacing all line-drawing characters (U+2500 ..
65 U+259F) by a similar-looking ascii character.
49 66
50 example-refresh-hooks 67 example-refresh-hooks
51 Displays a very simple digital clock in the upper right corner of 68 Displays a very simple digital clock in the upper right corner of
52 the window. Illustrates overwriting the refresh callbacks to create 69 the window. Illustrates overwriting the refresh callbacks to create
53 your own overlays or changes. 70 your own overlays or changes.
… …
62 When objects are destroyed on the C++ side, the perl object hashes are 79 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 80 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 81 the like inside the terminal object so they get destroyed as soon as the
65 terminal is destroyed. 82 terminal is destroyed.
66 83
84 Argument names also often indicate the type of a parameter. Here are
85 some hints on what they mean:
86
87 $text
88 Rxvt-unicodes special way of encoding text, where one "unicode"
89 character always represents one screen cell. See row_t for a
90 discussion of this format.
91
92 $string
93 A perl text string, with an emphasis on *text*. It can store all
94 unicode characters and is to be distinguished with text encoded in a
95 specific encoding (often locale-specific) and binary data.
96
97 $octets
98 Either binary data or - more common - a text string encoded in a
99 locale-specific way.
100
67 Hooks 101 Hooks
68 The following subroutines can be declared in loaded scripts, and will be 102 The following subroutines can be declared in extension files, and will
69 called whenever the relevant event happens. 103 be called whenever the relevant event happens.
70 104
71 The first argument passed to them is an object private to each terminal 105 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 106 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" 107 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" 108 object that is shared between all packages is stored in the "term"
75 member. 109 member. It is, however, blessed intot he package of the extension
110 script, so for all practical purposes you can treat an extension script
111 as a class.
76 112
77 All of them must return a boolean value. If it is true, then the event 113 All of them must return a boolean value. If it is true, then the event
78 counts as being *consumed*, and the invocation of other hooks is 114 counts as being *consumed*, and the invocation of other hooks is
79 skipped, and the relevant action might not be carried out by the C++ 115 skipped, and the relevant action might not be carried out by the C++
80 code. 116 code.
81 117
82 When in doubt, return a false value (preferably "()"). 118 When in doubt, return a false value (preferably "()").
83 119
84 on_init $term 120 on_init $term
85 Called after a new terminal object has been initialized, but before 121 Called after a new terminal object has been initialized, but before
86 windows are created or the command gets run. 122 windows are created or the command gets run. Most methods are unsafe
123 to call or deliver senseless data, as terminal size and other
124 characteristics have not yet been determined. You can safely query
125 and change resources, though.
87 126
88 on_reset $term 127 on_reset $term
89 Called after the screen is "reset" for any reason, such as resizing 128 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 129 or control sequences. Here is where you can react on changes to
91 size-related variables. 130 size-related variables.
… …
117 operation), or should extend the selection itelf and return true to 156 operation), or should extend the selection itelf and return true to
118 suppress the built-in processing. 157 suppress the built-in processing.
119 158
120 See the selection example extension. 159 See the selection example extension.
121 160
122 on_focus_in $term
123 Called whenever the window gets the keyboard focus, before urxvt
124 does focus in processing.
125
126 on_focus_out $term
127 Called wheneever the window loses keyboard focus, before urxvt does
128 focus out processing.
129
130 on_view_change $term, $offset 161 on_view_change $term, $offset
131 Called whenever the view offset changes, i..e the user or program 162 Called whenever the view offset changes, i..e the user or program
132 scrolls. Offset 0 means display the normal terminal, positive values 163 scrolls. Offset 0 means display the normal terminal, positive values
133 show this many lines of scrollback. 164 show this many lines of scrollback.
134 165
… …
138 may be larger than the scroll back buffer or the terminal. 169 may be larger than the scroll back buffer or the terminal.
139 170
140 It is called before lines are scrolled out (so rows 0 .. min ($lines 171 It is called before lines are scrolled out (so rows 0 .. min ($lines
141 - 1, $nrow - 1) represent the lines to be scrolled out). $saved is 172 - 1, $nrow - 1) represent the lines to be scrolled out). $saved is
142 the total number of lines that will be in the scrollback buffer. 173 the total number of lines that will be in the scrollback buffer.
143
144 on_tty_activity $term *NYI*
145 Called whenever the program(s) running in the urxvt window send
146 output.
147 174
148 on_osc_seq $term, $string 175 on_osc_seq $term, $string
149 Called whenever the ESC ] 777 ; string ST command sequence (OSC = 176 Called whenever the ESC ] 777 ; string ST command sequence (OSC =
150 operating system command) is processed. Cursor position and other 177 operating system command) is processed. Cursor position and other
151 state information is up-to-date when this happens. For 178 state information is up-to-date when this happens. For
… …
155 182
156 Be careful not ever to trust (in a security sense) the data you 183 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, 184 receive, as its source can not easily be controleld (e-mail content,
158 messages from other users on the same system etc.). 185 messages from other users on the same system etc.).
159 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.
207
160 on_refresh_begin $term 208 on_refresh_begin $term
161 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
162 or similar effects by modify terminal contents in refresh_begin, and 210 or similar effects by modify terminal contents in refresh_begin, and
163 restoring them in refresh_end. The built-in overlay and selection 211 restoring them in refresh_end. The built-in overlay and selection
164 display code is run after this hook, and takes precedence. 212 display code is run after this hook, and takes precedence.
… …
169 on_keyboard_command $term, $string 217 on_keyboard_command $term, $string
170 Called whenever the user presses a key combination that has a 218 Called whenever the user presses a key combination that has a
171 "perl:string" action bound to it (see description of the keysym 219 "perl:string" action bound to it (see description of the keysym
172 resource in the rxvt(1) manpage). 220 resource in the rxvt(1) manpage).
173 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
174 Variables in the "urxvt" Package 250 Variables in the "urxvt" Package
175 $urxvt::TERM 251 $urxvt::TERM
176 The current terminal. Whenever a callback/Hook is bein executed,
177 this variable stores the current "urxvt::term" object. 252 The current terminal. This variable stores the current "urxvt::term"
253 object, whenever a callback/hook is executing.
178 254
179 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
180 urxvt::fatal $errormessage 264 urxvt::fatal $errormessage
181 Fatally aborts execution with the given error message. Avoid at all 265 Fatally aborts execution with the given error message. Avoid at all
182 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
183 starts up. 267 starts up.
184 268
… …
188 function that calls this function. 272 function that calls this function.
189 273
190 Using this function has the advantage that its output ends up in the 274 Using this function has the advantage that its output ends up in the
191 correct place, e.g. on stderr of the connecting urxvtc client. 275 correct place, e.g. on stderr of the connecting urxvtc client.
192 276
277 $is_safe = urxvt::safe
278 Returns true when it is safe to do potentially unsafe things, such
279 as evaluating perl code specified by the user. This is true when
280 urxvt was started setuid or setgid.
281
193 $time = urxvt::NOW 282 $time = urxvt::NOW
194 Returns the "current time" (as per the event loop). 283 Returns the "current time" (as per the event loop).
284
285 urxvt::CurrentTime
286 urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask,
287 Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask,
288 Button5Mask, AnyModifier
289 Various constants for use in X calls and event processing.
195 290
196 RENDITION 291 RENDITION
197 Rendition bitsets contain information about colour, font, font styles 292 Rendition bitsets contain information about colour, font, font styles
198 and similar information for each screen cell. 293 and similar information for each screen cell.
199 294
… …
230 initially zero. 325 initially zero.
231 326
232 $rend = urxvt::SET_CUSTOM ($rend, $new_value) 327 $rend = urxvt::SET_CUSTOM ($rend, $new_value)
233 Change the custom value. 328 Change the custom value.
234 329
330 The "urxvt::anyevent" Class
331 The sole purpose of this class is to deliver an interface to the
332 "AnyEvent" module - any module using it will work inside urxvt without
333 further work. The only exception is that you cannot wait on condition
334 variables, but non-blocking condvar use is ok. What this means is that
335 you cannot use blocking APIs, but the non-blocking variant should work.
336
235 The "urxvt::term" Class 337 The "urxvt::term" Class
338 $term->destroy
339 Destroy the terminal object (close the window, free resources etc.).
340
341 $isset = $term->option ($optval[, $set])
342 Returns true if the option specified by $optval is enabled, and
343 optionally change it. All option values are stored by name in the
344 hash %urxvt::OPTION. Options not enabled in this binary are not in
345 the hash.
346
347 Here is a a likely non-exhaustive list of option names, please see
348 the source file /src/optinc.h to see the actual list:
349
350 borderLess console cursorBlink cursorUnderline hold iconic insecure
351 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
352 pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating
353 scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer
354 secondaryScreen secondaryScroll skipBuiltinGlyphs transparent
355 tripleclickwords utmpInhibit visualBell
356
236 $value = $term->resource ($name[, $newval]) 357 $value = $term->resource ($name[, $newval])
237 Returns the current resource value associated with a given name and 358 Returns the current resource value associated with a given name and
238 optionally sets a new value. Setting values is most useful in the 359 optionally sets a new value. Setting values is most useful in the
239 "init" hook. Unset resources are returned and accepted as "undef". 360 "init" hook. Unset resources are returned and accepted as "undef".
240 361
… …
249 Please note that resource strings will currently only be freed when 370 Please note that resource strings will currently only be freed when
250 the terminal is destroyed, so changing options frequently will eat 371 the terminal is destroyed, so changing options frequently will eat
251 memory. 372 memory.
252 373
253 Here is a a likely non-exhaustive list of resource names, not all of 374 Here is a a likely non-exhaustive list of resource names, not all of
254 which are supported in every build, please see the source to see the 375 which are supported in every build, please see the source file
255 actual list: 376 /src/rsinc.h to see the actual list:
256 377
257 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 378 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
258 borderLess color cursorBlink cursorUnderline cutchars delete_key 379 borderLess color cursorBlink cursorUnderline cutchars delete_key
259 display_name embed ext_bwidth fade font geometry hold iconName 380 display_name embed ext_bwidth fade font geometry hold iconName
260 imFont imLocale inputMethod insecure int_bwidth intensityStyles 381 imFont imLocale inputMethod insecure int_bwidth intensityStyles
… …
265 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 386 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
266 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 387 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
267 shade term_name title transparent transparent_all tripleclickwords 388 shade term_name title transparent transparent_all tripleclickwords
268 utmpInhibit visualBell 389 utmpInhibit visualBell
269 390
391 $rend = $term->rstyle ([$new_rstyle])
392 Return and optionally change the current rendition. Text that is
393 output by the terminal application will use this style.
394
395 ($row, $col) = $term->screen_cur ([$row, $col])
396 Return the current coordinates of the text cursor position and
397 optionally set it (which is usually bad as applications don't expect
398 that).
399
270 ($row, $col) = $term->selection_mark ([$row, $col]) 400 ($row, $col) = $term->selection_mark ([$row, $col])
271 ($row, $col) = $term->selection_beg ([$row, $col]) 401 ($row, $col) = $term->selection_beg ([$row, $col])
272 ($row, $col) = $term->selection_end ([$row, $col]) 402 ($row, $col) = $term->selection_end ([$row, $col])
273 Return the current values of the selection mark, begin or end 403 Return the current values of the selection mark, begin or end
274 positions, and optionally set them to new values. 404 positions, and optionally set them to new values.
… …
280 $oldtext = $term->selection ([$newtext]) 410 $oldtext = $term->selection ([$newtext])
281 Return the current selection text and optionally replace it by 411 Return the current selection text and optionally replace it by
282 $newtext. 412 $newtext.
283 413
284 #=item $term->overlay ($x, $y, $text) # #Create a simple multi-line 414 #=item $term->overlay ($x, $y, $text) # #Create a simple multi-line
285 overlay box. See the next method for details. # #=cut 415 overlay box. See the next method for details. # #=cut # #sub
286
287 sub urxvt::term::scr_overlay { die; my ($self, $x, $y, $text) = @_; 416 urxvt::term::scr_overlay { # my ($self, $x, $y, $text) = @_; # # my
288 417 @lines = split /\n/, $text; # # my $w = 0; # for (map
289 my @lines = split /\n/, $text; 418 $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); 419 $self->scr_overlay_new ($x, $y, $w, scalar @lines); #
297 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 420 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; #}
298 }
299 421
300 $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 422 $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
301 Create a new (empty) overlay at the given position with the given 423 Create a new (empty) overlay at the given position with the given
302 width/height. $rstyle defines the initial rendition style (default: 424 width/height. $rstyle defines the initial rendition style (default:
303 "OVERLAY_RSTYLE"). 425 "OVERLAY_RSTYLE").
… …
322 If visible, hide the overlay, but do not destroy it. 444 If visible, hide the overlay, but do not destroy it.
323 445
324 $overlay->show 446 $overlay->show
325 If hidden, display the overlay again. 447 If hidden, display the overlay again.
326 448
449 $popup = $term->popup ($event)
450 Creates a new "urxvt::popup" object that implements a popup menu.
451 The $event *must* be the event causing the menu to pop up (a button
452 event, currently).
453
327 $cellwidth = $term->strwidth $string 454 $cellwidth = $term->strwidth ($string)
328 Returns the number of screen-cells this string would need. Correctly 455 Returns the number of screen-cells this string would need. Correctly
329 accounts for wide and combining characters. 456 accounts for wide and combining characters.
330 457
331 $octets = $term->locale_encode $string 458 $octets = $term->locale_encode ($string)
332 Convert the given text string into the corresponding locale 459 Convert the given text string into the corresponding locale
333 encoding. 460 encoding.
334 461
335 $string = $term->locale_decode $octets 462 $string = $term->locale_decode ($octets)
336 Convert the given locale-encoded octets into a perl string. 463 Convert the given locale-encoded octets into a perl string.
464
465 $term->scr_add_lines ($string)
466 Write the given text string to the screen, as if output by the
467 application running inside the terminal. It may not contain command
468 sequences (escape codes), but is free to use line feeds, carriage
469 returns and tabs. The string is a normal text string, not in
470 locale-dependent encoding.
471
472 Normally its not a good idea to use this function, as programs might
473 be confused by changes in cursor position or scrolling. Its useful
474 inside a "on_add_lines" hook, though.
475
476 $term->cmd_parse ($octets)
477 Similar to "scr_add_lines", but the argument must be in the
478 locale-specific encoding of the terminal and can contain command
479 sequences (escape codes) that will be interpreted.
337 480
338 $term->tt_write ($octets) 481 $term->tt_write ($octets)
339 Write the octets given in $data to the tty (i.e. as program input). 482 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 483 To pass characters instead of octets, you should convert your
341 strings first to the locale-specific encoding using 484 strings first to the locale-specific encoding using
342 "$term->locale_encode". 485 "$term->locale_encode".
343 486
487 $windowid = $term->parent
488 Return the window id of the toplevel window.
489
490 $windowid = $term->vt
491 Return the window id of the terminal window.
492
493 $window_width = $term->width
494 $window_height = $term->height
495 $font_width = $term->fwidth
496 $font_height = $term->fheight
497 $font_ascent = $term->fbase
344 $nrow = $term->nrow 498 $terminal_rows = $term->nrow
345 $ncol = $term->ncol 499 $terminal_columns = $term->ncol
346 Return the number of rows/columns of the terminal window (i.e. as 500 $has_focus = $term->focus
347 specified by "-geometry", excluding any scrollback).
348
349 $nsaved = $term->nsaved 501 $is_mapped = $term->mapped
350 Returns the number of lines in the scrollback buffer. 502 $max_scrollback = $term->saveLines
503 $nrow_plus_saveLines = $term->total_rows
504 $lines_in_scrollback = $term->nsaved
505 Return various integers describing terminal characteristics.
506
507 $modifiermask = $term->ModLevel3Mask
508 $modifiermask = $term->ModMetaMask
509 $modifiermask = $term->ModNumLockMask
510 Return the modifier masks corresponding to the "ISO Level 3 Shift"
511 (often AltGr), the meta key (often Alt) and the num lock key, if
512 applicable.
351 513
352 $view_start = $term->view_start ([$newvalue]) 514 $view_start = $term->view_start ([$newvalue])
353 Returns the negative row number of the topmost line. Minimum value 515 Returns the negative row number of the topmost line. Minimum value
354 is 0, which displays the normal terminal contents. Larger values 516 is 0, which displays the normal terminal contents. Larger values
355 scroll this many lines into the scrollback buffer. 517 scroll this many lines into the scrollback buffer.
… …
409 $line = $term->line ($row_number) 571 $line = $term->line ($row_number)
410 Create and return a new "urxvt::line" object that stores information 572 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 573 about the logical line that row $row_number is part of. It supports
412 the following methods: 574 the following methods:
413 575
414 $text = $line->t 576 $text = $line->t ([$new_text])
415 Returns the full text of the line, similar to "ROW_t" 577 Returns or replaces the full text of the line, similar to
578 "ROW_t"
416 579
417 $rend = $line->r 580 $rend = $line->r ([$new_rend])
418 Returns the full rendition array of the line, similar to "ROW_r" 581 Returns or replaces the full rendition array of the line,
582 similar to "ROW_r"
419 583
420 $length = $line->l 584 $length = $line->l
421 Returns the length of the line in cells, similar to "ROW_l". 585 Returns the length of the line in cells, similar to "ROW_l".
422 586
423 $rownum = $line->beg 587 $rownum = $line->beg
… …
430 the logical line. 594 the logical line.
431 595
432 ($row, $col) = $line->coord_of ($offset) 596 ($row, $col) = $line->coord_of ($offset)
433 Translates a string offset into terminal coordinates again. 597 Translates a string offset into terminal coordinates again.
434 598
435 ($row, $col) = $line->coord_of ($offset) =item $text =
436 $term->special_encode $string 599 $text = $term->special_encode $string
437 Converts a perl string into the special encoding used by 600 Converts a perl string into the special encoding used by
438 rxvt-unicode, where one character corresponds to one screen cell. 601 rxvt-unicode, where one character corresponds to one screen cell.
439 See "$term->ROW_t" for details. 602 See "$term->ROW_t" for details.
440 603
441 $string = $term->special_decode $text 604 $string = $term->special_decode $text
442 Converts rxvt-unicodes text reprsentation into a perl string. See 605 Converts rxvt-unicodes text reprsentation into a perl string. See
443 "$term->ROW_t" for details. 606 "$term->ROW_t" for details.
444 607
608 $success = $term->grab_button ($button, $modifiermask)
609 Registers a synchronous button grab. See the XGrabButton manpage.
610
611 $success = $term->grab ($eventtime[, $sync])
612 Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
613 synchronous ($sync is true). Also remembers the grab timestampe.
614
615 $term->allow_events_async
616 Calls XAllowEvents with AsyncBoth for the most recent grab.
617
618 $term->allow_events_sync
619 Calls XAllowEvents with SyncBoth for the most recent grab.
620
621 $term->allow_events_replay
622 Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for
623 the most recent grab.
624
625 $term->ungrab
626 Calls XUngrab for the most recent grab. Is called automatically on
627 evaluation errors, as it is better to lose the grab in the error
628 case as the session.
629
630 The "urxvt::popup" Class
445 The "urxvt::timer" Class 631 The "urxvt::timer" Class
446 This class implements timer watchers/events. Time is represented as a 632 This class implements timer watchers/events. Time is represented as
447 fractional number of seconds since the epoch. Example: 633 a fractional number of seconds since the epoch. Example:
448 634
449 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0); 635 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
450 $term->{timer} = urxvt::timer 636 $term->{timer} = urxvt::timer
451 ->new 637 ->new
452 ->interval (1) 638 ->interval (1)
453 ->cb (sub { 639 ->cb (sub {
454 $term->{overlay}->set (0, 0, 640 $term->{overlay}->set (0, 0,
455 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]); 641 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
456 }); 642 });
457 643
458 $timer = new urxvt::timer 644 $timer = new urxvt::timer
459 Create a new timer object in started state. It is scheduled to fire 645 Create a new timer object in started state. It is scheduled to
460 immediately. 646 fire immediately.
461 647
462 $timer = $timer->cb (sub { my ($timer) = @_; ... }) 648 $timer = $timer->cb (sub { my ($timer) = @_; ... })
463 Set the callback to be called when the timer triggers. 649 Set the callback to be called when the timer triggers.
464 650
465 $tstamp = $timer->at 651 $tstamp = $timer->at
466 Return the time this watcher will fire next. 652 Return the time this watcher will fire next.
467 653
468 $timer = $timer->set ($tstamp) 654 $timer = $timer->set ($tstamp)
469 Set the time the event is generated to $tstamp. 655 Set the time the event is generated to $tstamp.
470 656
471 $timer = $timer->interval ($interval) 657 $timer = $timer->interval ($interval)
472 Normally (and when $interval is 0), the timer will automatically 658 Normally (and when $interval is 0), the timer will automatically
473 stop after it has fired once. If $interval is non-zero, then the 659 stop after it has fired once. If $interval is non-zero, then the
474 timer is automatically rescheduled at the given intervals. 660 timer is automatically rescheduled at the given intervals.
475 661
476 $timer = $timer->start 662 $timer = $timer->start
477 Start the timer. 663 Start the timer.
478 664
479 $timer = $timer->start ($tstamp) 665 $timer = $timer->start ($tstamp)
480 Set the event trigger time to $tstamp and start the timer. 666 Set the event trigger time to $tstamp and start the timer.
481 667
482 $timer = $timer->stop 668 $timer = $timer->stop
483 Stop the timer. 669 Stop the timer.
484 670
485 The "urxvt::iow" Class 671 The "urxvt::iow" Class
486 This class implements io watchers/events. Example: 672 This class implements io watchers/events. Example:
487 673
488 $term->{socket} = ... 674 $term->{socket} = ...
489 $term->{iow} = urxvt::iow 675 $term->{iow} = urxvt::iow
490 ->new 676 ->new
491 ->fd (fileno $term->{socket}) 677 ->fd (fileno $term->{socket})
492 ->events (1) # wait for read data 678 ->events (1) # wait for read data
493 ->start 679 ->start
494 ->cb (sub { 680 ->cb (sub {
495 my ($iow, $revents) = @_; 681 my ($iow, $revents) = @_;
496 # $revents must be 1 here, no need to check 682 # $revents must be 1 here, no need to check
497 sysread $term->{socket}, my $buf, 8192 683 sysread $term->{socket}, my $buf, 8192
498 or end-of-file; 684 or end-of-file;
499 }); 685 });
500 686
501 $iow = new urxvt::iow 687 $iow = new urxvt::iow
502 Create a new io watcher object in stopped state. 688 Create a new io watcher object in stopped state.
503 689
504 $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... }) 690 $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
505 Set the callback to be called when io events are triggered. 691 Set the callback to be called when io events are triggered.
506 $reventmask is a bitset as described in the "events" method. 692 $reventmask is a bitset as described in the "events" method.
507 693
508 $iow = $iow->fd ($fd) 694 $iow = $iow->fd ($fd)
509 Set the filedescriptor (not handle) to watch. 695 Set the filedescriptor (not handle) to watch.
510 696
511 $iow = $iow->events ($eventmask) 697 $iow = $iow->events ($eventmask)
512 Set the event mask to watch. Bit #0 (value 1) enables watching for 698 Set the event mask to watch. Bit #0 (value 1) enables watching
513 read data, Bit #1 (value 2) enables watching for write data. 699 for read data, Bit #1 (value 2) enables watching for write data.
514 700
515 $iow = $iow->start 701 $iow = $iow->start
516 Start watching for requested events on the given handle. 702 Start watching for requested events on the given handle.
517 703
518 $iow = $iow->stop 704 $iow = $iow->stop
519 Stop watching for events on the given filehandle. 705 Stop watching for events on the given filehandle.
520 706
521ENVIRONMENT 707ENVIRONMENT
522 URXVT_PERL_VERBOSITY 708 URXVT_PERL_VERBOSITY
523 This variable controls the verbosity level of the perl extension. Higher 709 This variable controls the verbosity level of the perl extension.
524 numbers indicate more verbose output. 710 Higher numbers indicate more verbose output.
525 711
526 =0 - only fatal messages 712 == 0 - fatal messages
527 =3 - script loading and management 713 >= 3 - script loading and management
528 =10 - all events received 714 >=10 - all events received
529 715
530AUTHOR 716AUTHOR
531 Marc Lehmann <pcg@goof.com> 717 Marc Lehmann <pcg@goof.com>
532 http://software.schmorp.de/pkg/rxvt-unicode 718 http://software.schmorp.de/pkg/rxvt-unicode
533 719

Diff Legend

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