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.37 by root, Fri Jan 6 03:40:19 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 266=item on_key_press $term, $event, $octets
267 267
268=item on_key_release $term, $event 268=item on_key_release $term, $event
269 269
270=item on_button_press $term, $event 270=item on_button_press $term, $event
271 271
272=item on_button_release $term, $event 272=item on_button_release $term, $event
273 273
274=item on_motion_notify $term, $event 274=item on_motion_notify $term, $event
275 275
276Called whenever the corresponding X event is received for the terminal. If 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. 277the hook returns true, then the even will be ignored by rxvt-unicode.
278 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
279subwindow. 286subwindow.
280 287
281=back 288=back
282 289
283=head2 Variables in the C<urxvt> Package 290=head2 Variables in the C<urxvt> Package
284 291
285=over 4 292=over 4
286 293
287=item $urxvt::TERM 294=item $urxvt::TERM
288 295
289The current terminal. Whenever a callback/Hook is bein executed, this 296The current terminal. This variable stores the current C<urxvt::term>
290variable stores the current C<urxvt::term> object. 297object, whenever a callback/hook is executing.
291 298
292=back 299=back
293 300
294=head2 Functions in the C<urxvt> Package 301=head2 Functions in the C<urxvt> Package
295 302
… …
422 $hook_count[$htype]++ 429 $hook_count[$htype]++
423 or set_should_invoke $htype, 1; 430 or set_should_invoke $htype, 1;
424 } 431 }
425} 432}
426 433
427my $script_pkg = "script0000"; 434my $extension_pkg = "extension0000";
428my %script_pkg; 435my %extension_pkg;
429 436
430# load a single script into its own package, once only 437# load a single script into its own package, once only
431sub script_package($) { 438sub extension_package($) {
432 my ($path) = @_; 439 my ($path) = @_;
433 440
434 $script_pkg{$path} ||= do { 441 $extension_pkg{$path} ||= do {
435 my $pkg = "urxvt::" . ($script_pkg++); 442 my $pkg = "urxvt::" . ($extension_pkg++);
436 443
437 verbose 3, "loading script '$path' into package '$pkg'"; 444 verbose 3, "loading extension '$path' into package '$pkg'";
438 445
439 open my $fh, "<:raw", $path 446 open my $fh, "<:raw", $path
440 or die "$path: $!"; 447 or die "$path: $!";
441 448
442 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"
443 . "#line 1 \"$path\"\n{\n" 451 . "#line 1 \"$path\"\n{\n"
444 . (do { local $/; <$fh> }) 452 . (do { local $/; <$fh> })
445 . "\n};\n1"; 453 . "\n};\n1";
446 454
447 eval $source or die "$path: $@"; 455 eval $source or die "$path: $@";
… …
458 my $htype = shift; 466 my $htype = shift;
459 467
460 if ($htype == 0) { # INIT 468 if ($htype == 0) { # INIT
461 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 469 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
462 470
463 for my $ext (map { split /:/, $TERM->resource ("perl_ext_$_") } 1, 2) { 471 for my $ext (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
464 my @files = grep -f $_, map "$_/$ext", @dirs; 472 my @files = grep -f $_, map "$_/$ext", @dirs;
465 473
466 if (@files) { 474 if (@files) {
467 register_package script_package $files[0]; 475 register_package extension_package $files[0];
468 } else { 476 } else {
469 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";
470 } 478 }
471 } 479 }
472 } 480 }
… …
478 if $verbosity >= 10; 486 if $verbosity >= 10;
479 487
480 keys %$cb; 488 keys %$cb;
481 489
482 while (my ($pkg, $cb) = each %$cb) { 490 while (my ($pkg, $cb) = each %$cb) {
491 eval {
483 $retval = $cb->( 492 $retval = $cb->(
484 $TERM->{_pkg}{$pkg} ||= do { 493 $TERM->{_pkg}{$pkg} ||= do {
485 my $proxy = bless { }, urxvt::term::proxy::; 494 my $proxy = bless { }, $pkg;
486 Scalar::Util::weaken ($proxy->{term} = $TERM); 495 Scalar::Util::weaken ($proxy->{term} = $TERM);
487 $proxy 496 $proxy
488 }, 497 },
489 @_, 498 @_,
490 ) and last; 499 ) and last;
500 };
501 warn $@ if $@;#d#
491 } 502 }
492 } 503 }
493 504
494 if ($htype == 1) { # DESTROY 505 if ($htype == 1) { # DESTROY
495 # remove hooks if unused 506 # remove hooks if unused
… …
656 667
657If hidden, display the overlay again. 668If hidden, display the overlay again.
658 669
659=back 670=back
660 671
661=item $cellwidth = $term->strwidth $string 672=item $cellwidth = $term->strwidth ($string)
662 673
663Returns the number of screen-cells this string would need. Correctly 674Returns the number of screen-cells this string would need. Correctly
664accounts for wide and combining characters. 675accounts for wide and combining characters.
665 676
666=item $octets = $term->locale_encode $string 677=item $octets = $term->locale_encode ($string)
667 678
668Convert the given text string into the corresponding locale encoding. 679Convert the given text string into the corresponding locale encoding.
669 680
670=item $string = $term->locale_decode $octets 681=item $string = $term->locale_decode ($octets)
671 682
672Convert the given locale-encoded octets into a perl string. 683Convert the given locale-encoded octets into a perl string.
673 684
674=item $term->scr_add_lines ($string) 685=item $term->scr_add_lines ($string)
675 686
… …
691=item $term->tt_write ($octets) 702=item $term->tt_write ($octets)
692 703
693Write 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
694pass characters instead of octets, you should convert your strings first 705pass characters instead of octets, you should convert your strings first
695to 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.
696 715
697=item $window_width = $term->width 716=item $window_width = $term->width
698 717
699=item $window_height = $term->height 718=item $window_height = $term->height
700 719

Diff Legend

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