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.31 by root, Wed Jan 4 19:39:46 2006 UTC vs.
Revision 1.44 by root, Sat Jan 7 19:29:17 2006 UTC

17 17
18 @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test 18 @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test
19 19
20=head1 DESCRIPTION 20=head1 DESCRIPTION
21 21
22Everytime a terminal object gets created, scripts specified via the 22Everytime a terminal object gets created, extension scripts specified via
23C<perl> resource are loaded and associated with it. 23the C<perl> resource are loaded and associated with it.
24 24
25Scripts are compiled in a 'use strict' and 'use utf8' environment, and 25Scripts are compiled in a 'use strict' and 'use utf8' environment, and
26thus must be encoded as UTF-8. 26thus must be encoded as UTF-8.
27 27
28Each 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
59=back 59=back
60 60
61=item digital-clock 61=item digital-clock
62 62
63Displays a digital clock using the built-in overlay. 63Displays a digital clock using the built-in overlay.
64
65=item mark-urls
66
67Uses per-line display filtering (C<on_line_update>) to underline urls.
68
69=item block-graphics-to-ascii
70
71A not very useful example of filtering all text output to the terminal,
72by replacing all line-drawing characters (U+2500 .. U+259F) by a
73similar-looking ascii character.
64 74
65=item example-refresh-hooks 75=item example-refresh-hooks
66 76
67Displays a very simple digital clock in the upper right corner of the 77Displays a very simple digital clock in the upper right corner of the
68window. Illustrates overwriting the refresh callbacks to create your own 78window. Illustrates overwriting the refresh callbacks to create your own
81When objects are destroyed on the C++ side, the perl object hashes are 91When objects are destroyed on the C++ side, the perl object hashes are
82emptied, so its best to store related objects such as time watchers and 92emptied, so its best to store related objects such as time watchers and
83the like inside the terminal object so they get destroyed as soon as the 93the like inside the terminal object so they get destroyed as soon as the
84terminal is destroyed. 94terminal is destroyed.
85 95
96Argument names also often indicate the type of a parameter. Here are some
97hints on what they mean:
98
99=over 4
100
101=item $text
102
103Rxvt-unicodes special way of encoding text, where one "unicode" character
104always represents one screen cell. See L<row_t> for a discussion of this format.
105
106=item $string
107
108A perl text string, with an emphasis on I<text>. It can store all unicode
109characters and is to be distinguished with text encoded in a specific
110encoding (often locale-specific) and binary data.
111
112=item $octets
113
114Either binary data or - more common - a text string encoded in a
115locale-specific way.
116
117=back
118
86=head2 Hooks 119=head2 Hooks
87 120
88The following subroutines can be declared in loaded scripts, and will be 121The following subroutines can be declared in extension files, and will be
89called whenever the relevant event happens. 122called whenever the relevant event happens.
90 123
91The first argument passed to them is an object private to each terminal 124The first argument passed to them is an object private to each terminal
92and extension package. You can call all C<urxvt::term> methods on it, but 125and extension package. You can call all C<urxvt::term> methods on it, but
93its not a real C<urxvt::term> object. Instead, the real C<urxvt::term> 126its not a real C<urxvt::term> object. Instead, the real C<urxvt::term>
94object that is shared between all packages is stored in the C<term> 127object that is shared between all packages is stored in the C<term>
95member. 128member. It is, however, blessed intot he package of the extension script,
129so for all practical purposes you can treat an extension script as a class.
96 130
97All of them must return a boolean value. If it is true, then the event 131All of them must return a boolean value. If it is true, then the event
98counts as being I<consumed>, and the invocation of other hooks is skipped, 132counts as being I<consumed>, and the invocation of other hooks is skipped,
99and the relevant action might not be carried out by the C++ code. 133and the relevant action might not be carried out by the C++ code.
100 134
103=over 4 137=over 4
104 138
105=item on_init $term 139=item on_init $term
106 140
107Called after a new terminal object has been initialized, but before 141Called after a new terminal object has been initialized, but before
108windows are created or the command gets run. 142windows are created or the command gets run. Most methods are unsafe to
143call or deliver senseless data, as terminal size and other characteristics
144have not yet been determined. You can safely query and change resources,
145though.
109 146
110=item on_reset $term 147=item on_reset $term
111 148
112Called after the screen is "reset" for any reason, such as resizing or 149Called after the screen is "reset" for any reason, such as resizing or
113control sequences. Here is where you can react on changes to size-related 150control sequences. Here is where you can react on changes to size-related
185 222
186Be careful not ever to trust (in a security sense) the data you receive, 223Be careful not ever to trust (in a security sense) the data you receive,
187as its source can not easily be controleld (e-mail content, messages from 224as its source can not easily be controleld (e-mail content, messages from
188other users on the same system etc.). 225other users on the same system etc.).
189 226
227=item on_add_lines $term, $string
228
229Called whenever text is about to be output, with the text as argument. You
230can filter/change and output the text yourself by returning a true value
231and calling C<< $term->scr_add_lines >> yourself. Please note that this
232might be very slow, however, as your hook is called for B<all> text being
233output.
234
235=item on_line_update $term, $row
236
237Called whenever a line was updated or changed. Can be used to filter
238screen output (e.g. underline urls or other useless stuff). Only lines
239that are being shown will be filtered, and, due to performance reasons,
240not always immediately.
241
242The row number is always the topmost row of the line if the line spans
243multiple rows.
244
245Please note that, if you change the line, then the hook might get called
246later with the already-modified line (e.g. if unrelated parts change), so
247you cannot just toggle rendition bits, but only set them.
248
190=item on_refresh_begin $term 249=item on_refresh_begin $term
191 250
192Called just before the screen gets redrawn. Can be used for overlay 251Called just before the screen gets redrawn. Can be used for overlay
193or similar effects by modify terminal contents in refresh_begin, and 252or similar effects by modify terminal contents in refresh_begin, and
194restoring them in refresh_end. The built-in overlay and selection display 253restoring them in refresh_end. The built-in overlay and selection display
202 261
203Called whenever the user presses a key combination that has a 262Called whenever the user presses a key combination that has a
204C<perl:string> action bound to it (see description of the B<keysym> 263C<perl:string> action bound to it (see description of the B<keysym>
205resource in the @@RXVT_NAME@@(1) manpage). 264resource in the @@RXVT_NAME@@(1) manpage).
206 265
266=item on_key_press $term, $event, $octets
267
268=item on_key_release $term, $event
269
270=item on_button_press $term, $event
271
272=item on_button_release $term, $event
273
274=item on_motion_notify $term, $event
275
276Called whenever the corresponding X event is received for the terminal If
277the hook returns true, then the even will be ignored by rxvt-unicode.
278
279The event is a hash with most values as named by Xlib (see the XEvent
280manpage), with the additional members C<row> and C<col>, which are the row
281and column under the mouse cursor.
282
283C<on_key_press> additionally receives the string rxvt-unicode would
284output, if any, in locale-specific encoding.
285
286subwindow.
287
207=back 288=back
208 289
209=head2 Variables in the C<urxvt> Package 290=head2 Variables in the C<urxvt> Package
210 291
211=over 4 292=over 4
212 293
213=item $urxvt::TERM 294=item $urxvt::TERM
214 295
215The current terminal. Whenever a callback/Hook is bein executed, this 296The current terminal. This variable stores the current C<urxvt::term>
216variable stores the current C<urxvt::term> object. 297object, whenever a callback/hook is executing.
217 298
218=back 299=back
219 300
220=head2 Functions in the C<urxvt> Package 301=head2 Functions in the C<urxvt> Package
221 302
222=over 4 303=over 4
304
305=item $term = new urxvt [arg...]
306
307Creates a new terminal, very similar as if you had started it with
308C<system $binfile, arg...>. Croaks (and probably outputs an error message)
309if the new instance couldn't be created. Returns C<undef> if the new
310instance didn't initialise perl, and the terminal object otherwise. The
311C<init> and C<start> hooks will be called during the call.
223 312
224=item urxvt::fatal $errormessage 313=item urxvt::fatal $errormessage
225 314
226Fatally aborts execution with the given error message. Avoid at all 315Fatally aborts execution with the given error message. Avoid at all
227costs! The only time this is acceptable is when the terminal process 316costs! The only time this is acceptable is when the terminal process
340 $hook_count[$htype]++ 429 $hook_count[$htype]++
341 or set_should_invoke $htype, 1; 430 or set_should_invoke $htype, 1;
342 } 431 }
343} 432}
344 433
345my $script_pkg = "script0000"; 434my $extension_pkg = "extension0000";
346my %script_pkg; 435my %extension_pkg;
347 436
348# load a single script into its own package, once only 437# load a single script into its own package, once only
349sub script_package($) { 438sub extension_package($) {
350 my ($path) = @_; 439 my ($path) = @_;
351 440
352 $script_pkg{$path} ||= do { 441 $extension_pkg{$path} ||= do {
353 my $pkg = "urxvt::" . ($script_pkg++); 442 my $pkg = "urxvt::" . ($extension_pkg++);
354 443
355 verbose 3, "loading script '$path' into package '$pkg'"; 444 verbose 3, "loading extension '$path' into package '$pkg'";
356 445
357 open my $fh, "<:raw", $path 446 open my $fh, "<:raw", $path
358 or die "$path: $!"; 447 or die "$path: $!";
359 448
360 my $source = "package $pkg; use strict; use utf8;\n" 449 my $source = "package $pkg; use strict; use utf8;\n"
450 . "use base urxvt::term::proxy::;\n"
361 . "#line 1 \"$path\"\n{\n" 451 . "#line 1 \"$path\"\n{\n"
362 . (do { local $/; <$fh> }) 452 . (do { local $/; <$fh> })
363 . "\n};\n1"; 453 . "\n};\n1";
364 454
365 eval $source or die "$path: $@"; 455 eval $source or die "$path: $@";
376 my $htype = shift; 466 my $htype = shift;
377 467
378 if ($htype == 0) { # INIT 468 if ($htype == 0) { # INIT
379 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 469 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
380 470
381 for my $ext (map { split /:/, $TERM->resource ("perl_ext_$_") } 1, 2) { 471 for my $ext (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
382 my @files = grep -f $_, map "$_/$ext", @dirs; 472 my @files = grep -f $_, map "$_/$ext", @dirs;
383 473
384 if (@files) { 474 if (@files) {
385 register_package script_package $files[0]; 475 register_package extension_package $files[0];
386 } else { 476 } else {
387 warn "perl extension '$ext' not found in perl library search path\n"; 477 warn "perl extension '$ext' not found in perl library search path\n";
388 } 478 }
389 } 479 }
390 } 480 }
396 if $verbosity >= 10; 486 if $verbosity >= 10;
397 487
398 keys %$cb; 488 keys %$cb;
399 489
400 while (my ($pkg, $cb) = each %$cb) { 490 while (my ($pkg, $cb) = each %$cb) {
491 eval {
401 $retval = $cb->( 492 $retval = $cb->(
402 $TERM->{_pkg}{$pkg} ||= do { 493 $TERM->{_pkg}{$pkg} ||= do {
403 my $proxy = bless { }, urxvt::term::proxy::; 494 my $proxy = bless { }, $pkg;
404 Scalar::Util::weaken ($proxy->{term} = $TERM); 495 Scalar::Util::weaken ($proxy->{term} = $TERM);
405 $proxy 496 $proxy
406 }, 497 },
407 @_, 498 @_,
408 ) and last; 499 ) and last;
500 };
501 warn $@ if $@;#d#
409 } 502 }
410 } 503 }
411 504
412 if ($htype == 1) { # DESTROY 505 if ($htype == 1) { # DESTROY
413 # remove hooks if unused 506 # remove hooks if unused
444} 537}
445 538
446=head2 The C<urxvt::term> Class 539=head2 The C<urxvt::term> Class
447 540
448=over 4 541=over 4
542
543=item $term->destroy
544
545Destroy the terminal object (close the window, free resources etc.).
449 546
450=item $value = $term->resource ($name[, $newval]) 547=item $value = $term->resource ($name[, $newval])
451 548
452Returns the current resource value associated with a given name and 549Returns the current resource value associated with a given name and
453optionally sets a new value. Setting values is most useful in the C<init> 550optionally sets a new value. Setting values is most useful in the C<init>
487 my ($self, $name) = (shift, shift); 584 my ($self, $name) = (shift, shift);
488 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 585 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
489 goto &urxvt::term::_resource; 586 goto &urxvt::term::_resource;
490} 587}
491 588
589=item $rend = $term->rstyle ([$new_rstyle])
590
591Return and optionally change the current rendition. Text that is output by
592the terminal application will use this style.
593
594=item ($row, $col) = $term->screen_cur ([$row, $col])
595
596Return the current coordinates of the text cursor position and optionally
597set it (which is usually bad as applications don't expect that).
598
492=item ($row, $col) = $term->selection_mark ([$row, $col]) 599=item ($row, $col) = $term->selection_mark ([$row, $col])
493 600
494=item ($row, $col) = $term->selection_beg ([$row, $col]) 601=item ($row, $col) = $term->selection_beg ([$row, $col])
495 602
496=item ($row, $col) = $term->selection_end ([$row, $col]) 603=item ($row, $col) = $term->selection_end ([$row, $col])
510#=item $term->overlay ($x, $y, $text) 617#=item $term->overlay ($x, $y, $text)
511# 618#
512#Create a simple multi-line overlay box. See the next method for details. 619#Create a simple multi-line overlay box. See the next method for details.
513# 620#
514#=cut 621#=cut
515 622#
516sub urxvt::term::scr_overlay { 623#sub urxvt::term::scr_overlay {
517die;
518 my ($self, $x, $y, $text) = @_; 624# my ($self, $x, $y, $text) = @_;
519 625#
520 my @lines = split /\n/, $text; 626# my @lines = split /\n/, $text;
521 627#
522 my $w = 0; 628# my $w = 0;
523 for (map $self->strwidth ($_), @lines) { 629# for (map $self->strwidth ($_), @lines) {
524 $w = $_ if $w < $_; 630# $w = $_ if $w < $_;
525 } 631# }
526 632#
527 $self->scr_overlay_new ($x, $y, $w, scalar @lines); 633# $self->scr_overlay_new ($x, $y, $w, scalar @lines);
528 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 634# $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
529} 635#}
530 636
531=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 637=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
532 638
533Create a new (empty) overlay at the given position with the given 639Create a new (empty) overlay at the given position with the given
534width/height. C<$rstyle> defines the initial rendition style 640width/height. C<$rstyle> defines the initial rendition style
561 667
562If hidden, display the overlay again. 668If hidden, display the overlay again.
563 669
564=back 670=back
565 671
566=item $cellwidth = $term->strwidth $string 672=item $cellwidth = $term->strwidth ($string)
567 673
568Returns the number of screen-cells this string would need. Correctly 674Returns the number of screen-cells this string would need. Correctly
569accounts for wide and combining characters. 675accounts for wide and combining characters.
570 676
571=item $octets = $term->locale_encode $string 677=item $octets = $term->locale_encode ($string)
572 678
573Convert the given text string into the corresponding locale encoding. 679Convert the given text string into the corresponding locale encoding.
574 680
575=item $string = $term->locale_decode $octets 681=item $string = $term->locale_decode ($octets)
576 682
577Convert the given locale-encoded octets into a perl string. 683Convert the given locale-encoded octets into a perl string.
684
685=item $term->scr_add_lines ($string)
686
687Write the given text string to the screen, as if output by the application
688running inside the terminal. It may not contain command sequences (escape
689codes), but is free to use line feeds, carriage returns and tabs. The
690string is a normal text string, not in locale-dependent encoding.
691
692Normally its not a good idea to use this function, as programs might be
693confused by changes in cursor position or scrolling. Its useful inside a
694C<on_add_lines> hook, though.
695
696=item $term->cmd_parse ($octets)
697
698Similar to C<scr_add_lines>, but the argument must be in the
699locale-specific encoding of the terminal and can contain command sequences
700(escape codes) that will be interpreted.
578 701
579=item $term->tt_write ($octets) 702=item $term->tt_write ($octets)
580 703
581Write the octets given in C<$data> to the tty (i.e. as program input). To 704Write the octets given in C<$data> to the tty (i.e. as program input). To
582pass characters instead of octets, you should convert your strings first 705pass characters instead of octets, you should convert your strings first
583to the locale-specific encoding using C<< $term->locale_encode >>. 706to the locale-specific encoding using C<< $term->locale_encode >>.
584 707
708=item $windowid = $term->parent
709
710Return the window id of the toplevel window.
711
712=item $windowid = $term->vt
713
714Return the window id of the terminal window.
715
716=item $window_width = $term->width
717
718=item $window_height = $term->height
719
720=item $font_width = $term->fwidth
721
722=item $font_height = $term->fheight
723
724=item $font_ascent = $term->fbase
725
585=item $nrow = $term->nrow 726=item $terminal_rows = $term->nrow
586 727
587=item $ncol = $term->ncol 728=item $terminal_columns = $term->ncol
588 729
589Return the number of rows/columns of the terminal window (i.e. as 730=item $has_focus = $term->focus
590specified by C<-geometry>, excluding any scrollback).
591 731
592=item $nsaved = $term->nsaved 732=item $is_mapped = $term->mapped
593 733
594Returns the number of lines in the scrollback buffer. 734=item $max_scrollback = $term->saveLines
735
736=item $nrow_plus_saveLines = $term->total_rows
737
738=item $lines_in_scrollback = $term->nsaved
739
740Return various integers describing terminal characteristics.
595 741
596=item $view_start = $term->view_start ([$newvalue]) 742=item $view_start = $term->view_start ([$newvalue])
597 743
598Returns the negative row number of the topmost line. Minimum value is 744Returns the negative row number of the topmost line. Minimum value is
599C<0>, which displays the normal terminal contents. Larger values scroll 745C<0>, which displays the normal terminal contents. Larger values scroll
662about the logical line that row C<$row_number> is part of. It supports the 808about the logical line that row C<$row_number> is part of. It supports the
663following methods: 809following methods:
664 810
665=over 4 811=over 4
666 812
667=item $text = $line->t 813=item $text = $line->t ([$new_text])
668 814
669Returns the full text of the line, similar to C<ROW_t> 815Returns or replaces the full text of the line, similar to C<ROW_t>
670 816
671=item $rend = $line->r 817=item $rend = $line->r ([$new_rend])
672 818
673Returns the full rendition array of the line, similar to C<ROW_r> 819Returns or replaces the full rendition array of the line, similar to C<ROW_r>
674 820
675=item $length = $line->l 821=item $length = $line->l
676 822
677Returns the length of the line in cells, similar to C<ROW_l>. 823Returns the length of the line in cells, similar to C<ROW_l>.
678 824
707 853
708 bless { 854 bless {
709 term => $self, 855 term => $self,
710 beg => $beg, 856 beg => $beg,
711 end => $end, 857 end => $end,
858 ncol => $self->ncol,
712 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end), 859 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end),
713 }, urxvt::line:: 860 }, urxvt::line::
714} 861}
715 862
716sub urxvt::line::t { 863sub urxvt::line::t {
717 my ($self) = @_; 864 my ($self) = @_;
718 865
866 if (@_ > 1)
867 {
868 $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
869 for $self->{beg} .. $self->{end};
870 }
871
872 defined wantarray &&
719 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}), 873 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
720 0, $self->{len} 874 0, $self->{len}
721} 875}
722 876
723sub urxvt::line::r { 877sub urxvt::line::r {
724 my ($self) = @_; 878 my ($self) = @_;
725 879
880 if (@_ > 1)
881 {
882 $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
883 for $self->{beg} .. $self->{end};
884 }
885
886 if (defined wantarray) {
726 my $rend = [ 887 my $rend = [
727 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end} 888 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
728 ]; 889 ];
729 $#$rend = $self->{len} - 1; 890 $#$rend = $self->{len} - 1;
730 $rend 891 return $rend;
892 }
893
894 ()
731} 895}
732 896
733sub urxvt::line::beg { $_[0]{beg} } 897sub urxvt::line::beg { $_[0]{beg} }
734sub urxvt::line::end { $_[0]{end} } 898sub urxvt::line::end { $_[0]{end} }
735sub urxvt::line::l { $_[0]{len} } 899sub urxvt::line::l { $_[0]{len} }
736 900
737sub urxvt::line::offset_of { 901sub urxvt::line::offset_of {
738 my ($self, $row, $col) = @_; 902 my ($self, $row, $col) = @_;
739 903
740 ($row - $self->{beg}) * $self->{term}->ncol + $col 904 ($row - $self->{beg}) * $self->{ncol} + $col
741} 905}
742 906
743sub urxvt::line::coord_of { 907sub urxvt::line::coord_of {
744 my ($self, $offset) = @_; 908 my ($self, $offset) = @_;
745 909
746 use integer; 910 use integer;
747 911
748 ( 912 (
749 $offset / $self->{term}->ncol + $self->{beg}, 913 $offset / $self->{ncol} + $self->{beg},
750 $offset % $self->{term}->ncol 914 $offset % $self->{ncol}
751 ) 915 )
752} 916}
753 917
754=item ($row, $col) = $line->coord_of ($offset) 918=item ($row, $col) = $line->coord_of ($offset)
755=item $text = $term->special_encode $string 919=item $text = $term->special_encode $string

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines