ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/rxvt-unicode/src/urxvt.pm
(Generate patch)

Comparing rxvt-unicode/src/urxvt.pm (file contents):
Revision 1.6 by root, Mon Jan 2 18:20:23 2006 UTC vs.
Revision 1.22 by root, Tue Jan 3 19:10:54 2006 UTC

1=encoding utf8
2
1=head1 NAME 3=head1 NAME
2 4
3rxvtperl - rxvt-unicode's embedded perl interpreter 5@@RXVT_NAME@@perl - rxvt-unicode's embedded perl interpreter
4 6
5=head1 SYNOPSIS 7=head1 SYNOPSIS
6 8
7* Put your scripts into F<@@RXVT_LIBDIR@@/urxvt/perl-ext/>, they will be loaded automatically. 9 # create a file grab_test in $HOME:
8
9* Scripts are evaluated in a 'use strict' and 'use utf8' environment, and
10thus must be encoded as UTF-8.
11 10
12 sub on_sel_grab { 11 sub on_sel_grab {
13 warn "you selected ", $_[0]->selection; 12 warn "you selected ", $_[0]->selection;
14 () 13 ()
15 } 14 }
16 15
17 1 16 # start a @@RXVT_NAME@@ using it:
17
18 @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test
18 19
19=head1 DESCRIPTION 20=head1 DESCRIPTION
20 21
21On startup, @@RXVT_NAME@@ will scan F<@@RXVT_LIBDIR@@/urxvt/perl-ext/> 22Everytime a terminal object gets created, scripts specified via the
22for files and will load them. Everytime a terminal object gets created, 23C<perl> resource are loaded and associated with it.
23the directory specified by the C<perl-lib> resource will be additionally 24
24scanned. 25Scripts are compiled in a 'use strict' and 'use utf8' environment, and
26thus must be encoded as UTF-8.
25 27
26Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where 28Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where
27scripts will be shared for all terminals. 29scripts will be shared (but not enabled) for all terminals.
28 30
29Hooks in scripts specified by C<perl-lib> will only be called for the 31=head2 Prepackaged Extensions
30terminals created with that specific option value. 32
33This section describes the extensiosn delivered with this version. You can
34find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>.
35
36You can activate them like this:
37
38 @@RXVT_NAME@@ -pe <extensionname>
39
40=over 4
41
42=item selection
43
44Intelligent selection. This etxension tries to be more intelligent when the user
45extends selections (double-click).
46
47It also offers the following bindable event:
48
49=over 4
50
51=item rot13
52
53Rot-13 the selection when activated. Used via keyboard trigger:
54
55 URxvt.keysym.C-M-r: perl:selection:rot13
56
57=back
58
59=item digital-clock
60
61Displays a digital clock using the built-in overlay.
62
63=item example-refresh-hooks
64
65Displays a very simple digital clock in the upper right corner of the
66window. Illustrates overwriting the refresh callbacks to create your own
67overlays or changes.
68
69=back
31 70
32=head2 General API Considerations 71=head2 General API Considerations
33 72
34All objects (such as terminals, time watchers etc.) are typical 73All objects (such as terminals, time watchers etc.) are typical
35reference-to-hash objects. The hash can be used to store anything you 74reference-to-hash objects. The hash can be used to store anything you
36like. The only reserved member is C<_ptr>, which must not be changed. 75like. All members starting with an underscore (such as C<_ptr> or
76C<_hook>) are reserved for internal uses and must not be accessed or
77modified).
37 78
38When objects are destroyed on the C++ side, the perl object hashes are 79When objects are destroyed on the C++ side, the perl object hashes are
39emptied, so its best to store related objects such as time watchers and 80emptied, so its best to store related objects such as time watchers and
40the like inside the terminal object so they get destroyed as soon as the 81the like inside the terminal object so they get destroyed as soon as the
41terminal is destroyed. 82terminal is destroyed.
84requested from the server. The selection text can be queried and changed 125requested from the server. The selection text can be queried and changed
85by calling C<< $term->selection >>. 126by calling C<< $term->selection >>.
86 127
87Returning a true value aborts selection grabbing. It will still be hilighted. 128Returning a true value aborts selection grabbing. It will still be hilighted.
88 129
130=item on_sel_extend $term
131
132Called whenever the user tries to extend the selection (e.g. with a double
133click) and is either supposed to return false (normal operation), or
134should extend the selection itelf and return true to suppress the built-in
135processing.
136
137See the F<selection> example extension.
138
89=item on_focus_in $term 139=item on_focus_in $term
90 140
91Called whenever the window gets the keyboard focus, before urxvt does 141Called whenever the window gets the keyboard focus, before urxvt does
92focus in processing. 142focus in processing.
93 143
125 175
126=item on_refresh_end $term 176=item on_refresh_end $term
127 177
128Called just after the screen gets redrawn. See C<on_refresh_begin>. 178Called just after the screen gets redrawn. See C<on_refresh_begin>.
129 179
180=item on_keyboard_command $term, $string
181
182Called whenever the user presses a key combination that has a
183C<perl:string> action bound to it (see description of the B<keysym>
184resource in the @@RXVT_NAME@@(1) manpage).
185
130=back 186=back
131 187
132=head2 Functions in the C<urxvt> Package 188=head2 Functions in the C<urxvt> Package
133 189
134=over 4 190=over 4
149correct place, e.g. on stderr of the connecting urxvtc client. 205correct place, e.g. on stderr of the connecting urxvtc client.
150 206
151=item $time = urxvt::NOW 207=item $time = urxvt::NOW
152 208
153Returns the "current time" (as per the event loop). 209Returns the "current time" (as per the event loop).
210
211=back
212
213=head2 RENDITION
214
215Rendition bitsets contain information about colour, font, font styles and
216similar information for each screen cell.
217
218The following "macros" deal with changes in rendition sets. You should
219never just create a bitset, you should always modify an existing one,
220as they contain important information required for correct operation of
221rxvt-unicode.
222
223=over 4
224
225=item $rend = urxvt::DEFAULT_RSTYLE
226
227Returns the default rendition, as used when the terminal is starting up or
228being reset. Useful as a base to start when creating renditions.
229
230=item $rend = urxvt::OVERLAY_RSTYLE
231
232Return the rendition mask used for overlays by default.
233
234=item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
235
236Return the bit that enabled bold, italic, blink, reverse-video and
237underline, respectively. To enable such a style, just logically OR it into
238the bitset.
239
240=item $foreground = urxvt::GET_BASEFG $rend
241
242=item $background = urxvt::GET_BASEBG $rend
243
244Return the foreground/background colour index, respectively.
245
246=item $rend = urxvt::SET_FGCOLOR ($rend, $new_colour)
247
248=item $rend = urxvt::SET_BGCOLOR ($rend, $new_colour)
249
250Replace the foreground/background colour in the rendition mask with the
251specified one.
252
253=item $value = urxvt::GET_CUSTOM ($rend)
254
255Return the "custom" value: Every rendition has 5 bits for use by
256extensions. They can be set and changed as you like and are initially
257zero.
258
259=item $rend = urxvt::SET_CUSTOM ($rend, $new_value)
260
261Change the custom value.
262
263=back
154 264
155=cut 265=cut
156 266
157package urxvt; 267package urxvt;
158 268
172 unless $msg =~ /\n$/; 282 unless $msg =~ /\n$/;
173 urxvt::warn ($msg); 283 urxvt::warn ($msg);
174 }; 284 };
175} 285}
176 286
287my @hook_count;
177my $verbosity = $ENV{URXVT_PERL_VERBOSITY} || 10; 288my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
178 289
179sub verbose { 290sub verbose {
180 my ($level, $msg) = @_; 291 my ($level, $msg) = @_;
181 warn "$msg\n"; #d# 292 warn "$msg\n" if $level <= $verbosity;
182} 293}
183 294
184my @invoke_cb; 295# find on_xxx subs in the package and register them
296# as hooks
297sub register_package($) {
298 my ($pkg) = @_;
299
300 for my $htype (0.. $#HOOKNAME) {
301 my $name = $HOOKNAME[$htype];
302
303 my $ref = $pkg->can ("on_" . lc $name)
304 or next;
305
306 $term->{_hook}[$htype]{$ref*1} = $ref;
307 $hook_count[$htype]++
308 or set_should_invoke $htype, 1;
309 }
310}
311
312my $script_pkg = "script0000";
313my %script_pkg;
314
315# load a single script into its own package, once only
316sub script_package($) {
317 my ($path) = @_;
318
319 $script_pkg{$path} ||= do {
320 my $pkg = "urxvt::" . ($script_pkg++);
321
322 verbose 3, "loading script '$path' into package '$pkg'";
323
324 open my $fh, "<:raw", $path
325 or die "$path: $!";
326
327 my $source = "package $pkg; use strict; use utf8;\n"
328 . "#line 1 \"$path\"\n{\n"
329 . (do { local $/; <$fh> })
330 . "\n};\n1";
331
332 eval $source or die "$path: $@";
333
334 $pkg
335 }
336}
185 337
186# called by the rxvt core 338# called by the rxvt core
187sub invoke { 339sub invoke {
188 local $term = shift; 340 local $term = shift;
189 my $htype = shift; 341 my $htype = shift;
190 342
191 my $cb = $invoke_cb[$htype]; 343 if ($htype == 0) { # INIT
344 my @dirs = ((split /:/, $term->resource ("perl_lib")), "$LIBDIR/perl");
345
346 for my $ext (split /:/, $term->resource ("perl_ext")) {
347 my @files = grep -f $_, map "$_/$ext", @dirs;
348
349 if (@files) {
350 register_package script_package $files[0];
351 } else {
352 warn "perl extension '$ext' not found in perl library search path\n";
353 }
354 }
355
356 } elsif ($htype == 1) { # DESTROY
357 if (my $hook = $term->{_hook}) {
358 for my $htype (0..$#$hook) {
359 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
360 or set_should_invoke $htype, 0;
361 }
362 }
363 }
364
365 my $cb = $term->{_hook}[$htype]
366 or return;
192 367
193 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $term, @_) . ")" 368 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $term, @_) . ")"
194 if $verbosity >= 10; 369 if $verbosity >= 10;
195 370
196 while (my ($k, $v) = each %$cb) { 371 while (my ($k, $v) = each %$cb) {
197 return 1 if $v->($term, @_); 372 return 1 if $v->($term, @_);
198 } 373 }
199 374
200 0 375 0
201} 376}
202
203# find on_xxx subs in the package and register them
204# as hooks
205sub register_package($) {
206 my ($pkg) = @_;
207
208 for my $hook (0.. $#HOOKNAME) {
209 my $name = $HOOKNAME[$hook];
210
211 my $ref = $pkg->can ("on_" . lc $name)
212 or next;
213
214 $invoke_cb[$hook]{$ref*1} = $ref;
215 set_should_invoke $hook, 1;
216 }
217}
218
219my $script_pkg = "script0000";
220my %script_pkg;
221
222# load a single script into its own package, once only
223sub load_script($) {
224 my ($path) = @_;
225
226 $script_pkg{$path} ||= do {
227 my $pkg = $script_pkg++;
228 verbose 3, "loading script '$path' into package '$pkg'";
229
230 open my $fh, "<:raw", $path
231 or die "$path: $!";
232
233 eval "package $pkg; use strict; use utf8;\n"
234 . "#line 1 \"$path\"\n"
235 . do { local $/; <$fh> }
236 or die "$path: $@";
237
238 register_package $pkg;
239
240 $pkg
241 };
242}
243
244sub load_scripts($) {
245 my ($dir) = @_;
246
247 verbose 3, "loading scripts from '$dir'";
248
249 load_script $_
250 for grep -f $_,
251 <$dir/perl-ext/*>;
252}
253
254sub on_init {
255 my ($term) = @_;
256
257 my $libdir = $term->resource ("perl_lib");
258
259 load_scripts $libdir
260 if defined $libdir;
261}
262
263register_package __PACKAGE__;
264load_scripts $LIBDIR;
265
266=back
267 377
268=head2 The C<urxvt::term> Class 378=head2 The C<urxvt::term> Class
269 379
270=over 4 380=over 4
271 381
292 402
293 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 403 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
294 borderLess color cursorBlink cursorUnderline cutchars delete_key 404 borderLess color cursorBlink cursorUnderline cutchars delete_key
295 display_name embed ext_bwidth fade font geometry hold iconName 405 display_name embed ext_bwidth fade font geometry hold iconName
296 imFont imLocale inputMethod insecure int_bwidth intensityStyles 406 imFont imLocale inputMethod insecure int_bwidth intensityStyles
297 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 407 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
298 modifier mouseWheelScrollPage name pastableTabs path perl perl_eval 408 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext
299 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 409 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
300 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 410 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
301 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 411 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
302 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 412 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
303 shade term_name title transparent transparent_all tripleclickwords 413 shade term_name title transparent transparent_all tripleclickwords
327 437
328=item $oldtext = $term->selection ([$newtext]) 438=item $oldtext = $term->selection ([$newtext])
329 439
330Return the current selection text and optionally replace it by C<$newtext>. 440Return the current selection text and optionally replace it by C<$newtext>.
331 441
332=item $term->scr_overlay ($x, $y, $text) 442#=item $term->overlay ($x, $y, $text)
333 443#
334Create a simple multi-line overlay box. See the next method for details. 444#Create a simple multi-line overlay box. See the next method for details.
335 445#
336=cut 446#=cut
337 447
338sub urxvt::term::scr_overlay { 448sub urxvt::term::scr_overlay {
449die;
339 my ($self, $x, $y, $text) = @_; 450 my ($self, $x, $y, $text) = @_;
340 451
341 my @lines = split /\n/, $text; 452 my @lines = split /\n/, $text;
342 453
343 my $w = 0; 454 my $w = 0;
347 458
348 $self->scr_overlay_new ($x, $y, $w, scalar @lines); 459 $self->scr_overlay_new ($x, $y, $w, scalar @lines);
349 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 460 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
350} 461}
351 462
352=item $term->scr_overlay_new ($x, $y, $width, $height) 463=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
353 464
354Create a new (empty) overlay at the given position with the given 465Create a new (empty) overlay at the given position with the given
355width/height. A border will be put around the box. If either C<$x> or 466width/height. C<$rstyle> defines the initial rendition style
356C<$y> is negative, then this is counted from the right/bottom side, 467(default: C<OVERLAY_RSTYLE>).
357respectively.
358 468
359=item $term->scr_overlay_off 469If C<$border> is C<2> (default), then a decorative border will be put
470around the box.
360 471
361Switch the overlay off again. 472If either C<$x> or C<$y> is negative, then this is counted from the
473right/bottom side, respectively.
362 474
363=item $term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE) 475This method returns an urxvt::overlay object. The overlay will be visible
476as long as the perl object is referenced.
364 477
365Put a single character (specified numerically) at the given overlay 478The methods currently supported on C<urxvt::overlay> objects are:
366position.
367 479
480=over 4
481
368=item $term->scr_overlay_set ($x, $y, $text) 482=item $overlay->set ($x, $y, $text, $rend)
369 483
370Write a string at the given position into the overlay. 484Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts
485text in rxvt-unicode's special encoding and an array of rendition values
486at a specific position inside the overlay.
487
488=item $overlay->hide
489
490If visible, hide the overlay, but do not destroy it.
491
492=item $overlay->show
493
494If hidden, display the overlay again.
495
496=back
371 497
372=item $cellwidth = $term->strwidth $string 498=item $cellwidth = $term->strwidth $string
373 499
374Returns the number of screen-cells this string would need. Correctly 500Returns the number of screen-cells this string would need. Correctly
375accounts for wide and combining characters. 501accounts for wide and combining characters.
383Convert the given locale-encoded octets into a perl string. 509Convert the given locale-encoded octets into a perl string.
384 510
385=item $term->tt_write ($octets) 511=item $term->tt_write ($octets)
386 512
387Write the octets given in C<$data> to the tty (i.e. as program input). To 513Write the octets given in C<$data> to the tty (i.e. as program input). To
388pass characters instead of octets, you should convetr you strings first to 514pass characters instead of octets, you should convert your strings first
389the locale-specific encoding using C<< $term->locale_encode >>. 515to the locale-specific encoding using C<< $term->locale_encode >>.
516
517=item $nrow = $term->nrow
518
519=item $ncol = $term->ncol
520
521Return the number of rows/columns of the terminal window (i.e. as
522specified by C<-geometry>, excluding any scrollback).
523
524=item $nsaved = $term->nsaved
525
526Returns the number of lines in the scrollback buffer.
527
528=item $view_start = $term->view_start ([$newvalue])
529
530Returns the negative row number of the topmost line. Minimum value is
531C<0>, which displays the normal terminal contents. Larger values scroll
532this many lines into the scrollback buffer.
533
534=item $term->want_refresh
535
536Requests a screen refresh. At the next opportunity, rxvt-unicode will
537compare the on-screen display with its stored representation. If they
538differ, it redraws the differences.
539
540Used after changing terminal contents to display them.
541
542=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
543
544Returns the text of the entire row with number C<$row_number>. Row C<0>
545is the topmost terminal line, row C<< $term->$ncol-1 >> is the bottommost
546terminal line. The scrollback buffer starts at line C<-1> and extends to
547line C<< -$term->nsaved >>.
548
549If C<$new_text> is specified, it will replace characters in the current
550line, starting at column C<$start_col> (default C<0>), which is useful
551to replace only parts of a line. The font index in the rendition will
552automatically be updated.
553
554C<$text> is in a special encoding: tabs and wide characters that use more
555than one cell when displayed are padded with urxvt::NOCHAR characters
556(C<chr 65535>). Characters with combining characters and other characters
557that do not fit into the normal tetx encoding will be replaced with
558characters in the private use area.
559
560You have to obey this encoding when changing text. The advantage is
561that C<substr> and similar functions work on screen cells and not on
562characters.
563
564The methods C<< $term->special_encode >> and C<< $term->special_decode >>
565can be used to convert normal strings into this encoding and vice versa.
566
567=item $rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])
568
569Like C<< $term->ROW_t >>, but returns an arrayref with rendition
570bitsets. Rendition bitsets contain information about colour, font, font
571styles and similar information. See also C<< $term->ROW_t >>.
572
573When setting rendition, the font mask will be ignored.
574
575See the section on RENDITION, above.
576
577=item $length = $term->ROW_l ($row_number[, $new_length])
578
579Returns the number of screen cells that are in use ("the line length"). If
580it is C<-1>, then the line is part of a multiple-row logical "line", which
581means all characters are in use and it is continued on the next row.
582
583=item $text = $term->special_encode $string
584
585Converts a perl string into the special encoding used by rxvt-unicode,
586where one character corresponds to one screen cell. See
587C<< $term->ROW_t >> for details.
588
589=item $string = $term->special_decode $text
590
591Converts rxvt-unicodes text reprsentation into a perl string. See
592C<< $term->ROW_t >> for details.
390 593
391=back 594=back
392 595
393=head2 The C<urxvt::timer> Class 596=head2 The C<urxvt::timer> Class
394 597
395This class implements timer watchers/events. Time is represented as a 598This class implements timer watchers/events. Time is represented as a
396fractional number of seconds since the epoch. Example: 599fractional number of seconds since the epoch. Example:
397 600
398 # create a digital clock display in upper right corner 601 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
399 $term->{timer} = urxvt::timer 602 $term->{timer} = urxvt::timer
400 ->new 603 ->new
401 ->start (urxvt::NOW) 604 ->interval (1)
402 ->cb (sub { 605 ->cb (sub {
403 my ($timer) = @_;
404 my $time = $timer->at;
405 $timer->start ($time + 1);
406 $self->scr_overlay (-1, 0, 606 $term->{overlay}->set (0, 0,
407 POSIX::strftime "%H:%M:%S", localtime $time); 607 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
408 }); 608 });
409 609
410=over 4 610=over 4
411 611
412=item $timer = new urxvt::timer 612=item $timer = new urxvt::timer
413 613
414Create a new timer object in stopped state. 614Create a new timer object in started state. It is scheduled to fire
615immediately.
415 616
416=item $timer = $timer->cb (sub { my ($timer) = @_; ... }) 617=item $timer = $timer->cb (sub { my ($timer) = @_; ... })
417 618
418Set the callback to be called when the timer triggers. 619Set the callback to be called when the timer triggers.
419 620
422Return the time this watcher will fire next. 623Return the time this watcher will fire next.
423 624
424=item $timer = $timer->set ($tstamp) 625=item $timer = $timer->set ($tstamp)
425 626
426Set the time the event is generated to $tstamp. 627Set the time the event is generated to $tstamp.
628
629=item $timer = $timer->interval ($interval)
630
631Normally (and when C<$interval> is C<0>), the timer will automatically
632stop after it has fired once. If C<$interval> is non-zero, then the timer
633is automatically rescheduled at the given intervals.
427 634
428=item $timer = $timer->start 635=item $timer = $timer->start
429 636
430Start the timer. 637Start the timer.
431 638

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines