ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/rxvt-unicode/doc/rxvtperl.3.txt
Revision: 1.15
Committed: Mon Jan 9 01:36:56 2006 UTC (18 years, 5 months ago) by root
Content type: text/plain
Branch: MAIN
Changes since 1.14: +31 -10 lines
Log Message:
*** empty log message ***

File Contents

# User Rev Content
1 root 1.1 NAME
2     rxvtperl - rxvt-unicode's embedded perl interpreter
3    
4     SYNOPSIS
5 root 1.3 # create a file grab_test in $HOME:
6 root 1.1
7     sub on_sel_grab {
8     warn "you selected ", $_[0]->selection;
9     ()
10     }
11    
12 root 1.3 # start a rxvt using it:
13    
14     rxvt --perl-lib $HOME -pe grab_test
15 root 1.1
16     DESCRIPTION
17 root 1.13 Everytime a terminal object gets created, extension scripts specified
18     via the "perl" resource are loaded and associated with it.
19 root 1.3
20     Scripts are compiled in a 'use strict' and 'use utf8' environment, and
21     thus must be encoded as UTF-8.
22 root 1.1
23     Each script will only ever be loaded once, even in rxvtd, where scripts
24 root 1.5 will be shared (but not enabled) for all terminals.
25 root 1.1
26 root 1.5 Prepackaged Extensions
27 root 1.4 This section describes the extensiosn delivered with this version. You
28     can find them in /opt/rxvt/lib/urxvt/perl/.
29    
30     You can activate them like this:
31    
32     rxvt -pe <extensionname>
33    
34 root 1.14 selection (enabled by default)
35 root 1.8 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 root 1.7
40     It also offers the following bindable event:
41 root 1.4
42     rot13
43     Rot-13 the selection when activated. Used via keyboard trigger:
44    
45     URxvt.keysym.C-M-r: perl:selection:rot13
46    
47 root 1.14 option-popup (enabled by default)
48 root 1.15 Binds a popup menu to Ctrl-Button2 that lets you toggle (some)
49 root 1.14 options at runtime.
50    
51 root 1.15 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    
55 root 1.4 digital-clock
56 root 1.6 Displays a digital clock using the built-in overlay.
57    
58 root 1.12 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.
66    
67 root 1.6 example-refresh-hooks
68 root 1.4 Displays a very simple digital clock in the upper right corner of
69     the window. Illustrates overwriting the refresh callbacks to create
70     your own overlays or changes.
71    
72 root 1.1 General API Considerations
73     All objects (such as terminals, time watchers etc.) are typical
74     reference-to-hash objects. The hash can be used to store anything you
75     like. All members starting with an underscore (such as "_ptr" or
76 root 1.7 "_hook") are reserved for internal uses and MUST NOT be accessed or
77 root 1.1 modified).
78    
79     When objects are destroyed on the C++ side, the perl object hashes are
80     emptied, so its best to store related objects such as time watchers and
81     the like inside the terminal object so they get destroyed as soon as the
82     terminal is destroyed.
83    
84 root 1.12 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    
101 root 1.1 Hooks
102 root 1.12 The following subroutines can be declared in extension files, and will
103     be called whenever the relevant event happens.
104 root 1.1
105 root 1.7 The first argument passed to them is an object private to each terminal
106     and extension package. You can call all "urxvt::term" methods on it, but
107     its not a real "urxvt::term" object. Instead, the real "urxvt::term"
108     object that is shared between all packages is stored in the "term"
109 root 1.13 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.
112 root 1.7
113 root 1.1 All of them must return a boolean value. If it is true, then the event
114     counts as being *consumed*, and the invocation of other hooks is
115     skipped, and the relevant action might not be carried out by the C++
116     code.
117    
118     When in doubt, return a false value (preferably "()").
119    
120     on_init $term
121     Called after a new terminal object has been initialized, but before
122 root 1.12 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.
126 root 1.1
127     on_reset $term
128     Called after the screen is "reset" for any reason, such as resizing
129     or control sequences. Here is where you can react on changes to
130     size-related variables.
131    
132     on_start $term
133     Called at the very end of initialisation of a new terminal, just
134     before returning to the mainloop.
135    
136     on_sel_make $term, $eventtime
137     Called whenever a selection has been made by the user, but before
138     the selection text is copied, so changes to the beginning, end or
139     type of the selection will be honored.
140    
141     Returning a true value aborts selection making by urxvt, in which
142     case you have to make a selection yourself by calling
143     "$term->selection_grab".
144    
145     on_sel_grab $term, $eventtime
146     Called whenever a selection has been copied, but before the
147     selection is requested from the server. The selection text can be
148     queried and changed by calling "$term->selection".
149    
150     Returning a true value aborts selection grabbing. It will still be
151     hilighted.
152    
153 root 1.7 on_sel_extend $term
154     Called whenever the user tries to extend the selection (e.g. with a
155     double click) and is either supposed to return false (normal
156     operation), or should extend the selection itelf and return true to
157     suppress the built-in processing.
158    
159     See the selection example extension.
160    
161 root 1.1 on_view_change $term, $offset
162     Called whenever the view offset changes, i..e the user or program
163     scrolls. Offset 0 means display the normal terminal, positive values
164     show this many lines of scrollback.
165    
166     on_scroll_back $term, $lines, $saved
167     Called whenever lines scroll out of the terminal area into the
168     scrollback buffer. $lines is the number of lines scrolled out and
169     may be larger than the scroll back buffer or the terminal.
170    
171     It is called before lines are scrolled out (so rows 0 .. min ($lines
172     - 1, $nrow - 1) represent the lines to be scrolled out). $saved is
173     the total number of lines that will be in the scrollback buffer.
174    
175 root 1.9 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 root 1.12 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    
208 root 1.1 on_refresh_begin $term
209     Called just before the screen gets redrawn. Can be used for overlay
210     or similar effects by modify terminal contents in refresh_begin, and
211     restoring them in refresh_end. The built-in overlay and selection
212     display code is run after this hook, and takes precedence.
213    
214     on_refresh_end $term
215     Called just after the screen gets redrawn. See "on_refresh_begin".
216    
217 root 1.3 on_keyboard_command $term, $string
218     Called whenever the user presses a key combination that has a
219     "perl:string" action bound to it (see description of the keysym
220     resource in the rxvt(1) manpage).
221    
222 root 1.13 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 root 1.12 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 root 1.13 on_map_notify $term, $event
236     on_unmap_notify $term, $event
237 root 1.12 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 root 1.7 Variables in the "urxvt" Package
251     $urxvt::TERM
252 root 1.12 The current terminal. This variable stores the current "urxvt::term"
253     object, whenever a callback/hook is executing.
254 root 1.7
255 root 1.1 Functions in the "urxvt" Package
256 root 1.12 $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    
264 root 1.1 urxvt::fatal $errormessage
265     Fatally aborts execution with the given error message. Avoid at all
266     costs! The only time this is acceptable is when the terminal process
267     starts up.
268    
269     urxvt::warn $string
270     Calls "rxvt_warn" with the given string which should not include a
271     newline. The module also overwrites the "warn" builtin with a
272     function that calls this function.
273    
274     Using this function has the advantage that its output ends up in the
275     correct place, e.g. on stderr of the connecting urxvtc client.
276    
277     $time = urxvt::NOW
278     Returns the "current time" (as per the event loop).
279    
280 root 1.13 urxvt::CurrentTime
281     urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask,
282     Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask,
283     Button5Mask, AnyModifier
284 root 1.14 Various constants for use in X calls and event processing.
285 root 1.13
286 root 1.6 RENDITION
287     Rendition bitsets contain information about colour, font, font styles
288     and similar information for each screen cell.
289    
290     The following "macros" deal with changes in rendition sets. You should
291     never just create a bitset, you should always modify an existing one, as
292     they contain important information required for correct operation of
293     rxvt-unicode.
294    
295     $rend = urxvt::DEFAULT_RSTYLE
296     Returns the default rendition, as used when the terminal is starting
297     up or being reset. Useful as a base to start when creating
298     renditions.
299    
300     $rend = urxvt::OVERLAY_RSTYLE
301     Return the rendition mask used for overlays by default.
302    
303     $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
304     Return the bit that enabled bold, italic, blink, reverse-video and
305     underline, respectively. To enable such a style, just logically OR
306     it into the bitset.
307    
308     $foreground = urxvt::GET_BASEFG $rend
309     $background = urxvt::GET_BASEBG $rend
310     Return the foreground/background colour index, respectively.
311    
312     $rend = urxvt::SET_FGCOLOR ($rend, $new_colour)
313     $rend = urxvt::SET_BGCOLOR ($rend, $new_colour)
314     Replace the foreground/background colour in the rendition mask with
315     the specified one.
316    
317     $value = urxvt::GET_CUSTOM ($rend)
318     Return the "custom" value: Every rendition has 5 bits for use by
319     extensions. They can be set and changed as you like and are
320     initially zero.
321    
322     $rend = urxvt::SET_CUSTOM ($rend, $new_value)
323     Change the custom value.
324    
325 root 1.14 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    
332 root 1.1 The "urxvt::term" Class
333 root 1.12 $term->destroy
334     Destroy the terminal object (close the window, free resources etc.).
335    
336 root 1.13 $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    
352 root 1.1 $value = $term->resource ($name[, $newval])
353     Returns the current resource value associated with a given name and
354     optionally sets a new value. Setting values is most useful in the
355     "init" hook. Unset resources are returned and accepted as "undef".
356    
357     The new value must be properly encoded to a suitable character
358     encoding before passing it to this method. Similarly, the returned
359     value may need to be converted from the used encoding to text.
360    
361     Resource names are as defined in src/rsinc.h. Colours can be
362     specified as resource names of the form "color+<index>", e.g.
363     "color+5". (will likely change).
364    
365     Please note that resource strings will currently only be freed when
366     the terminal is destroyed, so changing options frequently will eat
367     memory.
368    
369     Here is a a likely non-exhaustive list of resource names, not all of
370 root 1.13 which are supported in every build, please see the source file
371     /src/rsinc.h to see the actual list:
372 root 1.1
373     answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
374     borderLess color cursorBlink cursorUnderline cutchars delete_key
375     display_name embed ext_bwidth fade font geometry hold iconName
376     imFont imLocale inputMethod insecure int_bwidth intensityStyles
377 root 1.2 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
378 root 1.10 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2
379 root 1.1 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
380     reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
381     scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
382     scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
383     shade term_name title transparent transparent_all tripleclickwords
384     utmpInhibit visualBell
385    
386 root 1.12 $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 root 1.11
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    
395 root 1.1 ($row, $col) = $term->selection_mark ([$row, $col])
396     ($row, $col) = $term->selection_beg ([$row, $col])
397     ($row, $col) = $term->selection_end ([$row, $col])
398     Return the current values of the selection mark, begin or end
399     positions, and optionally set them to new values.
400    
401     $success = $term->selection_grab ($eventtime)
402     Try to request the primary selection from the server (for example,
403     as set by the next method).
404    
405     $oldtext = $term->selection ([$newtext])
406     Return the current selection text and optionally replace it by
407     $newtext.
408    
409 root 1.6 #=item $term->overlay ($x, $y, $text) # #Create a simple multi-line
410 root 1.12 overlay box. See the next method for details. # #=cut # #sub
411     urxvt::term::scr_overlay { # my ($self, $x, $y, $text) = @_; # # my
412     @lines = split /\n/, $text; # # my $w = 0; # for (map
413     $self->strwidth ($_), @lines) { # $w = $_ if $w < $_; # } # #
414     $self->scr_overlay_new ($x, $y, $w, scalar @lines); #
415     $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; #}
416 root 1.6
417     $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
418 root 1.1 Create a new (empty) overlay at the given position with the given
419 root 1.6 width/height. $rstyle defines the initial rendition style (default:
420     "OVERLAY_RSTYLE").
421    
422     If $border is 2 (default), then a decorative border will be put
423     around the box.
424    
425     If either $x or $y is negative, then this is counted from the
426     right/bottom side, respectively.
427    
428     This method returns an urxvt::overlay object. The overlay will be
429     visible as long as the perl object is referenced.
430 root 1.1
431 root 1.7 The methods currently supported on "urxvt::overlay" objects are:
432 root 1.6
433 root 1.7 $overlay->set ($x, $y, $text, $rend)
434     Similar to "$term->ROW_t" and "$term->ROW_r" in that it puts
435     text in rxvt-unicode's special encoding and an array of
436     rendition values at a specific position inside the overlay.
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 root 1.1
444 root 1.13 $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    
449 root 1.12 $cellwidth = $term->strwidth ($string)
450 root 1.1 Returns the number of screen-cells this string would need. Correctly
451     accounts for wide and combining characters.
452    
453 root 1.12 $octets = $term->locale_encode ($string)
454 root 1.1 Convert the given text string into the corresponding locale
455     encoding.
456    
457 root 1.12 $string = $term->locale_decode ($octets)
458 root 1.1 Convert the given locale-encoded octets into a perl string.
459    
460 root 1.12 $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.
475    
476 root 1.1 $term->tt_write ($octets)
477     Write the octets given in $data to the tty (i.e. as program input).
478 root 1.4 To pass characters instead of octets, you should convert your
479     strings first to the locale-specific encoding using
480     "$term->locale_encode".
481    
482 root 1.12 $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 root 1.11 $window_width = $term->width
489     $window_height = $term->height
490     $font_width = $term->fwidth
491     $font_height = $term->fheight
492     $font_ascent = $term->fbase
493     $terminal_rows = $term->nrow
494     $terminal_columns = $term->ncol
495     $has_focus = $term->focus
496     $is_mapped = $term->mapped
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 root 1.4
502 root 1.13 $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.
508    
509 root 1.4 $view_start = $term->view_start ([$newvalue])
510     Returns the negative row number of the topmost line. Minimum value
511     is 0, which displays the normal terminal contents. Larger values
512     scroll this many lines into the scrollback buffer.
513    
514     $term->want_refresh
515     Requests a screen refresh. At the next opportunity, rxvt-unicode
516     will compare the on-screen display with its stored representation.
517     If they differ, it redraws the differences.
518    
519     Used after changing terminal contents to display them.
520    
521     $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
522     Returns the text of the entire row with number $row_number. Row 0 is
523     the topmost terminal line, row "$term->$ncol-1" is the bottommost
524     terminal line. The scrollback buffer starts at line -1 and extends
525 root 1.7 to line "-$term->nsaved". Nothing will be returned if a nonexistent
526     line is requested.
527 root 1.4
528     If $new_text is specified, it will replace characters in the current
529     line, starting at column $start_col (default 0), which is useful to
530 root 1.6 replace only parts of a line. The font index in the rendition will
531 root 1.4 automatically be updated.
532    
533     $text is in a special encoding: tabs and wide characters that use
534     more than one cell when displayed are padded with urxvt::NOCHAR
535     characters ("chr 65535"). Characters with combining characters and
536     other characters that do not fit into the normal tetx encoding will
537     be replaced with characters in the private use area.
538    
539     You have to obey this encoding when changing text. The advantage is
540     that "substr" and similar functions work on screen cells and not on
541     characters.
542    
543     The methods "$term->special_encode" and "$term->special_decode" can
544     be used to convert normal strings into this encoding and vice versa.
545    
546     $rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])
547     Like "$term->ROW_t", but returns an arrayref with rendition bitsets.
548     Rendition bitsets contain information about colour, font, font
549     styles and similar information. See also "$term->ROW_t".
550    
551     When setting rendition, the font mask will be ignored.
552    
553 root 1.6 See the section on RENDITION, above.
554 root 1.4
555     $length = $term->ROW_l ($row_number[, $new_length])
556     Returns the number of screen cells that are in use ("the line
557 root 1.7 length"). Unlike the urxvt core, this returns "$term->ncol" if the
558     line is joined with the following one.
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 root 1.12 $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 root 1.7
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 root 1.4
594 root 1.15 $text = $term->special_encode $string
595 root 1.4 Converts a perl string into the special encoding used by
596     rxvt-unicode, where one character corresponds to one screen cell.
597     See "$term->ROW_t" for details.
598    
599     $string = $term->special_decode $text
600     Converts rxvt-unicodes text reprsentation into a perl string. See
601     "$term->ROW_t" for details.
602    
603 root 1.15 $success = $term->grab_button ($button, $modifiermask)
604     Registers a synchronous button grab. See XGrabButton.
605    
606     $success = $term->grab ($eventtime[, $sync])
607     Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
608     synchronous ($sync is true). Also remembers the grab timestampe.
609    
610     $term->allow_events_async
611     Calls XAllowEvents with AsyncBoth for the most recent grab.
612    
613     $term->allow_events_sync
614     Calls XAllowEvents with SyncBoth for the most recent grab.
615    
616     $term->allow_events_replay
617     Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for
618     the most recent grab.
619    
620     $term->ungrab
621     Calls XUngrab for the most recent grab. Is called automatically on
622     evaluation errors, as it is better to lose the grab in the error
623     case as the session.
624    
625 root 1.13 The "urxvt::popup" Class
626 root 1.1 The "urxvt::timer" Class
627 root 1.13 This class implements timer watchers/events. Time is represented as
628     a fractional number of seconds since the epoch. Example:
629 root 1.1
630 root 1.13 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
631     $term->{timer} = urxvt::timer
632     ->new
633     ->interval (1)
634     ->cb (sub {
635     $term->{overlay}->set (0, 0,
636     sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
637     });
638    
639     $timer = new urxvt::timer
640     Create a new timer object in started state. It is scheduled to
641     fire immediately.
642    
643     $timer = $timer->cb (sub { my ($timer) = @_; ... })
644     Set the callback to be called when the timer triggers.
645    
646     $tstamp = $timer->at
647     Return the time this watcher will fire next.
648    
649     $timer = $timer->set ($tstamp)
650     Set the time the event is generated to $tstamp.
651    
652     $timer = $timer->interval ($interval)
653     Normally (and when $interval is 0), the timer will automatically
654     stop after it has fired once. If $interval is non-zero, then the
655     timer is automatically rescheduled at the given intervals.
656 root 1.6
657 root 1.13 $timer = $timer->start
658     Start the timer.
659 root 1.1
660 root 1.13 $timer = $timer->start ($tstamp)
661     Set the event trigger time to $tstamp and start the timer.
662 root 1.1
663 root 1.13 $timer = $timer->stop
664     Stop the timer.
665 root 1.1
666     The "urxvt::iow" Class
667 root 1.13 This class implements io watchers/events. Example:
668 root 1.1
669 root 1.13 $term->{socket} = ...
670     $term->{iow} = urxvt::iow
671     ->new
672     ->fd (fileno $term->{socket})
673     ->events (1) # wait for read data
674     ->start
675     ->cb (sub {
676     my ($iow, $revents) = @_;
677     # $revents must be 1 here, no need to check
678     sysread $term->{socket}, my $buf, 8192
679     or end-of-file;
680     });
681    
682     $iow = new urxvt::iow
683     Create a new io watcher object in stopped state.
684    
685     $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
686     Set the callback to be called when io events are triggered.
687     $reventmask is a bitset as described in the "events" method.
688    
689     $iow = $iow->fd ($fd)
690     Set the filedescriptor (not handle) to watch.
691    
692     $iow = $iow->events ($eventmask)
693     Set the event mask to watch. Bit #0 (value 1) enables watching
694     for read data, Bit #1 (value 2) enables watching for write data.
695 root 1.1
696 root 1.13 $iow = $iow->start
697     Start watching for requested events on the given handle.
698 root 1.1
699 root 1.13 $iow = $iow->stop
700     Stop watching for events on the given filehandle.
701 root 1.1
702     ENVIRONMENT
703     URXVT_PERL_VERBOSITY
704 root 1.13 This variable controls the verbosity level of the perl extension.
705     Higher numbers indicate more verbose output.
706 root 1.1
707 root 1.15 == 0 - fatal messages
708     >= 3 - script loading and management
709     >=10 - all events received
710 root 1.1
711     AUTHOR
712 root 1.13 Marc Lehmann <pcg@goof.com>
713     http://software.schmorp.de/pkg/rxvt-unicode
714 root 1.1