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.12 by root, Sat Jan 7 04:19:43 2006 UTC vs.
Revision 1.19 by root, Tue Jan 10 19:46:28 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
24 will be shared (but not enabled) for all terminals. 24 will be shared (but not enabled) for all terminals.
25 25
26 Prepackaged Extensions 26PREPACKAGED EXTENSIONS
27 This section describes the extensiosn delivered with this version. You 27 This section describes the extensions delivered with this release. You
28 can find them in /opt/rxvt/lib/urxvt/perl/. 28 can find them in /opt/rxvt/lib/urxvt/perl/.
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 (More) intelligent selection. This extension tries to be more
36 when the user extends selections (double-click). Right now, it tries 36 intelligent when the user extends selections (double-click). Right
37 to select urls and complete shell-quoted arguments, which is very 37 now, it tries to select urls and complete shell-quoted arguments,
38 convenient, too, if your ls supports "--quoting-style=shell". 38 which is very convenient, too, if your ls supports
39 "--quoting-style=shell".
39 40
40 It also offers the following bindable event: 41 It also offers the following bindable keyboard command:
41 42
42 rot13 43 rot13
43 Rot-13 the selection when activated. Used via keyboard trigger: 44 Rot-13 the selection when activated. Used via keyboard trigger:
44 45
45 URxvt.keysym.C-M-r: perl:selection:rot13 46 URxvt.keysym.C-M-r: perl:selection:rot13
47
48 option-popup (enabled by default)
49 Binds a popup menu to Ctrl-Button2 that lets you toggle (some)
50 options at runtime.
51
52 selection-popup (enabled by default)
53 Binds a popup menu to Ctrl-Button3 that lets you convert the
54 selection text into various other formats/action (such as uri
55 unescaping, perl evalution, web-browser starting etc.), depending on
56 content.
57
58 searchable-scrollback<hotkey> (enabled by default)
59 Adds regex search functionality to the scrollback buffer, triggered
60 by a hotkey (default: "M-s"). When in search mode, normal terminal
61 input/output is suspended.
62
63 "/" starts an incremental regex search, "n" searches further, "p" or
64 "N" jump to the previous match, "G" jumps to the bottom and clears
65 the history, "enter" leaves search mode at the current position and
66 "escape" returns to the original position.
46 67
47 digital-clock 68 digital-clock
48 Displays a digital clock using the built-in overlay. 69 Displays a digital clock using the built-in overlay.
49 70
50 mark-urls 71 mark-urls
… …
59 example-refresh-hooks 80 example-refresh-hooks
60 Displays a very simple digital clock in the upper right corner of 81 Displays a very simple digital clock in the upper right corner of
61 the window. Illustrates overwriting the refresh callbacks to create 82 the window. Illustrates overwriting the refresh callbacks to create
62 your own overlays or changes. 83 your own overlays or changes.
63 84
85API DOCUMENTATION
64 General API Considerations 86 General API Considerations
65 All objects (such as terminals, time watchers etc.) are typical 87 All objects (such as terminals, time watchers etc.) are typical
66 reference-to-hash objects. The hash can be used to store anything you 88 reference-to-hash objects. The hash can be used to store anything you
67 like. All members starting with an underscore (such as "_ptr" or 89 like. All members starting with an underscore (such as "_ptr" or
68 "_hook") are reserved for internal uses and MUST NOT be accessed or 90 "_hook") are reserved for internal uses and MUST NOT be accessed or
… …
88 110
89 $octets 111 $octets
90 Either binary data or - more common - a text string encoded in a 112 Either binary data or - more common - a text string encoded in a
91 locale-specific way. 113 locale-specific way.
92 114
115 Extension Objects
116 Very perl extension is a perl class. A separate perl object is created
117 for each terminal and each extension and passed as the first parameter
118 to hooks. So extensions can use their $self object without having to
119 think about other extensions, with the exception of methods and members
120 that begin with an underscore character "_": these are reserved for
121 internal use.
122
123 Although it isn't a "urxvt::term" object, you can call all methods of
124 the "urxvt::term" class on this object.
125
126 It has the following methods and data members:
127
128 $urxvt_term = $self->{term}
129 Returns the "urxvt::term" object associated with this instance of
130 the extension. This member *must not* be changed in any way.
131
132 $self->enable ($hook_name => $cb, [$hook_name => $cb..])
133 Dynamically enable the given hooks (named without the "on_" prefix)
134 for this extension, replacing any previous hook. This is useful when
135 you want to overwrite time-critical hooks only temporarily.
136
137 $self->disable ($hook_name[, $hook_name..])
138 Dynamically disable the given hooks.
139
93 Hooks 140 Hooks
94 The following subroutines can be declared in extension files, and will 141 The following subroutines can be declared in extension files, and will
95 be called whenever the relevant event happens. 142 be called whenever the relevant event happens.
96 143
97 The first argument passed to them is an object private to each terminal 144 The first argument passed to them is an extension oject as described in
98 and extension package. You can call all "urxvt::term" methods on it, but 145 the in the "Extension Objects" section.
99 its not a real "urxvt::term" object. Instead, the real "urxvt::term"
100 object that is shared between all packages is stored in the "term"
101 member.
102 146
103 All of them must return a boolean value. If it is true, then the event 147 All of these hooks must return a boolean value. If it is true, then the
104 counts as being *consumed*, and the invocation of other hooks is 148 event counts as being *consumed*, and the invocation of other hooks is
105 skipped, and the relevant action might not be carried out by the C++ 149 skipped, and the relevant action might not be carried out by the C++
106 code. 150 code.
107 151
108 When in doubt, return a false value (preferably "()"). 152 *When in doubt, return a false value (preferably "()").*
109 153
110 on_init $term 154 on_init $term
111 Called after a new terminal object has been initialized, but before 155 Called after a new terminal object has been initialized, but before
112 windows are created or the command gets run. Most methods are unsafe 156 windows are created or the command gets run. Most methods are unsafe
113 to call or deliver senseless data, as terminal size and other 157 to call or deliver senseless data, as terminal size and other
… …
146 operation), or should extend the selection itelf and return true to 190 operation), or should extend the selection itelf and return true to
147 suppress the built-in processing. 191 suppress the built-in processing.
148 192
149 See the selection example extension. 193 See the selection example extension.
150 194
151 on_focus_in $term
152 Called whenever the window gets the keyboard focus, before urxvt
153 does focus in processing.
154
155 on_focus_out $term
156 Called wheneever the window loses keyboard focus, before urxvt does
157 focus out processing.
158
159 on_view_change $term, $offset 195 on_view_change $term, $offset
160 Called whenever the view offset changes, i..e the user or program 196 Called whenever the view offset changes, i..e the user or program
161 scrolls. Offset 0 means display the normal terminal, positive values 197 scrolls. Offset 0 means display the normal terminal, positive values
162 show this many lines of scrollback. 198 show this many lines of scrollback.
163 199
… …
167 may be larger than the scroll back buffer or the terminal. 203 may be larger than the scroll back buffer or the terminal.
168 204
169 It is called before lines are scrolled out (so rows 0 .. min ($lines 205 It is called before lines are scrolled out (so rows 0 .. min ($lines
170 - 1, $nrow - 1) represent the lines to be scrolled out). $saved is 206 - 1, $nrow - 1) represent the lines to be scrolled out). $saved is
171 the total number of lines that will be in the scrollback buffer. 207 the total number of lines that will be in the scrollback buffer.
172
173 on_tty_activity $term *NYI*
174 Called whenever the program(s) running in the urxvt window send
175 output.
176 208
177 on_osc_seq $term, $string 209 on_osc_seq $term, $string
178 Called whenever the ESC ] 777 ; string ST command sequence (OSC = 210 Called whenever the ESC ] 777 ; string ST command sequence (OSC =
179 operating system command) is processed. Cursor position and other 211 operating system command) is processed. Cursor position and other
180 state information is up-to-date when this happens. For 212 state information is up-to-date when this happens. For
… …
191 argument. You can filter/change and output the text yourself by 223 argument. You can filter/change and output the text yourself by
192 returning a true value and calling "$term->scr_add_lines" yourself. 224 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 225 Please note that this might be very slow, however, as your hook is
194 called for all text being output. 226 called for all text being output.
195 227
228 on_tt_write $term, $octets
229 Called whenever some data is written to the tty/pty and can be used
230 to suppress or filter tty input.
231
196 on_line_update $term, $row 232 on_line_update $term, $row
197 Called whenever a line was updated or changed. Can be used to filter 233 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 234 screen output (e.g. underline urls or other useless stuff). Only
199 lines that are being shown will be filtered, and, due to performance 235 lines that are being shown will be filtered, and, due to performance
200 reasons, not always immediately. 236 reasons, not always immediately.
… …
219 on_keyboard_command $term, $string 255 on_keyboard_command $term, $string
220 Called whenever the user presses a key combination that has a 256 Called whenever the user presses a key combination that has a
221 "perl:string" action bound to it (see description of the keysym 257 "perl:string" action bound to it (see description of the keysym
222 resource in the rxvt(1) manpage). 258 resource in the rxvt(1) manpage).
223 259
260 on_focus_in $term
261 Called whenever the window gets the keyboard focus, before
262 rxvt-unicode does focus in processing.
263
264 on_focus_out $term
265 Called wheneever the window loses keyboard focus, before
266 rxvt-unicode does focus out processing.
267
224 on_key_press $term, $event, $octets 268 on_key_press $term, $event, $keysym, $octets
225 on_key_release $term, $event 269 on_key_release $term, $event, $keysym
226 on_button_press $term, $event 270 on_button_press $term, $event
227 on_button_release $term, $event 271 on_button_release $term, $event
228 on_motion_notify $term, $event 272 on_motion_notify $term, $event
273 on_map_notify $term, $event
274 on_unmap_notify $term, $event
229 Called whenever the corresponding X event is received for the 275 Called whenever the corresponding X event is received for the
230 terminal If the hook returns true, then the even will be ignored by 276 terminal If the hook returns true, then the even will be ignored by
231 rxvt-unicode. 277 rxvt-unicode.
232 278
233 The event is a hash with most values as named by Xlib (see the 279 The event is a hash with most values as named by Xlib (see the
… …
238 output, if any, in locale-specific encoding. 284 output, if any, in locale-specific encoding.
239 285
240 subwindow. 286 subwindow.
241 287
242 Variables in the "urxvt" Package 288 Variables in the "urxvt" Package
289 $urxvt::LIBDIR
290 The rxvt-unicode library directory, where, among other things, the
291 perl modules and scripts are stored.
292
293 $urxvt::RESCLASS, $urxvt::RESCLASS
294 The resource class and name rxvt-unicode uses to look up X
295 resources.
296
297 $urxvt::RXVTNAME
298 The basename of the installed binaries, usually "urxvt".
299
243 $urxvt::TERM 300 $urxvt::TERM
244 The current terminal. This variable stores the current "urxvt::term" 301 The current terminal. This variable stores the current "urxvt::term"
245 object, whenever a callback/hook is executing. 302 object, whenever a callback/hook is executing.
303
304 *
246 305
247 Functions in the "urxvt" Package 306 Functions in the "urxvt" Package
248 $term = new urxvt [arg...] 307 $term = new urxvt [arg...]
249 Creates a new terminal, very similar as if you had started it with 308 Creates a new terminal, very similar as if you had started it with
250 "system $binfile, arg...". Croaks (and probably outputs an error 309 "system $binfile, arg...". Croaks (and probably outputs an error
… …
264 function that calls this function. 323 function that calls this function.
265 324
266 Using this function has the advantage that its output ends up in the 325 Using this function has the advantage that its output ends up in the
267 correct place, e.g. on stderr of the connecting urxvtc client. 326 correct place, e.g. on stderr of the connecting urxvtc client.
268 327
328 $is_safe = urxvt::safe
329 Returns true when it is safe to do potentially unsafe things, such
330 as evaluating perl code specified by the user. This is true when
331 urxvt was started setuid or setgid.
332
269 $time = urxvt::NOW 333 $time = urxvt::NOW
270 Returns the "current time" (as per the event loop). 334 Returns the "current time" (as per the event loop).
335
336 urxvt::CurrentTime
337 urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask,
338 Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask,
339 Button5Mask, AnyModifier
340 Various constants for use in X calls and event processing.
271 341
272 RENDITION 342 RENDITION
273 Rendition bitsets contain information about colour, font, font styles 343 Rendition bitsets contain information about colour, font, font styles
274 and similar information for each screen cell. 344 and similar information for each screen cell.
275 345
… …
293 363
294 $foreground = urxvt::GET_BASEFG $rend 364 $foreground = urxvt::GET_BASEFG $rend
295 $background = urxvt::GET_BASEBG $rend 365 $background = urxvt::GET_BASEBG $rend
296 Return the foreground/background colour index, respectively. 366 Return the foreground/background colour index, respectively.
297 367
298 $rend = urxvt::SET_FGCOLOR ($rend, $new_colour) 368 $rend = urxvt::SET_FGCOLOR $rend, $new_colour
299 $rend = urxvt::SET_BGCOLOR ($rend, $new_colour) 369 $rend = urxvt::SET_BGCOLOR $rend, $new_colour
300 Replace the foreground/background colour in the rendition mask with 370 Replace the foreground/background colour in the rendition mask with
301 the specified one. 371 the specified one.
302 372
303 $value = urxvt::GET_CUSTOM ($rend) 373 $value = urxvt::GET_CUSTOM $rend
304 Return the "custom" value: Every rendition has 5 bits for use by 374 Return the "custom" value: Every rendition has 5 bits for use by
305 extensions. They can be set and changed as you like and are 375 extensions. They can be set and changed as you like and are
306 initially zero. 376 initially zero.
307 377
308 $rend = urxvt::SET_CUSTOM ($rend, $new_value) 378 $rend = urxvt::SET_CUSTOM $rend, $new_value
309 Change the custom value. 379 Change the custom value.
380
381 The "urxvt::anyevent" Class
382 The sole purpose of this class is to deliver an interface to the
383 "AnyEvent" module - any module using it will work inside urxvt without
384 further programming. The only exception is that you cannot wait on
385 condition variables, but non-blocking condvar use is ok. What this means
386 is that you cannot use blocking APIs, but the non-blocking variant
387 should work.
310 388
311 The "urxvt::term" Class 389 The "urxvt::term" Class
312 $term->destroy 390 $term->destroy
313 Destroy the terminal object (close the window, free resources etc.). 391 Destroy the terminal object (close the window, free resources etc.).
392 Please note that rxvt will not exit as long as any event watchers
393 (timers, io watchers) are still active.
394
395 $isset = $term->option ($optval[, $set])
396 Returns true if the option specified by $optval is enabled, and
397 optionally change it. All option values are stored by name in the
398 hash %urxvt::OPTION. Options not enabled in this binary are not in
399 the hash.
400
401 Here is a a likely non-exhaustive list of option names, please see
402 the source file /src/optinc.h to see the actual list:
403
404 borderLess console cursorBlink cursorUnderline hold iconic insecure
405 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
406 pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating
407 scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer
408 secondaryScreen secondaryScroll skipBuiltinGlyphs transparent
409 tripleclickwords utmpInhibit visualBell
314 410
315 $value = $term->resource ($name[, $newval]) 411 $value = $term->resource ($name[, $newval])
316 Returns the current resource value associated with a given name and 412 Returns the current resource value associated with a given name and
317 optionally sets a new value. Setting values is most useful in the 413 optionally sets a new value. Setting values is most useful in the
318 "init" hook. Unset resources are returned and accepted as "undef". 414 "init" hook. Unset resources are returned and accepted as "undef".
… …
328 Please note that resource strings will currently only be freed when 424 Please note that resource strings will currently only be freed when
329 the terminal is destroyed, so changing options frequently will eat 425 the terminal is destroyed, so changing options frequently will eat
330 memory. 426 memory.
331 427
332 Here is a a likely non-exhaustive list of resource names, not all of 428 Here is a a likely non-exhaustive list of resource names, not all of
333 which are supported in every build, please see the source to see the 429 which are supported in every build, please see the source file
334 actual list: 430 /src/rsinc.h to see the actual list:
335 431
336 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 432 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
337 borderLess color cursorBlink cursorUnderline cutchars delete_key 433 borderLess color cursorBlink cursorUnderline cutchars delete_key
338 display_name embed ext_bwidth fade font geometry hold iconName 434 display_name embed ext_bwidth fade font geometry hold iconName
339 imFont imLocale inputMethod insecure int_bwidth intensityStyles 435 imFont imLocale inputMethod insecure int_bwidth intensityStyles
… …
344 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 440 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
345 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 441 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
346 shade term_name title transparent transparent_all tripleclickwords 442 shade term_name title transparent transparent_all tripleclickwords
347 utmpInhibit visualBell 443 utmpInhibit visualBell
348 444
445 $success = $term->parse_keysym ($keysym_spec, $command_string)
446 Adds a keymap translation exactly as specified via a resource. See
447 the "keysym" resource in the rxvt(1) manpage.
448
349 $rend = $term->rstyle ([$new_rstyle]) 449 $rend = $term->rstyle ([$new_rstyle])
350 Return and optionally change the current rendition. Text that is 450 Return and optionally change the current rendition. Text that is
351 output by the terminal application will use this style. 451 output by the terminal application will use this style.
352 452
353 ($row, $col) = $term->screen_cur ([$row, $col]) 453 ($row, $col) = $term->screen_cur ([$row, $col])
… …
367 467
368 $oldtext = $term->selection ([$newtext]) 468 $oldtext = $term->selection ([$newtext])
369 Return the current selection text and optionally replace it by 469 Return the current selection text and optionally replace it by
370 $newtext. 470 $newtext.
371 471
372 #=item $term->overlay ($x, $y, $text) # #Create a simple multi-line 472 $term->overlay_simple ($x, $y, $text)
373 overlay box. See the next method for details. # #=cut # #sub 473 Create a simple multi-line overlay box. See the next method for
374 urxvt::term::scr_overlay { # my ($self, $x, $y, $text) = @_; # # my 474 details.
375 @lines = split /\n/, $text; # # my $w = 0; # for (map
376 $self->strwidth ($_), @lines) { # $w = $_ if $w < $_; # } # #
377 $self->scr_overlay_new ($x, $y, $w, scalar @lines); #
378 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; #}
379 475
380 $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 476 $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
381 Create a new (empty) overlay at the given position with the given 477 Create a new (empty) overlay at the given position with the given
382 width/height. $rstyle defines the initial rendition style (default: 478 width/height. $rstyle defines the initial rendition style (default:
383 "OVERLAY_RSTYLE"). 479 "OVERLAY_RSTYLE").
… …
402 If visible, hide the overlay, but do not destroy it. 498 If visible, hide the overlay, but do not destroy it.
403 499
404 $overlay->show 500 $overlay->show
405 If hidden, display the overlay again. 501 If hidden, display the overlay again.
406 502
503 $popup = $term->popup ($event)
504 Creates a new "urxvt::popup" object that implements a popup menu.
505 The $event *must* be the event causing the menu to pop up (a button
506 event, currently).
507
407 $cellwidth = $term->strwidth ($string) 508 $cellwidth = $term->strwidth ($string)
408 Returns the number of screen-cells this string would need. Correctly 509 Returns the number of screen-cells this string would need. Correctly
409 accounts for wide and combining characters. 510 accounts for wide and combining characters.
410 511
411 $octets = $term->locale_encode ($string) 512 $octets = $term->locale_encode ($string)
412 Convert the given text string into the corresponding locale 513 Convert the given text string into the corresponding locale
413 encoding. 514 encoding.
414 515
415 $string = $term->locale_decode ($octets) 516 $string = $term->locale_decode ($octets)
416 Convert the given locale-encoded octets into a perl string. 517 Convert the given locale-encoded octets into a perl string.
518
519 $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
520 XORs the rendition values in the given span with the provided value
521 (default: "RS_RVid"). Useful in refresh hooks to provide effects
522 similar to the selection.
523
524 $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[,
525 $rstyle2]])
526 Similar to "scr_xor_span", but xors a rectangle instead. Trailing
527 whitespace will additionally be xored with the $rstyle2, which
528 defaults to "RS_RVid | RS_Uline", which removes reverse video again
529 and underlines it instead.
530
531 $term->scr_bell
532 Ring the bell!
417 533
418 $term->scr_add_lines ($string) 534 $term->scr_add_lines ($string)
419 Write the given text string to the screen, as if output by the 535 Write the given text string to the screen, as if output by the
420 application running inside the terminal. It may not contain command 536 application running inside the terminal. It may not contain command
421 sequences (escape codes), but is free to use line feeds, carriage 537 sequences (escape codes), but is free to use line feeds, carriage
… …
434 $term->tt_write ($octets) 550 $term->tt_write ($octets)
435 Write the octets given in $data to the tty (i.e. as program input). 551 Write the octets given in $data to the tty (i.e. as program input).
436 To pass characters instead of octets, you should convert your 552 To pass characters instead of octets, you should convert your
437 strings first to the locale-specific encoding using 553 strings first to the locale-specific encoding using
438 "$term->locale_encode". 554 "$term->locale_encode".
555
556 $old_events = $term->pty_ev_events ([$new_events])
557 Replaces the event mask of the pty watcher by the given event mask.
558 Can be used to suppress input and output handling to the pty/tty.
559 See the description of "urxvt::timer->events". Make sure to always
560 restore the previous value.
439 561
440 $windowid = $term->parent 562 $windowid = $term->parent
441 Return the window id of the toplevel window. 563 Return the window id of the toplevel window.
442 564
443 $windowid = $term->vt 565 $windowid = $term->vt
… …
455 $max_scrollback = $term->saveLines 577 $max_scrollback = $term->saveLines
456 $nrow_plus_saveLines = $term->total_rows 578 $nrow_plus_saveLines = $term->total_rows
457 $lines_in_scrollback = $term->nsaved 579 $lines_in_scrollback = $term->nsaved
458 Return various integers describing terminal characteristics. 580 Return various integers describing terminal characteristics.
459 581
582 $lc_ctype = $term->locale
583 Returns the LC_CTYPE category string used by this rxvt-unicode.
584
585 $x_display = $term->display_id
586 Return the DISPLAY used by rxvt-unicode.
587
588 $modifiermask = $term->ModLevel3Mask
589 $modifiermask = $term->ModMetaMask
590 $modifiermask = $term->ModNumLockMask
591 Return the modifier masks corresponding to the "ISO Level 3 Shift"
592 (often AltGr), the meta key (often Alt) and the num lock key, if
593 applicable.
594
460 $view_start = $term->view_start ([$newvalue]) 595 $view_start = $term->view_start ([$newvalue])
461 Returns the negative row number of the topmost line. Minimum value 596 Returns the negative row number of the topmost line. Minimum value
462 is 0, which displays the normal terminal contents. Larger values 597 is 0, which displays the normal terminal contents. Larger values
463 scroll this many lines into the scrollback buffer. 598 scroll this many lines into the scrollback buffer.
464 599
… …
540 the logical line. 675 the logical line.
541 676
542 ($row, $col) = $line->coord_of ($offset) 677 ($row, $col) = $line->coord_of ($offset)
543 Translates a string offset into terminal coordinates again. 678 Translates a string offset into terminal coordinates again.
544 679
545 ($row, $col) = $line->coord_of ($offset) =item $text =
546 $term->special_encode $string 680 $text = $term->special_encode $string
547 Converts a perl string into the special encoding used by 681 Converts a perl string into the special encoding used by
548 rxvt-unicode, where one character corresponds to one screen cell. 682 rxvt-unicode, where one character corresponds to one screen cell.
549 See "$term->ROW_t" for details. 683 See "$term->ROW_t" for details.
550 684
551 $string = $term->special_decode $text 685 $string = $term->special_decode $text
552 Converts rxvt-unicodes text reprsentation into a perl string. See 686 Converts rxvt-unicodes text reprsentation into a perl string. See
553 "$term->ROW_t" for details. 687 "$term->ROW_t" for details.
554 688
689 $success = $term->grab_button ($button, $modifiermask)
690 Registers a synchronous button grab. See the XGrabButton manpage.
691
692 $success = $term->grab ($eventtime[, $sync])
693 Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
694 synchronous ($sync is true). Also remembers the grab timestampe.
695
696 $term->allow_events_async
697 Calls XAllowEvents with AsyncBoth for the most recent grab.
698
699 $term->allow_events_sync
700 Calls XAllowEvents with SyncBoth for the most recent grab.
701
702 $term->allow_events_replay
703 Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for
704 the most recent grab.
705
706 $term->ungrab
707 Calls XUngrab for the most recent grab. Is called automatically on
708 evaluation errors, as it is better to lose the grab in the error
709 case as the session.
710
711 The "urxvt::popup" Class
712 $popup->add_title ($title)
713 Adds a non-clickable title to the popup.
714
715 $popup->add_separator ([$sepchr])
716 Creates a separator, optionally using the character given as
717 $sepchr.
718
719 $popup->add_button ($text, $cb)
720 Adds a clickable button to the popup. $cb is called whenever it is
721 selected.
722
723 $popup->add_toggle ($text, $cb, $initial_value)
724 Adds a toggle/checkbox item to the popup. Teh callback gets called
725 whenever it gets toggled, with a boolean indicating its value as its
726 first argument.
727
728 $popup->show
729 Displays the popup (which is initially hidden).
730
555 The "urxvt::timer" Class 731 The "urxvt::timer" Class
556 This class implements timer watchers/events. Time is represented as a 732 This class implements timer watchers/events. Time is represented as
557 fractional number of seconds since the epoch. Example: 733 a fractional number of seconds since the epoch. Example:
558 734
559 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0); 735 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
560 $term->{timer} = urxvt::timer 736 $term->{timer} = urxvt::timer
561 ->new 737 ->new
562 ->interval (1) 738 ->interval (1)
563 ->cb (sub { 739 ->cb (sub {
564 $term->{overlay}->set (0, 0, 740 $term->{overlay}->set (0, 0,
565 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]); 741 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
566 }); 742 });
567 743
568 $timer = new urxvt::timer 744 $timer = new urxvt::timer
569 Create a new timer object in started state. It is scheduled to fire 745 Create a new timer object in started state. It is scheduled to
570 immediately. 746 fire immediately.
571 747
572 $timer = $timer->cb (sub { my ($timer) = @_; ... }) 748 $timer = $timer->cb (sub { my ($timer) = @_; ... })
573 Set the callback to be called when the timer triggers. 749 Set the callback to be called when the timer triggers.
574 750
575 $tstamp = $timer->at 751 $tstamp = $timer->at
576 Return the time this watcher will fire next. 752 Return the time this watcher will fire next.
577 753
578 $timer = $timer->set ($tstamp) 754 $timer = $timer->set ($tstamp)
579 Set the time the event is generated to $tstamp. 755 Set the time the event is generated to $tstamp.
580 756
581 $timer = $timer->interval ($interval) 757 $timer = $timer->interval ($interval)
582 Normally (and when $interval is 0), the timer will automatically 758 Normally (and when $interval is 0), the timer will automatically
583 stop after it has fired once. If $interval is non-zero, then the 759 stop after it has fired once. If $interval is non-zero, then the
584 timer is automatically rescheduled at the given intervals. 760 timer is automatically rescheduled at the given intervals.
585 761
586 $timer = $timer->start 762 $timer = $timer->start
587 Start the timer. 763 Start the timer.
588 764
589 $timer = $timer->start ($tstamp) 765 $timer = $timer->start ($tstamp)
590 Set the event trigger time to $tstamp and start the timer. 766 Set the event trigger time to $tstamp and start the timer.
591 767
592 $timer = $timer->stop 768 $timer = $timer->stop
593 Stop the timer. 769 Stop the timer.
594 770
595 The "urxvt::iow" Class 771 The "urxvt::iow" Class
596 This class implements io watchers/events. Example: 772 This class implements io watchers/events. Example:
597 773
598 $term->{socket} = ... 774 $term->{socket} = ...
599 $term->{iow} = urxvt::iow 775 $term->{iow} = urxvt::iow
600 ->new 776 ->new
601 ->fd (fileno $term->{socket}) 777 ->fd (fileno $term->{socket})
602 ->events (1) # wait for read data 778 ->events (urxvt::EVENT_READ)
603 ->start 779 ->start
604 ->cb (sub { 780 ->cb (sub {
605 my ($iow, $revents) = @_; 781 my ($iow, $revents) = @_;
606 # $revents must be 1 here, no need to check 782 # $revents must be 1 here, no need to check
607 sysread $term->{socket}, my $buf, 8192 783 sysread $term->{socket}, my $buf, 8192
608 or end-of-file; 784 or end-of-file;
609 }); 785 });
610 786
611 $iow = new urxvt::iow 787 $iow = new urxvt::iow
612 Create a new io watcher object in stopped state. 788 Create a new io watcher object in stopped state.
613 789
614 $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... }) 790 $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
615 Set the callback to be called when io events are triggered. 791 Set the callback to be called when io events are triggered.
616 $reventmask is a bitset as described in the "events" method. 792 $reventmask is a bitset as described in the "events" method.
617 793
618 $iow = $iow->fd ($fd) 794 $iow = $iow->fd ($fd)
619 Set the filedescriptor (not handle) to watch. 795 Set the filedescriptor (not handle) to watch.
620 796
621 $iow = $iow->events ($eventmask) 797 $iow = $iow->events ($eventmask)
622 Set the event mask to watch. Bit #0 (value 1) enables watching for 798 Set the event mask to watch. The only allowed values are
623 read data, Bit #1 (value 2) enables watching for write data. 799 "urxvt::EVENT_READ" and "urxvt::EVENT_WRITE", which might be
800 ORed together, or "urxvt::EVENT_NONE".
624 801
625 $iow = $iow->start 802 $iow = $iow->start
626 Start watching for requested events on the given handle. 803 Start watching for requested events on the given handle.
627 804
628 $iow = $iow->stop 805 $iow = $iow->stop
629 Stop watching for events on the given filehandle. 806 Stop watching for events on the given filehandle.
630 807
631ENVIRONMENT 808ENVIRONMENT
632 URXVT_PERL_VERBOSITY 809 URXVT_PERL_VERBOSITY
633 This variable controls the verbosity level of the perl extension. Higher 810 This variable controls the verbosity level of the perl extension.
634 numbers indicate more verbose output. 811 Higher numbers indicate more verbose output.
635 812
636 =0 - only fatal messages 813 == 0 - fatal messages
637 =3 - script loading and management 814 >= 3 - script loading and management
638 =10 - all events received 815 >=10 - all events received
639 816
640AUTHOR 817AUTHOR
641 Marc Lehmann <pcg@goof.com> 818 Marc Lehmann <pcg@goof.com>
642 http://software.schmorp.de/pkg/rxvt-unicode 819 http://software.schmorp.de/pkg/rxvt-unicode
643 820

Diff Legend

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