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.39 by root, Fri Jan 6 05:28:55 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
… …
62 62
63Displays a digital clock using the built-in overlay. 63Displays a digital clock using the built-in overlay.
64 64
65=item mark-urls 65=item mark-urls
66 66
67Uses per-line filtering (C<on_line_update>) to underline urls. 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.
68 74
69=item example-refresh-hooks 75=item example-refresh-hooks
70 76
71Displays 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
72window. Illustrates overwriting the refresh callbacks to create your own 78window. Illustrates overwriting the refresh callbacks to create your own
73overlays or changes. 79overlays or changes.
74
75=item example-filter-input
76
77A not very useful example of filtering all text output to the terminal, by
78underlining all urls that matches a certain regex (i.e. some urls :). It
79is not very useful because urls that are output in multiple steps (e.g.
80when typing them) do not get marked.
81 80
82=back 81=back
83 82
84=head2 General API Considerations 83=head2 General API Considerations
85 84
… …
117 116
118=back 117=back
119 118
120=head2 Hooks 119=head2 Hooks
121 120
122The following subroutines can be declared in loaded scripts, and will be 121The following subroutines can be declared in extension files, and will be
123called whenever the relevant event happens. 122called whenever the relevant event happens.
124 123
125The 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
126and 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
127its 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>
128object 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>
129member. 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.
130 130
131All 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
132counts 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,
133and 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.
134 134
… …
291 291
292=over 4 292=over 4
293 293
294=item $urxvt::TERM 294=item $urxvt::TERM
295 295
296The current terminal. Whenever a callback/Hook is bein executed, this 296The current terminal. This variable stores the current C<urxvt::term>
297variable stores the current C<urxvt::term> object. 297object, whenever a callback/hook is executing.
298 298
299=back 299=back
300 300
301=head2 Functions in the C<urxvt> Package 301=head2 Functions in the C<urxvt> Package
302 302
… …
429 $hook_count[$htype]++ 429 $hook_count[$htype]++
430 or set_should_invoke $htype, 1; 430 or set_should_invoke $htype, 1;
431 } 431 }
432} 432}
433 433
434my $script_pkg = "script0000"; 434my $extension_pkg = "extension0000";
435my %script_pkg; 435my %extension_pkg;
436 436
437# load a single script into its own package, once only 437# load a single script into its own package, once only
438sub script_package($) { 438sub extension_package($) {
439 my ($path) = @_; 439 my ($path) = @_;
440 440
441 $script_pkg{$path} ||= do { 441 $extension_pkg{$path} ||= do {
442 my $pkg = "urxvt::" . ($script_pkg++); 442 my $pkg = "urxvt::" . ($extension_pkg++);
443 443
444 verbose 3, "loading script '$path' into package '$pkg'"; 444 verbose 3, "loading extension '$path' into package '$pkg'";
445 445
446 open my $fh, "<:raw", $path 446 open my $fh, "<:raw", $path
447 or die "$path: $!"; 447 or die "$path: $!";
448 448
449 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"
450 . "#line 1 \"$path\"\n{\n" 451 . "#line 1 \"$path\"\n{\n"
451 . (do { local $/; <$fh> }) 452 . (do { local $/; <$fh> })
452 . "\n};\n1"; 453 . "\n};\n1";
453 454
454 eval $source or die "$path: $@"; 455 eval $source or die "$path: $@";
… …
465 my $htype = shift; 466 my $htype = shift;
466 467
467 if ($htype == 0) { # INIT 468 if ($htype == 0) { # INIT
468 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 469 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
469 470
470 for my $ext (map { split /:/, $TERM->resource ("perl_ext_$_") } 1, 2) { 471 for my $ext (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
471 my @files = grep -f $_, map "$_/$ext", @dirs; 472 my @files = grep -f $_, map "$_/$ext", @dirs;
472 473
473 if (@files) { 474 if (@files) {
474 register_package script_package $files[0]; 475 register_package extension_package $files[0];
475 } else { 476 } else {
476 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";
477 } 478 }
478 } 479 }
479 } 480 }
… …
485 if $verbosity >= 10; 486 if $verbosity >= 10;
486 487
487 keys %$cb; 488 keys %$cb;
488 489
489 while (my ($pkg, $cb) = each %$cb) { 490 while (my ($pkg, $cb) = each %$cb) {
491 eval {
490 $retval = $cb->( 492 $retval = $cb->(
491 $TERM->{_pkg}{$pkg} ||= do { 493 $TERM->{_pkg}{$pkg} ||= do {
492 my $proxy = bless { }, urxvt::term::proxy::; 494 my $proxy = bless { }, $pkg;
493 Scalar::Util::weaken ($proxy->{term} = $TERM); 495 Scalar::Util::weaken ($proxy->{term} = $TERM);
494 $proxy 496 $proxy
495 }, 497 },
496 @_, 498 @_,
497 ) and last; 499 ) and last;
500 };
501 warn $@ if $@;#d#
498 } 502 }
499 } 503 }
500 504
501 if ($htype == 1) { # DESTROY 505 if ($htype == 1) { # DESTROY
502 # remove hooks if unused 506 # remove hooks if unused
… …
663 667
664If hidden, display the overlay again. 668If hidden, display the overlay again.
665 669
666=back 670=back
667 671
668=item $cellwidth = $term->strwidth $string 672=item $cellwidth = $term->strwidth ($string)
669 673
670Returns the number of screen-cells this string would need. Correctly 674Returns the number of screen-cells this string would need. Correctly
671accounts for wide and combining characters. 675accounts for wide and combining characters.
672 676
673=item $octets = $term->locale_encode $string 677=item $octets = $term->locale_encode ($string)
674 678
675Convert the given text string into the corresponding locale encoding. 679Convert the given text string into the corresponding locale encoding.
676 680
677=item $string = $term->locale_decode $octets 681=item $string = $term->locale_decode ($octets)
678 682
679Convert the given locale-encoded octets into a perl string. 683Convert the given locale-encoded octets into a perl string.
680 684
681=item $term->scr_add_lines ($string) 685=item $term->scr_add_lines ($string)
682 686
… …
698=item $term->tt_write ($octets) 702=item $term->tt_write ($octets)
699 703
700Write 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
701pass characters instead of octets, you should convert your strings first 705pass characters instead of octets, you should convert your strings first
702to the locale-specific encoding using C<< $term->locale_encode >>. 706to the locale-specific encoding using C<< $term->locale_encode >>.
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.
703 715
704=item $window_width = $term->width 716=item $window_width = $term->width
705 717
706=item $window_height = $term->height 718=item $window_height = $term->height
707 719

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines