rxvt-unicode/src/urxvt.pm

=head1 NAME

rxvtperl - rxvt-unicode's embedded perl interpreter

=head1 SYNOPSIS

* Put your scripts into F<@@RXVT_LIBDIR@@/urxvt/perl/>, they will be loaded automatically.

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

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

   1

=head1 DESCRIPTION

Everytime a terminal object gets created, scripts specified via the
C<perl> resource are associated with it.

Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where
scripts will be shared (But not enabled) for all terminals.

=head2 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 C<_ptr> or
C<_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.

=head2 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 I<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 C<()>).

=over 4

=item on_init $term

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

=item 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.

=item on_start $term

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

=item 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 C<< $term->selection_grab >>.

=item 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 C<< $term->selection >>.

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

=item on_focus_in $term

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

=item on_focus_out $term

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

=item on_view_change $term, $offset

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

=item on_scroll_back $term, $lines, $saved

Called whenever lines scroll out of the terminal area into the scrollback
buffer. C<$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). C<$saved> is the total
number of lines that will be in the scrollback buffer.

=item on_tty_activity $term *NYI*

Called whenever the program(s) running in the urxvt window send output.

=item 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.

=item on_refresh_end $term

Called just after the screen gets redrawn. See C<on_refresh_begin>.

=back

=head2 Functions in the C<urxvt> Package

=over 4

=item 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.

=item urxvt::warn $string

Calls C<rxvt_warn> with the given string which should not include a
newline. The module also overwrites the C<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.

=item $time = urxvt::NOW

Returns the "current time" (as per the event loop).

=cut

package urxvt;

use strict;

our $term;
our @HOOKNAME;
our $LIBDIR;

BEGIN {
   urxvt->bootstrap;

   # overwrite perl's warn
   *CORE::GLOBAL::warn = sub {
      my $msg = join "", @_;
      $msg .= "\n"
         unless $msg =~ /\n$/;
      urxvt::warn ($msg);
   };
}

my @hook_count;
my $verbosity = $ENV{URXVT_PERL_VERBOSITY};

sub verbose {
   my ($level, $msg) = @_;
   warn "$msg\n" if $level <= $verbosity;
}

# find on_xxx subs in the package and register them
# as hooks
sub register_package($) {
   my ($pkg) = @_;

   for my $htype (0.. $#HOOKNAME) {
      my $name = $HOOKNAME[$htype];

      my $ref = $pkg->can ("on_" . lc $name)
         or next;

      $term->{_hook}[$htype]{$ref*1} = $ref;
      $hook_count[$htype]++
         or set_should_invoke $htype, 1;
   }
}

my $script_pkg = "script0000";
my %script_pkg;

# load a single script into its own package, once only
sub script_package($) {
   my ($path) = @_;

   $script_pkg{$path} ||= do {
      my $pkg = "urxvt::" . ($script_pkg++);

      verbose 3, "loading script '$path' into package '$pkg'";

      open my $fh, "<:raw", $path
         or die "$path: $!";

      my $source = "package $pkg; use strict; use utf8;\n"
                   . "#line 1 \"$path\"\n{\n"
                   . (do { local $/; <$fh> })
                   . "\n};\n1";

      eval $source or die "$path: $@";

      $pkg
   }
}

# called by the rxvt core
sub invoke {
   local $term = shift;
   my $htype = shift;

   if ($htype == 0) { # INIT
      my @dirs = ((split /:/, $term->resource ("perl_lib")), "$LIBDIR/perl");

      for my $ext (split /:/, $term->resource ("perl_ext")) {
         my @files = grep -f $_, map "$_/$ext", @dirs;

         if (@files) {
            register_package script_package $files[0];
         } else {
            warn "perl extension '$ext' not found in perl library search path\n";
         }
      }

   } elsif ($htype == 1) { # DESTROY
      if (my $hook = $term->{_hook}) {
         for my $htype (0..$#$hook) {
            $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
               or set_should_invoke $htype, 0;
         }
      }
   }

   my $cb = $term->{_hook}[$htype]
      or return;

   verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $term, @_) . ")"
      if $verbosity >= 10;

   while (my ($k, $v) = each %$cb) {
      return 1 if $v->($term, @_);
   }

   0
}

=back

=head2 The C<urxvt::term> Class

=over 4

=item $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 C<init>
hook. Unset resources are returned and accepted as C<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 F<src/rsinc.h>. Colours can be specified
as resource names of the form C<< color+<index> >>, e.g. C<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

=cut

sub urxvt::term::resource($$;$) {
   my ($self, $name) = (shift, shift);
   unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
   goto &urxvt::term::_resource;
}

=item ($row, $col) = $term->selection_mark ([$row, $col])

=item ($row, $col) = $term->selection_beg ([$row, $col])

=item ($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.

=item $success = $term->selection_grab ($eventtime)

Try to request the primary selection from the server (for example, as set
by the next method).

=item $oldtext = $term->selection ([$newtext])

Return the current selection text and optionally replace it by C<$newtext>.

=item $term->scr_overlay ($x, $y, $text)

Create a simple multi-line overlay box. See the next method for details.

=cut

sub urxvt::term::scr_overlay {
   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;
}

=item $term->scr_overlay_new ($x, $y, $width, $height)

Create a new (empty) overlay at the given position with the given
width/height. A border will be put around the box. If either C<$x> or
C<$y> is negative, then this is counted from the right/bottom side,
respectively.

=item $term->scr_overlay_off

Switch the overlay off again.

=item $term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE)

Put a single character (specified numerically) at the given overlay
position.

=item $term->scr_overlay_set ($x, $y, $text)

Write a string at the given position into the overlay.

=item $cellwidth = $term->strwidth $string

Returns the number of screen-cells this string would need. Correctly
accounts for wide and combining characters.

=item $octets = $term->locale_encode $string

Convert the given text string into the corresponding locale encoding.

=item $string = $term->locale_decode $octets

Convert the given locale-encoded octets into a perl string.

=item $term->tt_write ($octets)

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

=back

=head2 The C<urxvt::timer> Class

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

   # create a digital clock display in upper right corner
   $term->{timer} = urxvt::timer
                    ->new
                    ->start (urxvt::NOW)
                    ->cb (sub {
                       my ($timer) = @_;
                       my $time = $timer->at;
                       $timer->start ($time + 1);
                       $self->scr_overlay (-1, 0, 
                          POSIX::strftime "%H:%M:%S", localtime $time);
                    });

=over 4

=item $timer = new urxvt::timer

Create a new timer object in stopped state.

=item $timer = $timer->cb (sub { my ($timer) = @_; ... })

Set the callback to be called when the timer triggers.

=item $tstamp = $timer->at

Return the time this watcher will fire next.

=item $timer = $timer->set ($tstamp)

Set the time the event is generated to $tstamp.

=item $timer = $timer->start

Start the timer.

=item $timer = $timer->start ($tstamp)

Set the event trigger time to C<$tstamp> and start the timer.

=item $timer = $timer->stop

Stop the timer.

=back

=head2 The C<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;
                 });


=over 4

=item $iow = new urxvt::iow

Create a new io watcher object in stopped state.

=item $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })

Set the callback to be called when io events are triggered. C<$reventmask>
is a bitset as described in the C<events> method.

=item $iow = $iow->fd ($fd)

Set the filedescriptor (not handle) to watch.

=item $iow = $iow->events ($eventmask)

Set the event mask to watch. Bit #0 (value C<1>) enables watching for read
data, Bit #1 (value C<2>) enables watching for write data.

=item $iow = $iow->start

Start watching for requested events on the given handle.

=item $iow = $iow->stop

Stop watching for events on the given filehandle.

=back

=head1 ENVIRONMENT

=head2 URXVT_PERL_VERBOSITY

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

=over 4

=item 0 - only fatal messages

=item 3 - script loading and management

=item 10 - all events received

=back

=head1 AUTHOR

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

=cut

1
Revision:	1.9
Committed:	Mon Jan 2 20:40:20 2006 UTC (18 years, 4 months ago) by root
Branch:	MAIN
Changes since 1.8:	+2 -2 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	=head1 NAME
2
3	root	1.3	rxvtperl - rxvt-unicode's embedded perl interpreter
4	root	1.1
5			=head1 SYNOPSIS
6
7	root	1.9	* Put your scripts into F<@@RXVT_LIBDIR@@/urxvt/perl/>, they will be loaded automatically.
8	root	1.1
9	root	1.3	* Scripts are evaluated in a 'use strict' and 'use utf8' environment, and
10			thus must be encoded as UTF-8.
11	root	1.1
12			sub on_sel_grab {
13			warn "you selected ", $_[0]->selection;
14	root	1.3	()
15	root	1.1	}
16
17			1
18
19			=head1 DESCRIPTION
20
21	root	1.8	Everytime a terminal object gets created, scripts specified via the
22			C<perl> resource are associated with it.
23	root	1.6
24			Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where
25	root	1.8	scripts will be shared (But not enabled) for all terminals.
26	root	1.6
27			=head2 General API Considerations
28
29			All objects (such as terminals, time watchers etc.) are typical
30			reference-to-hash objects. The hash can be used to store anything you
31	root	1.7	like. All members starting with an underscore (such as C<_ptr> or
32			C<_hook>) are reserved for internal uses and must not be accessed or
33			modified).
34	root	1.6
35			When objects are destroyed on the C++ side, the perl object hashes are
36			emptied, so its best to store related objects such as time watchers and
37			the like inside the terminal object so they get destroyed as soon as the
38			terminal is destroyed.
39
40	root	1.1	=head2 Hooks
41
42			The following subroutines can be declared in loaded scripts, and will be called
43			whenever the relevant event happens.
44
45			All of them must return a boolean value. If it is true, then the event
46			counts as being I<consumed>, and the invocation of other hooks is skipped,
47			and the relevant action might not be carried out by the C++ code.
48
49			When in doubt, return a false value (preferably C<()>).
50
51			=over 4
52
53			=item on_init $term
54
55			Called after a new terminal object has been initialized, but before
56			windows are created or the command gets run.
57
58			=item on_reset $term
59
60			Called after the screen is "reset" for any reason, such as resizing or
61			control sequences. Here is where you can react on changes to size-related
62			variables.
63
64			=item on_start $term
65
66			Called at the very end of initialisation of a new terminal, just before
67			returning to the mainloop.
68
69			=item on_sel_make $term, $eventtime
70
71			Called whenever a selection has been made by the user, but before the
72			selection text is copied, so changes to the beginning, end or type of the
73			selection will be honored.
74
75			Returning a true value aborts selection making by urxvt, in which case you
76			have to make a selection yourself by calling C<< $term->selection_grab >>.
77
78			=item on_sel_grab $term, $eventtime
79
80			Called whenever a selection has been copied, but before the selection is
81			requested from the server. The selection text can be queried and changed
82			by calling C<< $term->selection >>.
83
84			Returning a true value aborts selection grabbing. It will still be hilighted.
85
86			=item on_focus_in $term
87
88			Called whenever the window gets the keyboard focus, before urxvt does
89			focus in processing.
90
91			=item on_focus_out $term
92
93			Called wheneever the window loses keyboard focus, before urxvt does focus
94			out processing.
95
96			=item on_view_change $term, $offset
97
98			Called whenever the view offset changes, i..e the user or program
99			scrolls. Offset C<0> means display the normal terminal, positive values
100			show this many lines of scrollback.
101
102			=item on_scroll_back $term, $lines, $saved
103
104			Called whenever lines scroll out of the terminal area into the scrollback
105			buffer. C<$lines> is the number of lines scrolled out and may be larger
106			than the scroll back buffer or the terminal.
107
108			It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
109			$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
110			number of lines that will be in the scrollback buffer.
111
112			=item on_tty_activity $term NYI
113
114			Called whenever the program(s) running in the urxvt window send output.
115
116			=item on_refresh_begin $term
117
118			Called just before the screen gets redrawn. Can be used for overlay
119			or similar effects by modify terminal contents in refresh_begin, and
120			restoring them in refresh_end. The built-in overlay and selection display
121			code is run after this hook, and takes precedence.
122
123			=item on_refresh_end $term
124
125			Called just after the screen gets redrawn. See C<on_refresh_begin>.
126
127			=back
128
129			=head2 Functions in the C<urxvt> Package
130
131			=over 4
132
133			=item urxvt::fatal $errormessage
134
135			Fatally aborts execution with the given error message. Avoid at all
136			costs! The only time this is acceptable is when the terminal process
137			starts up.
138
139			=item urxvt::warn $string
140
141	root	1.6	Calls C<rxvt_warn> with the given string which should not include a
142	root	1.1	newline. The module also overwrites the C<warn> builtin with a function
143			that calls this function.
144
145			Using this function has the advantage that its output ends up in the
146			correct place, e.g. on stderr of the connecting urxvtc client.
147
148			=item $time = urxvt::NOW
149
150			Returns the "current time" (as per the event loop).
151
152			=cut
153
154			package urxvt;
155
156			use strict;
157
158			our $term;
159			our @HOOKNAME;
160			our $LIBDIR;
161
162			BEGIN {
163			urxvt->bootstrap;
164
165			# overwrite perl's warn
166			*CORE::GLOBAL::warn = sub {
167			my $msg = join "", @_;
168			$msg .= "\n"
169			unless $msg =~ /\n$/;
170			urxvt::warn ($msg);
171			};
172			}
173
174	root	1.8	my @hook_count;
175	root	1.7	my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
176	root	1.1
177			sub verbose {
178			my ($level, $msg) = @_;
179	root	1.8	warn "$msg\n" if $level <= $verbosity;
180	root	1.1	}
181
182			# find on_xxx subs in the package and register them
183			# as hooks
184			sub register_package($) {
185			my ($pkg) = @_;
186
187	root	1.7	for my $htype (0.. $#HOOKNAME) {
188			my $name = $HOOKNAME[$htype];
189	root	1.1
190			my $ref = $pkg->can ("on_" . lc $name)
191			or next;
192
193	root	1.7	$term->{_hook}[$htype]{$ref*1} = $ref;
194			$hook_count[$htype]++
195			or set_should_invoke $htype, 1;
196	root	1.1	}
197			}
198
199			my $script_pkg = "script0000";
200			my %script_pkg;
201
202			# load a single script into its own package, once only
203	root	1.7	sub script_package($) {
204	root	1.1	my ($path) = @_;
205
206			$script_pkg{$path} \|\|= do {
207	root	1.8	my $pkg = "urxvt::" . ($script_pkg++);
208
209	root	1.1	verbose 3, "loading script '$path' into package '$pkg'";
210
211			open my $fh, "<:raw", $path
212			or die "$path: $!";
213
214	root	1.8	my $source = "package $pkg; use strict; use utf8;\n"
215			. "#line 1 \"$path\"\n{\n"
216			. (do { local $/; <$fh> })
217			. "\n};\n1";
218
219			eval $source or die "$path: $@";
220	root	1.1
221			$pkg
222	root	1.7	}
223	root	1.1	}
224
225	root	1.8	# called by the rxvt core
226			sub invoke {
227			local $term = shift;
228			my $htype = shift;
229	root	1.6
230	root	1.8	if ($htype == 0) { # INIT
231	root	1.9	my @dirs = ((split /:/, $term->resource ("perl_lib")), "$LIBDIR/perl");
232	root	1.6
233	root	1.8	for my $ext (split /:/, $term->resource ("perl_ext")) {
234			my @files = grep -f $_, map "$_/$ext", @dirs;
235	root	1.6
236	root	1.8	if (@files) {
237			register_package script_package $files[0];
238			} else {
239			warn "perl extension '$ext' not found in perl library search path\n";
240			}
241			}
242	root	1.6
243	root	1.8	} elsif ($htype == 1) { # DESTROY
244			if (my $hook = $term->{_hook}) {
245			for my $htype (0..$#$hook) {
246			$hook_count[$htype] -= scalar keys %{ $hook->[$htype] \|\| {} }
247			or set_should_invoke $htype, 0;
248			}
249			}
250			}
251	root	1.6
252	root	1.8	my $cb = $term->{_hook}[$htype]
253			or return;
254	root	1.6
255	root	1.8	verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $term, @_) . ")"
256			if $verbosity >= 10;
257	root	1.7
258	root	1.8	while (my ($k, $v) = each %$cb) {
259			return 1 if $v->($term, @_);
260	root	1.7	}
261
262	root	1.8	0
263	root	1.7	}
264	root	1.1
265			=back
266
267			=head2 The C<urxvt::term> Class
268
269			=over 4
270
271	root	1.4	=item $value = $term->resource ($name[, $newval])
272
273			Returns the current resource value associated with a given name and
274			optionally sets a new value. Setting values is most useful in the C<init>
275			hook. Unset resources are returned and accepted as C<undef>.
276
277			The new value must be properly encoded to a suitable character encoding
278			before passing it to this method. Similarly, the returned value may need
279			to be converted from the used encoding to text.
280
281			Resource names are as defined in F<src/rsinc.h>. Colours can be specified
282			as resource names of the form C<< color+<index> >>, e.g. C<color+5>. (will
283			likely change).
284
285			Please note that resource strings will currently only be freed when the
286			terminal is destroyed, so changing options frequently will eat memory.
287
288	root	1.5	Here is a a likely non-exhaustive list of resource names, not all of which
289			are supported in every build, please see the source to see the actual
290			list:
291
292			answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
293			borderLess color cursorBlink cursorUnderline cutchars delete_key
294			display_name embed ext_bwidth fade font geometry hold iconName
295			imFont imLocale inputMethod insecure int_bwidth intensityStyles
296	root	1.8	italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
297			mouseWheelScrollPage name pastableTabs path perl_eval perl_ext
298	root	1.6	perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
299			reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
300			scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
301			scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
302			shade term_name title transparent transparent_all tripleclickwords
303			utmpInhibit visualBell
304	root	1.5
305	root	1.4	=cut
306
307			sub urxvt::term::resource($$;$) {
308			my ($self, $name) = (shift, shift);
309			unshift @_, $self, $name, ($name =~ s/\s\+\s(\d+)$// ? $1 : 0);
310			goto &urxvt::term::_resource;
311			}
312
313	root	1.1	=item ($row, $col) = $term->selection_mark ([$row, $col])
314
315			=item ($row, $col) = $term->selection_beg ([$row, $col])
316
317			=item ($row, $col) = $term->selection_end ([$row, $col])
318
319			Return the current values of the selection mark, begin or end positions,
320			and optionally set them to new values.
321
322			=item $success = $term->selection_grab ($eventtime)
323
324			Try to request the primary selection from the server (for example, as set
325			by the next method).
326
327			=item $oldtext = $term->selection ([$newtext])
328
329			Return the current selection text and optionally replace it by C<$newtext>.
330
331			=item $term->scr_overlay ($x, $y, $text)
332
333			Create a simple multi-line overlay box. See the next method for details.
334
335			=cut
336
337			sub urxvt::term::scr_overlay {
338			my ($self, $x, $y, $text) = @_;
339
340			my @lines = split /\n/, $text;
341
342			my $w = 0;
343	root	1.6	for (map $self->strwidth ($_), @lines) {
344	root	1.1	$w = $_ if $w < $_;
345			}
346
347			$self->scr_overlay_new ($x, $y, $w, scalar @lines);
348			$self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
349			}
350
351			=item $term->scr_overlay_new ($x, $y, $width, $height)
352
353			Create a new (empty) overlay at the given position with the given
354			width/height. A border will be put around the box. If either C<$x> or
355			C<$y> is negative, then this is counted from the right/bottom side,
356			respectively.
357
358			=item $term->scr_overlay_off
359
360			Switch the overlay off again.
361
362			=item $term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE)
363
364			Put a single character (specified numerically) at the given overlay
365			position.
366
367			=item $term->scr_overlay_set ($x, $y, $text)
368
369			Write a string at the given position into the overlay.
370
371	root	1.6	=item $cellwidth = $term->strwidth $string
372
373			Returns the number of screen-cells this string would need. Correctly
374			accounts for wide and combining characters.
375
376			=item $octets = $term->locale_encode $string
377
378			Convert the given text string into the corresponding locale encoding.
379
380			=item $string = $term->locale_decode $octets
381
382			Convert the given locale-encoded octets into a perl string.
383
384			=item $term->tt_write ($octets)
385
386			Write the octets given in C<$data> to the tty (i.e. as program input). To
387			pass characters instead of octets, you should convetr you strings first to
388			the locale-specific encoding using C<< $term->locale_encode >>.
389
390	root	1.1	=back
391
392			=head2 The C<urxvt::timer> Class
393
394			This class implements timer watchers/events. Time is represented as a
395			fractional number of seconds since the epoch. Example:
396
397			# create a digital clock display in upper right corner
398			$term->{timer} = urxvt::timer
399			->new
400			->start (urxvt::NOW)
401			->cb (sub {
402			my ($timer) = @_;
403			my $time = $timer->at;
404			$timer->start ($time + 1);
405			$self->scr_overlay (-1, 0,
406			POSIX::strftime "%H:%M:%S", localtime $time);
407			});
408
409			=over 4
410
411			=item $timer = new urxvt::timer
412
413			Create a new timer object in stopped state.
414
415			=item $timer = $timer->cb (sub { my ($timer) = @_; ... })
416
417			Set the callback to be called when the timer triggers.
418
419			=item $tstamp = $timer->at
420
421			Return the time this watcher will fire next.
422
423			=item $timer = $timer->set ($tstamp)
424
425			Set the time the event is generated to $tstamp.
426
427			=item $timer = $timer->start
428
429			Start the timer.
430
431			=item $timer = $timer->start ($tstamp)
432
433			Set the event trigger time to C<$tstamp> and start the timer.
434
435			=item $timer = $timer->stop
436
437			Stop the timer.
438
439			=back
440
441			=head2 The C<urxvt::iow> Class
442
443			This class implements io watchers/events. Example:
444
445			$term->{socket} = ...
446			$term->{iow} = urxvt::iow
447			->new
448			->fd (fileno $term->{socket})
449			->events (1) # wait for read data
450			->start
451			->cb (sub {
452			my ($iow, $revents) = @_;
453			# $revents must be 1 here, no need to check
454			sysread $term->{socket}, my $buf, 8192
455			or end-of-file;
456			});
457
458
459			=over 4
460
461			=item $iow = new urxvt::iow
462
463			Create a new io watcher object in stopped state.
464
465			=item $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
466
467			Set the callback to be called when io events are triggered. C<$reventmask>
468			is a bitset as described in the C<events> method.
469
470			=item $iow = $iow->fd ($fd)
471
472			Set the filedescriptor (not handle) to watch.
473
474			=item $iow = $iow->events ($eventmask)
475
476			Set the event mask to watch. Bit #0 (value C<1>) enables watching for read
477			data, Bit #1 (value C<2>) enables watching for write data.
478
479			=item $iow = $iow->start
480
481			Start watching for requested events on the given handle.
482
483			=item $iow = $iow->stop
484
485			Stop watching for events on the given filehandle.
486
487			=back
488
489	root	1.4	=head1 ENVIRONMENT
490
491			=head2 URXVT_PERL_VERBOSITY
492
493			This variable controls the verbosity level of the perl extension. Higher
494			numbers indicate more verbose output.
495
496			=over 4
497
498			=item 0 - only fatal messages
499
500			=item 3 - script loading and management
501
502			=item 10 - all events received
503
504			=back
505
506	root	1.1	=head1 AUTHOR
507
508			Marc Lehmann <pcg@goof.com>
509			http://software.schmorp.de/pkg/rxvt-unicode
510
511			=cut
512
513			1