rxvt-unicode/doc/rxvtperl.3.txt

NAME
    rxvtperl - rxvt-unicode's embedded perl interpreter

SYNOPSIS
       # create a file grab_test in $HOME:

       sub on_sel_grab {
          warn "you selected ", $_[0]->selection;
          ()
       }

       # start a rxvt using it:

       rxvt --perl-lib $HOME -pe grab_test

DESCRIPTION
    Everytime a terminal object gets created, scripts specified via the
    "perl" resource are loaded and associated with it.

    Scripts are compiled in a 'use strict' and 'use utf8' environment, and
    thus must be encoded as UTF-8.

    Each script will only ever be loaded once, even in rxvtd, where scripts
    will be shared (but not enabled) for all terminals.

  Prepackaged Extensions
    This section describes the extensiosn delivered with this version. You
    can find them in /opt/rxvt/lib/urxvt/perl/.

    You can activate them like this:

      rxvt -pe <extensionname>

    selection
        Miscellaneous selection modifications.

        rot13
            Rot-13 the selection when activated. Used via keyboard trigger:

               URxvt.keysym.C-M-r: perl:selection:rot13

    digital-clock
        Displays a digital clock using the built-in overlay.

    example-refresh-hooks
        Displays a very simple digital clock in the upper right corner of
        the window. Illustrates overwriting the refresh callbacks to create
        your own overlays or changes.

  General API Considerations
    All objects (such as terminals, time watchers etc.) are typical
    reference-to-hash objects. The hash can be used to store anything you
    like. All members starting with an underscore (such as "_ptr" or
    "_hook") are reserved for internal uses and must not be accessed or
    modified).

    When objects are destroyed on the C++ side, the perl object hashes are
    emptied, so its best to store related objects such as time watchers and
    the like inside the terminal object so they get destroyed as soon as the
    terminal is destroyed.

  Hooks
    The following subroutines can be declared in loaded scripts, and will be
    called whenever the relevant event happens.

    All of them must return a boolean value. If it is true, then the event
    counts as being *consumed*, and the invocation of other hooks is
    skipped, and the relevant action might not be carried out by the C++
    code.

    When in doubt, return a false value (preferably "()").

    on_init $term
        Called after a new terminal object has been initialized, but before
        windows are created or the command gets run.

    on_reset $term
        Called after the screen is "reset" for any reason, such as resizing
        or control sequences. Here is where you can react on changes to
        size-related variables.

    on_start $term
        Called at the very end of initialisation of a new terminal, just
        before returning to the mainloop.

    on_sel_make $term, $eventtime
        Called whenever a selection has been made by the user, but before
        the selection text is copied, so changes to the beginning, end or
        type of the selection will be honored.

        Returning a true value aborts selection making by urxvt, in which
        case you have to make a selection yourself by calling
        "$term->selection_grab".

    on_sel_grab $term, $eventtime
        Called whenever a selection has been copied, but before the
        selection is requested from the server. The selection text can be
        queried and changed by calling "$term->selection".

        Returning a true value aborts selection grabbing. It will still be
        hilighted.

    on_focus_in $term
        Called whenever the window gets the keyboard focus, before urxvt
        does focus in processing.

    on_focus_out $term
        Called wheneever the window loses keyboard focus, before urxvt does
        focus out processing.

    on_view_change $term, $offset
        Called whenever the view offset changes, i..e the user or program
        scrolls. Offset 0 means display the normal terminal, positive values
        show this many lines of scrollback.

    on_scroll_back $term, $lines, $saved
        Called whenever lines scroll out of the terminal area into the
        scrollback buffer. $lines is the number of lines scrolled out and
        may be larger than the scroll back buffer or the terminal.

        It is called before lines are scrolled out (so rows 0 .. min ($lines
        - 1, $nrow - 1) represent the lines to be scrolled out). $saved is
        the total number of lines that will be in the scrollback buffer.

    on_tty_activity $term *NYI*
        Called whenever the program(s) running in the urxvt window send
        output.

    on_refresh_begin $term
        Called just before the screen gets redrawn. Can be used for overlay
        or similar effects by modify terminal contents in refresh_begin, and
        restoring them in refresh_end. The built-in overlay and selection
        display code is run after this hook, and takes precedence.

    on_refresh_end $term
        Called just after the screen gets redrawn. See "on_refresh_begin".

    on_keyboard_command $term, $string
        Called whenever the user presses a key combination that has a
        "perl:string" action bound to it (see description of the keysym
        resource in the rxvt(1) manpage).

  Functions in the "urxvt" Package
    urxvt::fatal $errormessage
        Fatally aborts execution with the given error message. Avoid at all
        costs! The only time this is acceptable is when the terminal process
        starts up.

    urxvt::warn $string
        Calls "rxvt_warn" with the given string which should not include a
        newline. The module also overwrites the "warn" builtin with a
        function that calls this function.

        Using this function has the advantage that its output ends up in the
        correct place, e.g. on stderr of the connecting urxvtc client.

    $time = urxvt::NOW
        Returns the "current time" (as per the event loop).

  RENDITION
    Rendition bitsets contain information about colour, font, font styles
    and similar information for each screen cell.

    The following "macros" deal with changes in rendition sets. You should
    never just create a bitset, you should always modify an existing one, as
    they contain important information required for correct operation of
    rxvt-unicode.

    $rend = urxvt::DEFAULT_RSTYLE
        Returns the default rendition, as used when the terminal is starting
        up or being reset. Useful as a base to start when creating
        renditions.

    $rend = urxvt::OVERLAY_RSTYLE
        Return the rendition mask used for overlays by default.

    $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
        Return the bit that enabled bold, italic, blink, reverse-video and
        underline, respectively. To enable such a style, just logically OR
        it into the bitset.

    $foreground = urxvt::GET_BASEFG $rend
    $background = urxvt::GET_BASEBG $rend
        Return the foreground/background colour index, respectively.

    $rend = urxvt::SET_FGCOLOR ($rend, $new_colour)
    $rend = urxvt::SET_BGCOLOR ($rend, $new_colour)
        Replace the foreground/background colour in the rendition mask with
        the specified one.

    $value = urxvt::GET_CUSTOM ($rend)
        Return the "custom" value: Every rendition has 5 bits for use by
        extensions. They can be set and changed as you like and are
        initially zero.

    $rend = urxvt::SET_CUSTOM ($rend, $new_value)
        Change the custom value.

  The "urxvt::term" Class
    $value = $term->resource ($name[, $newval])
        Returns the current resource value associated with a given name and
        optionally sets a new value. Setting values is most useful in the
        "init" hook. Unset resources are returned and accepted as "undef".

        The new value must be properly encoded to a suitable character
        encoding before passing it to this method. Similarly, the returned
        value may need to be converted from the used encoding to text.

        Resource names are as defined in src/rsinc.h. Colours can be
        specified as resource names of the form "color+<index>", e.g.
        "color+5". (will likely change).

        Please note that resource strings will currently only be freed when
        the terminal is destroyed, so changing options frequently will eat
        memory.

        Here is a a likely non-exhaustive list of resource names, not all of
        which are supported in every build, please see the source to see the
        actual list:

          answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
          borderLess color cursorBlink cursorUnderline cutchars delete_key
          display_name embed ext_bwidth fade font geometry hold iconName
          imFont imLocale inputMethod insecure int_bwidth intensityStyles
          italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
          mouseWheelScrollPage name pastableTabs path perl_eval perl_ext
          perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
          reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
          scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
          scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
          shade term_name title transparent transparent_all tripleclickwords
          utmpInhibit visualBell

    ($row, $col) = $term->selection_mark ([$row, $col])
    ($row, $col) = $term->selection_beg ([$row, $col])
    ($row, $col) = $term->selection_end ([$row, $col])
        Return the current values of the selection mark, begin or end
        positions, and optionally set them to new values.

    $success = $term->selection_grab ($eventtime)
        Try to request the primary selection from the server (for example,
        as set by the next method).

    $oldtext = $term->selection ([$newtext])
        Return the current selection text and optionally replace it by
        $newtext.

        #=item $term->overlay ($x, $y, $text) # #Create a simple multi-line
        overlay box. See the next method for details. # #=cut

        sub urxvt::term::scr_overlay { die; my ($self, $x, $y, $text) = @_;

           my @lines = split /\n/, $text;

           my $w = 0;
           for (map $self->strwidth ($_), @lines) {
              $w = $_ if $w < $_;
           }

           $self->scr_overlay_new ($x, $y, $w, scalar @lines);
           $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
        }

    $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
        Create a new (empty) overlay at the given position with the given
        width/height. $rstyle defines the initial rendition style (default:
        "OVERLAY_RSTYLE").

        If $border is 2 (default), then a decorative border will be put
        around the box.

        If either $x or $y is negative, then this is counted from the
        right/bottom side, respectively.

        This method returns an urxvt::overlay object. The overlay will be
        visible as long as the perl object is referenced.

        Currently, the only method on the "urxvt::overlay" object is "set":

    $overlay->set ($x, $y, $text, $rend)
        Similar to "$term->ROW_t" and "$term->ROW_r" in that it puts text in
        rxvt-unicode's special encoding and an array of rendition values at
        a specific position inside the overlay.

    $cellwidth = $term->strwidth $string
        Returns the number of screen-cells this string would need. Correctly
        accounts for wide and combining characters.

    $octets = $term->locale_encode $string
        Convert the given text string into the corresponding locale
        encoding.

    $string = $term->locale_decode $octets
        Convert the given locale-encoded octets into a perl string.

    $term->tt_write ($octets)
        Write the octets given in $data to the tty (i.e. as program input).
        To pass characters instead of octets, you should convert your
        strings first to the locale-specific encoding using
        "$term->locale_encode".

    $nrow = $term->nrow
    $ncol = $term->ncol
        Return the number of rows/columns of the terminal window (i.e. as
        specified by "-geometry", excluding any scrollback).

    $nsaved = $term->nsaved
        Returns the number of lines in the scrollback buffer.

    $view_start = $term->view_start ([$newvalue])
        Returns the negative row number of the topmost line. Minimum value
        is 0, which displays the normal terminal contents. Larger values
        scroll this many lines into the scrollback buffer.

    $term->want_refresh
        Requests a screen refresh. At the next opportunity, rxvt-unicode
        will compare the on-screen display with its stored representation.
        If they differ, it redraws the differences.

        Used after changing terminal contents to display them.

    $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
        Returns the text of the entire row with number $row_number. Row 0 is
        the topmost terminal line, row "$term->$ncol-1" is the bottommost
        terminal line. The scrollback buffer starts at line -1 and extends
        to line "-$term->nsaved".

        If $new_text is specified, it will replace characters in the current
        line, starting at column $start_col (default 0), which is useful to
        replace only parts of a line. The font index in the rendition will
        automatically be updated.

        $text is in a special encoding: tabs and wide characters that use
        more than one cell when displayed are padded with urxvt::NOCHAR
        characters ("chr 65535"). Characters with combining characters and
        other characters that do not fit into the normal tetx encoding will
        be replaced with characters in the private use area.

        You have to obey this encoding when changing text. The advantage is
        that "substr" and similar functions work on screen cells and not on
        characters.

        The methods "$term->special_encode" and "$term->special_decode" can
        be used to convert normal strings into this encoding and vice versa.

    $rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])
        Like "$term->ROW_t", but returns an arrayref with rendition bitsets.
        Rendition bitsets contain information about colour, font, font
        styles and similar information. See also "$term->ROW_t".

        When setting rendition, the font mask will be ignored.

        See the section on RENDITION, above.

    $length = $term->ROW_l ($row_number[, $new_length])
        Returns the number of screen cells that are in use ("the line
        length"). If it is -1, then the line is part of a multiple-row
        logical "line", which means all characters are in use and it is
        continued on the next row.

    $text = $term->special_encode $string
        Converts a perl string into the special encoding used by
        rxvt-unicode, where one character corresponds to one screen cell.
        See "$term->ROW_t" for details.

    $string = $term->special_decode $text
        Converts rxvt-unicodes text reprsentation into a perl string. See
        "$term->ROW_t" for details.

  The "urxvt::timer" Class
    This class implements timer watchers/events. Time is represented as a
    fractional number of seconds since the epoch. Example:

       $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
       $term->{timer} = urxvt::timer
                        ->new
                        ->interval (1)
                        ->cb (sub {
                           $term->{overlay}->set (0, 0,
                              sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
                        });                                                                                                                                      

    $timer = new urxvt::timer
        Create a new timer object in started state. It is scheduled to fire
        immediately.

    $timer = $timer->cb (sub { my ($timer) = @_; ... })
        Set the callback to be called when the timer triggers.

    $tstamp = $timer->at
        Return the time this watcher will fire next.

    $timer = $timer->set ($tstamp)
        Set the time the event is generated to $tstamp.

    $timer = $timer->interval ($interval)
        Normally (and when $interval is 0), the timer will automatically
        stop after it has fired once. If $interval is non-zero, then the
        timer is automatically rescheduled at the given intervals.

    $timer = $timer->start
        Start the timer.

    $timer = $timer->start ($tstamp)
        Set the event trigger time to $tstamp and start the timer.

    $timer = $timer->stop
        Stop the timer.

  The "urxvt::iow" Class
    This class implements io watchers/events. Example:

      $term->{socket} = ...
      $term->{iow} = urxvt::iow
                     ->new
                     ->fd (fileno $term->{socket})
                     ->events (1) # wait for read data
                     ->start
                     ->cb (sub {
                       my ($iow, $revents) = @_;
                       # $revents must be 1 here, no need to check
                       sysread $term->{socket}, my $buf, 8192
                          or end-of-file;
                     });

    $iow = new urxvt::iow
        Create a new io watcher object in stopped state.

    $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
        Set the callback to be called when io events are triggered.
        $reventmask is a bitset as described in the "events" method.

    $iow = $iow->fd ($fd)
        Set the filedescriptor (not handle) to watch.

    $iow = $iow->events ($eventmask)
        Set the event mask to watch. Bit #0 (value 1) enables watching for
        read data, Bit #1 (value 2) enables watching for write data.

    $iow = $iow->start
        Start watching for requested events on the given handle.

    $iow = $iow->stop
        Stop watching for events on the given filehandle.

ENVIRONMENT
  URXVT_PERL_VERBOSITY
    This variable controls the verbosity level of the perl extension. Higher
    numbers indicate more verbose output.

    0 - only fatal messages
    3 - script loading and management
    10 - all events received

AUTHOR
     Marc Lehmann <pcg@goof.com>
     http://software.schmorp.de/pkg/rxvt-unicode

Revision:	1.6
Committed:	Tue Jan 3 04:20:37 2006 UTC (18 years, 6 months ago) by root
Content type:	text/plain
Branch:	MAIN
Changes since 1.5:	+89 -44 lines
Log Message:	* empty log message *
#	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.2	Everytime a terminal object gets created, scripts specified via the
18	root	1.3	"perl" resource are loaded and associated with it.
19
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			selection
35			Miscellaneous selection modifications.
36
37			rot13
38			Rot-13 the selection when activated. Used via keyboard trigger:
39
40			URxvt.keysym.C-M-r: perl:selection:rot13
41
42			digital-clock
43	root	1.6	Displays a digital clock using the built-in overlay.
44
45			example-refresh-hooks
46	root	1.4	Displays a very simple digital clock in the upper right corner of
47			the window. Illustrates overwriting the refresh callbacks to create
48			your own overlays or changes.
49
50	root	1.1	General API Considerations
51			All objects (such as terminals, time watchers etc.) are typical
52			reference-to-hash objects. The hash can be used to store anything you
53			like. All members starting with an underscore (such as "_ptr" or
54			"_hook") are reserved for internal uses and must not be accessed or
55			modified).
56
57			When objects are destroyed on the C++ side, the perl object hashes are
58			emptied, so its best to store related objects such as time watchers and
59			the like inside the terminal object so they get destroyed as soon as the
60			terminal is destroyed.
61
62			Hooks
63			The following subroutines can be declared in loaded scripts, and will be
64			called whenever the relevant event happens.
65
66			All of them must return a boolean value. If it is true, then the event
67			counts as being consumed, and the invocation of other hooks is
68			skipped, and the relevant action might not be carried out by the C++
69			code.
70
71			When in doubt, return a false value (preferably "()").
72
73			on_init $term
74			Called after a new terminal object has been initialized, but before
75			windows are created or the command gets run.
76
77			on_reset $term
78			Called after the screen is "reset" for any reason, such as resizing
79			or control sequences. Here is where you can react on changes to
80			size-related variables.
81
82			on_start $term
83			Called at the very end of initialisation of a new terminal, just
84			before returning to the mainloop.
85
86			on_sel_make $term, $eventtime
87			Called whenever a selection has been made by the user, but before
88			the selection text is copied, so changes to the beginning, end or
89			type of the selection will be honored.
90
91			Returning a true value aborts selection making by urxvt, in which
92			case you have to make a selection yourself by calling
93			"$term->selection_grab".
94
95			on_sel_grab $term, $eventtime
96			Called whenever a selection has been copied, but before the
97			selection is requested from the server. The selection text can be
98			queried and changed by calling "$term->selection".
99
100			Returning a true value aborts selection grabbing. It will still be
101			hilighted.
102
103			on_focus_in $term
104			Called whenever the window gets the keyboard focus, before urxvt
105			does focus in processing.
106
107			on_focus_out $term
108			Called wheneever the window loses keyboard focus, before urxvt does
109			focus out processing.
110
111			on_view_change $term, $offset
112			Called whenever the view offset changes, i..e the user or program
113			scrolls. Offset 0 means display the normal terminal, positive values
114			show this many lines of scrollback.
115
116			on_scroll_back $term, $lines, $saved
117			Called whenever lines scroll out of the terminal area into the
118			scrollback buffer. $lines is the number of lines scrolled out and
119			may be larger than the scroll back buffer or the terminal.
120
121			It is called before lines are scrolled out (so rows 0 .. min ($lines
122			- 1, $nrow - 1) represent the lines to be scrolled out). $saved is
123			the total number of lines that will be in the scrollback buffer.
124
125			on_tty_activity $term NYI
126			Called whenever the program(s) running in the urxvt window send
127			output.
128
129			on_refresh_begin $term
130			Called just before the screen gets redrawn. Can be used for overlay
131			or similar effects by modify terminal contents in refresh_begin, and
132			restoring them in refresh_end. The built-in overlay and selection
133			display code is run after this hook, and takes precedence.
134
135			on_refresh_end $term
136			Called just after the screen gets redrawn. See "on_refresh_begin".
137
138	root	1.3	on_keyboard_command $term, $string
139			Called whenever the user presses a key combination that has a
140			"perl:string" action bound to it (see description of the keysym
141			resource in the rxvt(1) manpage).
142
143	root	1.1	Functions in the "urxvt" Package
144			urxvt::fatal $errormessage
145			Fatally aborts execution with the given error message. Avoid at all
146			costs! The only time this is acceptable is when the terminal process
147			starts up.
148
149			urxvt::warn $string
150			Calls "rxvt_warn" with the given string which should not include a
151			newline. The module also overwrites the "warn" builtin with a
152			function that calls this function.
153
154			Using this function has the advantage that its output ends up in the
155			correct place, e.g. on stderr of the connecting urxvtc client.
156
157			$time = urxvt::NOW
158			Returns the "current time" (as per the event loop).
159
160	root	1.6	RENDITION
161			Rendition bitsets contain information about colour, font, font styles
162			and similar information for each screen cell.
163
164			The following "macros" deal with changes in rendition sets. You should
165			never just create a bitset, you should always modify an existing one, as
166			they contain important information required for correct operation of
167			rxvt-unicode.
168
169			$rend = urxvt::DEFAULT_RSTYLE
170			Returns the default rendition, as used when the terminal is starting
171			up or being reset. Useful as a base to start when creating
172			renditions.
173
174			$rend = urxvt::OVERLAY_RSTYLE
175			Return the rendition mask used for overlays by default.
176
177			$rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
178			Return the bit that enabled bold, italic, blink, reverse-video and
179			underline, respectively. To enable such a style, just logically OR
180			it into the bitset.
181
182			$foreground = urxvt::GET_BASEFG $rend
183			$background = urxvt::GET_BASEBG $rend
184			Return the foreground/background colour index, respectively.
185
186			$rend = urxvt::SET_FGCOLOR ($rend, $new_colour)
187			$rend = urxvt::SET_BGCOLOR ($rend, $new_colour)
188			Replace the foreground/background colour in the rendition mask with
189			the specified one.
190
191			$value = urxvt::GET_CUSTOM ($rend)
192			Return the "custom" value: Every rendition has 5 bits for use by
193			extensions. They can be set and changed as you like and are
194			initially zero.
195
196			$rend = urxvt::SET_CUSTOM ($rend, $new_value)
197			Change the custom value.
198
199	root	1.1	The "urxvt::term" Class
200			$value = $term->resource ($name[, $newval])
201			Returns the current resource value associated with a given name and
202			optionally sets a new value. Setting values is most useful in the
203			"init" hook. Unset resources are returned and accepted as "undef".
204
205			The new value must be properly encoded to a suitable character
206			encoding before passing it to this method. Similarly, the returned
207			value may need to be converted from the used encoding to text.
208
209			Resource names are as defined in src/rsinc.h. Colours can be
210			specified as resource names of the form "color+<index>", e.g.
211			"color+5". (will likely change).
212
213			Please note that resource strings will currently only be freed when
214			the terminal is destroyed, so changing options frequently will eat
215			memory.
216
217			Here is a a likely non-exhaustive list of resource names, not all of
218			which are supported in every build, please see the source to see the
219			actual list:
220
221			answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
222			borderLess color cursorBlink cursorUnderline cutchars delete_key
223			display_name embed ext_bwidth fade font geometry hold iconName
224			imFont imLocale inputMethod insecure int_bwidth intensityStyles
225	root	1.2	italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
226			mouseWheelScrollPage name pastableTabs path perl_eval perl_ext
227	root	1.1	perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
228			reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
229			scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
230			scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
231			shade term_name title transparent transparent_all tripleclickwords
232			utmpInhibit visualBell
233
234			($row, $col) = $term->selection_mark ([$row, $col])
235			($row, $col) = $term->selection_beg ([$row, $col])
236			($row, $col) = $term->selection_end ([$row, $col])
237			Return the current values of the selection mark, begin or end
238			positions, and optionally set them to new values.
239
240			$success = $term->selection_grab ($eventtime)
241			Try to request the primary selection from the server (for example,
242			as set by the next method).
243
244			$oldtext = $term->selection ([$newtext])
245			Return the current selection text and optionally replace it by
246			$newtext.
247
248	root	1.6	#=item $term->overlay ($x, $y, $text) # #Create a simple multi-line
249			overlay box. See the next method for details. # #=cut
250
251			sub urxvt::term::scr_overlay { die; my ($self, $x, $y, $text) = @_;
252
253			my @lines = split /\n/, $text;
254	root	1.1
255	root	1.6	my $w = 0;
256			for (map $self->strwidth ($_), @lines) {
257			$w = $_ if $w < $_;
258			}
259
260			$self->scr_overlay_new ($x, $y, $w, scalar @lines);
261			$self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
262			}
263
264			$term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
265	root	1.1	Create a new (empty) overlay at the given position with the given
266	root	1.6	width/height. $rstyle defines the initial rendition style (default:
267			"OVERLAY_RSTYLE").
268
269			If $border is 2 (default), then a decorative border will be put
270			around the box.
271
272			If either $x or $y is negative, then this is counted from the
273			right/bottom side, respectively.
274
275			This method returns an urxvt::overlay object. The overlay will be
276			visible as long as the perl object is referenced.
277	root	1.1
278	root	1.6	Currently, the only method on the "urxvt::overlay" object is "set":
279
280			$overlay->set ($x, $y, $text, $rend)
281			Similar to "$term->ROW_t" and "$term->ROW_r" in that it puts text in
282			rxvt-unicode's special encoding and an array of rendition values at
283			a specific position inside the overlay.
284	root	1.1
285			$cellwidth = $term->strwidth $string
286			Returns the number of screen-cells this string would need. Correctly
287			accounts for wide and combining characters.
288
289			$octets = $term->locale_encode $string
290			Convert the given text string into the corresponding locale
291			encoding.
292
293			$string = $term->locale_decode $octets
294			Convert the given locale-encoded octets into a perl string.
295
296			$term->tt_write ($octets)
297			Write the octets given in $data to the tty (i.e. as program input).
298	root	1.4	To pass characters instead of octets, you should convert your
299			strings first to the locale-specific encoding using
300			"$term->locale_encode".
301
302			$nrow = $term->nrow
303			$ncol = $term->ncol
304			Return the number of rows/columns of the terminal window (i.e. as
305			specified by "-geometry", excluding any scrollback).
306
307			$nsaved = $term->nsaved
308			Returns the number of lines in the scrollback buffer.
309
310			$view_start = $term->view_start ([$newvalue])
311			Returns the negative row number of the topmost line. Minimum value
312			is 0, which displays the normal terminal contents. Larger values
313			scroll this many lines into the scrollback buffer.
314
315			$term->want_refresh
316			Requests a screen refresh. At the next opportunity, rxvt-unicode
317			will compare the on-screen display with its stored representation.
318			If they differ, it redraws the differences.
319
320			Used after changing terminal contents to display them.
321
322			$text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
323			Returns the text of the entire row with number $row_number. Row 0 is
324			the topmost terminal line, row "$term->$ncol-1" is the bottommost
325			terminal line. The scrollback buffer starts at line -1 and extends
326			to line "-$term->nsaved".
327
328			If $new_text is specified, it will replace characters in the current
329			line, starting at column $start_col (default 0), which is useful to
330	root	1.6	replace only parts of a line. The font index in the rendition will
331	root	1.4	automatically be updated.
332
333			$text is in a special encoding: tabs and wide characters that use
334			more than one cell when displayed are padded with urxvt::NOCHAR
335			characters ("chr 65535"). Characters with combining characters and
336			other characters that do not fit into the normal tetx encoding will
337			be replaced with characters in the private use area.
338
339			You have to obey this encoding when changing text. The advantage is
340			that "substr" and similar functions work on screen cells and not on
341			characters.
342
343			The methods "$term->special_encode" and "$term->special_decode" can
344			be used to convert normal strings into this encoding and vice versa.
345
346			$rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])
347			Like "$term->ROW_t", but returns an arrayref with rendition bitsets.
348			Rendition bitsets contain information about colour, font, font
349			styles and similar information. See also "$term->ROW_t".
350
351			When setting rendition, the font mask will be ignored.
352
353	root	1.6	See the section on RENDITION, above.
354	root	1.4
355			$length = $term->ROW_l ($row_number[, $new_length])
356			Returns the number of screen cells that are in use ("the line
357			length"). If it is -1, then the line is part of a multiple-row
358			logical "line", which means all characters are in use and it is
359			continued on the next row.
360
361			$text = $term->special_encode $string
362			Converts a perl string into the special encoding used by
363			rxvt-unicode, where one character corresponds to one screen cell.
364			See "$term->ROW_t" for details.
365
366			$string = $term->special_decode $text
367			Converts rxvt-unicodes text reprsentation into a perl string. See
368			"$term->ROW_t" for details.
369
370	root	1.1	The "urxvt::timer" Class
371			This class implements timer watchers/events. Time is represented as a
372			fractional number of seconds since the epoch. Example:
373
374	root	1.6	$term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
375	root	1.1	$term->{timer} = urxvt::timer
376			->new
377	root	1.6	->interval (1)
378	root	1.1	->cb (sub {
379	root	1.6	$term->{overlay}->set (0, 0,
380			sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
381			});
382	root	1.1
383			$timer = new urxvt::timer
384	root	1.6	Create a new timer object in started state. It is scheduled to fire
385			immediately.
386	root	1.1
387			$timer = $timer->cb (sub { my ($timer) = @_; ... })
388			Set the callback to be called when the timer triggers.
389
390			$tstamp = $timer->at
391			Return the time this watcher will fire next.
392
393			$timer = $timer->set ($tstamp)
394			Set the time the event is generated to $tstamp.
395
396	root	1.6	$timer = $timer->interval ($interval)
397			Normally (and when $interval is 0), the timer will automatically
398			stop after it has fired once. If $interval is non-zero, then the
399			timer is automatically rescheduled at the given intervals.
400
401	root	1.1	$timer = $timer->start
402			Start the timer.
403
404			$timer = $timer->start ($tstamp)
405			Set the event trigger time to $tstamp and start the timer.
406
407			$timer = $timer->stop
408			Stop the timer.
409
410			The "urxvt::iow" Class
411			This class implements io watchers/events. Example:
412
413			$term->{socket} = ...
414			$term->{iow} = urxvt::iow
415			->new
416			->fd (fileno $term->{socket})
417			->events (1) # wait for read data
418			->start
419			->cb (sub {
420			my ($iow, $revents) = @_;
421			# $revents must be 1 here, no need to check
422			sysread $term->{socket}, my $buf, 8192
423			or end-of-file;
424			});
425
426			$iow = new urxvt::iow
427			Create a new io watcher object in stopped state.
428
429			$iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
430			Set the callback to be called when io events are triggered.
431			$reventmask is a bitset as described in the "events" method.
432
433			$iow = $iow->fd ($fd)
434			Set the filedescriptor (not handle) to watch.
435
436			$iow = $iow->events ($eventmask)
437			Set the event mask to watch. Bit #0 (value 1) enables watching for
438			read data, Bit #1 (value 2) enables watching for write data.
439
440			$iow = $iow->start
441			Start watching for requested events on the given handle.
442
443			$iow = $iow->stop
444			Stop watching for events on the given filehandle.
445
446			ENVIRONMENT
447			URXVT_PERL_VERBOSITY
448			This variable controls the verbosity level of the perl extension. Higher
449			numbers indicate more verbose output.
450
451			0 - only fatal messages
452			3 - script loading and management
453			10 - all events received
454
455			AUTHOR
456			Marc Lehmann <pcg@goof.com>
457			http://software.schmorp.de/pkg/rxvt-unicode
458