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.36 by root, Fri Jan 6 02:58:02 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
… …
261 261
262Called whenever the user presses a key combination that has a 262Called whenever the user presses a key combination that has a
263C<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>
264resource in the @@RXVT_NAME@@(1) manpage). 264resource in the @@RXVT_NAME@@(1) manpage).
265 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
266=back 288=back
267 289
268=head2 Variables in the C<urxvt> Package 290=head2 Variables in the C<urxvt> Package
269 291
270=over 4 292=over 4
271 293
272=item $urxvt::TERM 294=item $urxvt::TERM
273 295
274The current terminal. Whenever a callback/Hook is bein executed, this 296The current terminal. This variable stores the current C<urxvt::term>
275variable stores the current C<urxvt::term> object. 297object, whenever a callback/hook is executing.
276 298
277=back 299=back
278 300
279=head2 Functions in the C<urxvt> Package 301=head2 Functions in the C<urxvt> Package
280 302
… …
407 $hook_count[$htype]++ 429 $hook_count[$htype]++
408 or set_should_invoke $htype, 1; 430 or set_should_invoke $htype, 1;
409 } 431 }
410} 432}
411 433
412my $script_pkg = "script0000"; 434my $extension_pkg = "extension0000";
413my %script_pkg; 435my %extension_pkg;
414 436
415# load a single script into its own package, once only 437# load a single script into its own package, once only
416sub script_package($) { 438sub extension_package($) {
417 my ($path) = @_; 439 my ($path) = @_;
418 440
419 $script_pkg{$path} ||= do { 441 $extension_pkg{$path} ||= do {
420 my $pkg = "urxvt::" . ($script_pkg++); 442 my $pkg = "urxvt::" . ($extension_pkg++);
421 443
422 verbose 3, "loading script '$path' into package '$pkg'"; 444 verbose 3, "loading extension '$path' into package '$pkg'";
423 445
424 open my $fh, "<:raw", $path 446 open my $fh, "<:raw", $path
425 or die "$path: $!"; 447 or die "$path: $!";
426 448
427 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"
428 . "#line 1 \"$path\"\n{\n" 451 . "#line 1 \"$path\"\n{\n"
429 . (do { local $/; <$fh> }) 452 . (do { local $/; <$fh> })
430 . "\n};\n1"; 453 . "\n};\n1";
431 454
432 eval $source or die "$path: $@"; 455 eval $source or die "$path: $@";
… …
443 my $htype = shift; 466 my $htype = shift;
444 467
445 if ($htype == 0) { # INIT 468 if ($htype == 0) { # INIT
446 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 469 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
447 470
448 for my $ext (map { split /:/, $TERM->resource ("perl_ext_$_") } 1, 2) { 471 for my $ext (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
449 my @files = grep -f $_, map "$_/$ext", @dirs; 472 my @files = grep -f $_, map "$_/$ext", @dirs;
450 473
451 if (@files) { 474 if (@files) {
452 register_package script_package $files[0]; 475 register_package extension_package $files[0];
453 } else { 476 } else {
454 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";
455 } 478 }
456 } 479 }
457 } 480 }
… …
463 if $verbosity >= 10; 486 if $verbosity >= 10;
464 487
465 keys %$cb; 488 keys %$cb;
466 489
467 while (my ($pkg, $cb) = each %$cb) { 490 while (my ($pkg, $cb) = each %$cb) {
491 eval {
468 $retval = $cb->( 492 $retval = $cb->(
469 $TERM->{_pkg}{$pkg} ||= do { 493 $TERM->{_pkg}{$pkg} ||= do {
470 my $proxy = bless { }, urxvt::term::proxy::; 494 my $proxy = bless { }, $pkg;
471 Scalar::Util::weaken ($proxy->{term} = $TERM); 495 Scalar::Util::weaken ($proxy->{term} = $TERM);
472 $proxy 496 $proxy
473 }, 497 },
474 @_, 498 @_,
475 ) and last; 499 ) and last;
500 };
501 warn $@ if $@;#d#
476 } 502 }
477 } 503 }
478 504
479 if ($htype == 1) { # DESTROY 505 if ($htype == 1) { # DESTROY
480 # remove hooks if unused 506 # remove hooks if unused
… …
641 667
642If hidden, display the overlay again. 668If hidden, display the overlay again.
643 669
644=back 670=back
645 671
646=item $cellwidth = $term->strwidth $string 672=item $cellwidth = $term->strwidth ($string)
647 673
648Returns the number of screen-cells this string would need. Correctly 674Returns the number of screen-cells this string would need. Correctly
649accounts for wide and combining characters. 675accounts for wide and combining characters.
650 676
651=item $octets = $term->locale_encode $string 677=item $octets = $term->locale_encode ($string)
652 678
653Convert the given text string into the corresponding locale encoding. 679Convert the given text string into the corresponding locale encoding.
654 680
655=item $string = $term->locale_decode $octets 681=item $string = $term->locale_decode ($octets)
656 682
657Convert the given locale-encoded octets into a perl string. 683Convert the given locale-encoded octets into a perl string.
658 684
659=item $term->scr_add_lines ($string) 685=item $term->scr_add_lines ($string)
660 686
… …
676=item $term->tt_write ($octets) 702=item $term->tt_write ($octets)
677 703
678Write 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
679pass characters instead of octets, you should convert your strings first 705pass characters instead of octets, you should convert your strings first
680to 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.
681 715
682=item $window_width = $term->width 716=item $window_width = $term->width
683 717
684=item $window_height = $term->height 718=item $window_height = $term->height
685 719

Diff Legend

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