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.68 by root, Mon Jan 9 20:00:31 2006 UTC vs.
Revision 1.69 by root, Mon Jan 9 22:41:41 2006 UTC

… …
65 65
66=item selection-popup (enabled by default) 66=item selection-popup (enabled by default)
67 67
68Binds a popup menu to Ctrl-Button3 that lets you convert the selection 68Binds a popup menu to Ctrl-Button3 that lets you convert the selection
69text into various other formats/action. 69text into various other formats/action.
70
71=item searchable-scrollback (enabled by default)
72
73Adds regex search functionality to the scrollback buffer, triggered by a
74hotkey (default: C<M-s>). When in search mode, terminal input/output is
75suspended, C</> starts an incremental regex search, C<n> searches further,
76C<p> jumps to the previous match. C<enter> leaves search mode at the
77current position and C<escape> returns to the original position.
70 78
71=item digital-clock 79=item digital-clock
72 80
73Displays a digital clock using the built-in overlay. 81Displays a digital clock using the built-in overlay.
74 82
… …
124Either binary data or - more common - a text string encoded in a 132Either binary data or - more common - a text string encoded in a
125locale-specific way. 133locale-specific way.
126 134
127=back 135=back
128 136
137=head2 Extension Objects
138
139Very perl extension is a perl class. A separate perl object is created
140for each terminal and each extension and passed as the first parameter to
141hooks. So extensions can use their C<$self> object without having to think
142about other extensions, with the exception of methods and members that
143begin with an underscore character C<_>: these are reserved for internal
144use.
145
146Although it isn't a C<urxvt::term> object, you can call all methods of the
147C<urxvt::term> class on this object.
148
149It has the following methods and data members:
150
151=over 4
152
153=item $urxvt_term = $self->{term}
154
155Returns the C<urxvt::term> object associated with this instance of the
156extension. This member I<must not> be changed in any way.
157
158=item $self->enable ($hook_name => $cb, [$hook_name => $cb..])
159
160Dynamically enable the given hooks (named without the C<on_> prefix) for
161this extension, replacing any previous hook. This is useful when you want
162to overwrite time-critical hooks only temporarily.
163
164=item $self->disable ($hook_name[, $hook_name..])
165
166Dynamically disable the given hooks.
167
168=back
169
129=head2 Hooks 170=head2 Hooks
130 171
131The following subroutines can be declared in extension files, and will be 172The following subroutines can be declared in extension files, and will be
132called whenever the relevant event happens. 173called whenever the relevant event happens.
133 174
134The first argument passed to them is an object private to each terminal 175The first argument passed to them is an extension oject as described in
135and extension package. You can call all C<urxvt::term> methods on it, but 176the in the C<Extension Objects> section.
136its not a real C<urxvt::term> object. Instead, the real C<urxvt::term>
137object that is shared between all packages is stored in the C<term>
138member. It is, however, blessed intot he package of the extension script,
139so for all practical purposes you can treat an extension script as a class.
140 177
141All of them must return a boolean value. If it is true, then the event 178B<All> of these hooks must return a boolean value. If it is true, then the
142counts as being I<consumed>, and the invocation of other hooks is skipped, 179event counts as being I<consumed>, and the invocation of other hooks is
143and the relevant action might not be carried out by the C++ code. 180skipped, and the relevant action might not be carried out by the C++ code.
144 181
145When in doubt, return a false value (preferably C<()>). 182I<< When in doubt, return a false value (preferably C<()>). >>
146 183
147=over 4 184=over 4
148 185
149=item on_init $term 186=item on_init $term
150 187
… …
267=item on_focus_out $term 304=item on_focus_out $term
268 305
269Called wheneever the window loses keyboard focus, before rxvt-unicode does 306Called wheneever the window loses keyboard focus, before rxvt-unicode does
270focus out processing. 307focus out processing.
271 308
272=item on_key_press $term, $event, $octets 309=item on_key_press $term, $event, $keysym, $octets
273 310
274=item on_key_release $term, $event 311=item on_key_release $term, $event, $keysym
275 312
276=item on_button_press $term, $event 313=item on_button_press $term, $event
277 314
278=item on_button_release $term, $event 315=item on_button_release $term, $event
279 316
… …
411 448
412package urxvt; 449package urxvt;
413 450
414use utf8; 451use utf8;
415use strict; 452use strict;
453use Carp ();
416use Scalar::Util (); 454use Scalar::Util ();
417use List::Util (); 455use List::Util ();
418 456
419our $VERSION = 1; 457our $VERSION = 1;
420our $TERM; 458our $TERM;
421our @HOOKNAME; 459our @HOOKNAME;
460our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
422our %OPTION; 461our %OPTION;
423our $LIBDIR; 462our $LIBDIR;
424 463
425BEGIN { 464BEGIN {
426 urxvt->bootstrap; 465 urxvt->bootstrap;
… …
460 verbose 3, "loading extension '$path' into package '$pkg'"; 499 verbose 3, "loading extension '$path' into package '$pkg'";
461 500
462 open my $fh, "<:raw", $path 501 open my $fh, "<:raw", $path
463 or die "$path: $!"; 502 or die "$path: $!";
464 503
504 my $source = untaint
465 my $source = untaint "package $pkg; use strict; use utf8;\n" 505 "package $pkg; use strict; use utf8;\n"
466 . "use base urxvt::term::proxy::;\n" 506 . "use base urxvt::term::proxy::;\n"
467 . "#line 1 \"$path\"\n{\n" 507 . "#line 1 \"$path\"\n{\n"
468 . (do { local $/; <$fh> }) 508 . (do { local $/; <$fh> })
469 . "\n};\n1"; 509 . "\n};\n1";
470 510
511 eval $source
471 eval $source or die "$path: $@"; 512 or die "$path: $@";
472 513
473 $pkg 514 $pkg
474 } 515 }
475} 516}
476 517
… …
486 527
487 my %ext_arg; 528 my %ext_arg;
488 529
489 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) { 530 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
490 if ($_ eq "default") { 531 if ($_ eq "default") {
491 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup); 532 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback);
492 } elsif (/^-(.*)$/) { 533 } elsif (/^-(.*)$/) {
493 delete $ext_arg{$1}; 534 delete $ext_arg{$1};
494 } elsif (/^([^<]+)<(.*)>$/) { 535 } elsif (/^([^<]+)<(.*)>$/) {
495 push @{ $ext_arg{$1} }, $2; 536 push @{ $ext_arg{$1} }, $2;
496 } else { 537 } else {
… …
530 } 571 }
531 } 572 }
532 } 573 }
533 574
534 if ($htype == 1) { # DESTROY 575 if ($htype == 1) { # DESTROY
535 # remove hooks if unused
536 if (my $hook = $TERM->{_hook}) { 576 if (my $hook = delete $TERM->{_hook}) {
537 for my $htype (0..$#$hook) { 577 for my $htype (0..$#$hook) {
538 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} } 578 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
539 or set_should_invoke $htype, 0; 579 or set_should_invoke $htype, 0;
540 } 580 }
541 } 581 }
… …
550 $retval 590 $retval
551} 591}
552 592
553# urxvt::term::proxy 593# urxvt::term::proxy
554 594
555sub urxvt::term::proxy::AUTOLOAD { 595package urxvt::term::proxy;
556 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/ 596
597sub enable {
598 my ($self, %hook) = @_;
599 my $pkg = $self->{_pkg};
600
601 while (my ($name, $cb) = each %hook) {
602 my $htype = $HOOKTYPE{uc $name};
603 defined $htype
604 or Carp::croak "unsupported hook type '$name'";
605
606 unless (exists $self->{term}{_hook}[$htype]{$pkg}) {
607 $hook_count[$htype]++
608 or urxvt::set_should_invoke $htype, 1;
609 }
610
611 $self->{term}{_hook}[$htype]{$pkg} = $cb;
612 }
613}
614
615sub disable {
616 my ($self, @hook) = @_;
617 my $pkg = $self->{_pkg};
618
619 for my $name (@hook) {
620 my $htype = $HOOKTYPE{uc $name};
621 defined $htype
622 or Carp::croak "unsupported hook type '$name'";
623
624 if (delete $self->{term}{_hook}[$htype]{$pkg}) {
625 --$hook_count[$htype]
626 or urxvt::set_should_invoke $htype, 0;
627 }
628 }
629}
630
631our $AUTOLOAD;
632
633sub AUTOLOAD {
634 $AUTOLOAD =~ /:([^:]+)$/
557 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable"; 635 or die "FATAL: \$AUTOLOAD '$AUTOLOAD' unparsable";
558 636
559 eval qq{ 637 eval qq{
560 sub $urxvt::term::proxy::AUTOLOAD { 638 sub $AUTOLOAD {
561 my \$proxy = shift; 639 my \$proxy = shift;
562 \$proxy->{term}->$1 (\@_) 640 \$proxy->{term}->$1 (\@_)
563 } 641 }
564 1 642 1
565 } or die "FATAL: unable to compile method forwarder: $@"; 643 } or die "FATAL: unable to compile method forwarder: $@";
566 644
567 goto &$urxvt::term::proxy::AUTOLOAD; 645 goto &$AUTOLOAD;
568} 646}
569 647
570sub urxvt::term::proxy::DESTROY { 648sub DESTROY {
571 # nop 649 # nop
572} 650}
573 651
574# urxvt::destroy_hook 652# urxvt::destroy_hook
575 653
… …
642 ${$_[0]}++; 720 ${$_[0]}++;
643} 721}
644 722
645sub urxvt::anyevent::condvar::wait { 723sub urxvt::anyevent::condvar::wait {
646 unless (${$_[0]}) { 724 unless (${$_[0]}) {
647 require Carp;
648 Carp::croak ("AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API"); 725 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API";
649 } 726 }
650} 727}
651 728
652package urxvt::term; 729package urxvt::term;
653 730
… …
660# find on_xxx subs in the package and register them 737# find on_xxx subs in the package and register them
661# as hooks 738# as hooks
662sub register_package { 739sub register_package {
663 my ($self, $pkg, $argv) = @_; 740 my ($self, $pkg, $argv) = @_;
664 741
665 my $proxy = bless { argv => $argv }, $pkg; 742 my $proxy = bless {
743 _pkg => $pkg,
744 argv => $argv,
745 }, $pkg;
666 Scalar::Util::weaken ($proxy->{term} = $TERM); 746 Scalar::Util::weaken ($proxy->{term} = $self);
667 747
668 $self->{_pkg}{$pkg} = $proxy; 748 $self->{_pkg}{$pkg} = $proxy;
669 749
670 for my $htype (0.. $#HOOKNAME) { 750 for my $name (@HOOKNAME) {
671 my $name = $HOOKNAME[$htype];
672
673 my $ref = $pkg->can ("on_" . lc $name) 751 if (my $ref = $pkg->can ("on_" . lc $name)) {
674 or next; 752 $proxy->enable ($name => $ref);
675 753 }
676 $self->{_hook}[$htype]{$pkg} = $ref;
677 $hook_count[$htype]++
678 or urxvt::set_should_invoke $htype, 1;
679 } 754 }
680} 755}
681 756
682=item $term->destroy 757=item $term->destroy
683 758
… …
739 my ($self, $name) = (shift, shift); 814 my ($self, $name) = (shift, shift);
740 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 815 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
741 &urxvt::term::_resource 816 &urxvt::term::_resource
742} 817}
743 818
819=item $success = $term->parse_keysym ($keysym_spec, $command_string)
820
821Adds a keymap translation exactly as specified via a resource. See the
822C<keysym> resource in the @@RXVT_NAME@@(1) manpage.
823
744=item $rend = $term->rstyle ([$new_rstyle]) 824=item $rend = $term->rstyle ([$new_rstyle])
745 825
746Return and optionally change the current rendition. Text that is output by 826Return and optionally change the current rendition. Text that is output by
747the terminal application will use this style. 827the terminal application will use this style.
748 828
… …
767 847
768=item $oldtext = $term->selection ([$newtext]) 848=item $oldtext = $term->selection ([$newtext])
769 849
770Return the current selection text and optionally replace it by C<$newtext>. 850Return the current selection text and optionally replace it by C<$newtext>.
771 851
772#=item $term->overlay ($x, $y, $text) 852=item $term->overlay_simple ($x, $y, $text)
773# 853
774#Create a simple multi-line overlay box. See the next method for details. 854Create a simple multi-line overlay box. See the next method for details.
775# 855
776#=cut 856=cut
777# 857
778#sub urxvt::term::scr_overlay { 858sub overlay_simple {
779# my ($self, $x, $y, $text) = @_; 859 my ($self, $x, $y, $text) = @_;
780# 860
781# my @lines = split /\n/, $text; 861 my @lines = split /\n/, $text;
782# 862
783# my $w = 0; 863 my $w = List::Util::max map $self->strwidth ($_), @lines;
784# for (map $self->strwidth ($_), @lines) { 864
785# $w = $_ if $w < $_;
786# }
787#
788# $self->scr_overlay_new ($x, $y, $w, scalar @lines); 865 my $overlay = $self->overlay ($x, $y, $w, scalar @lines);
789# $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 866 $overlay->set (0, $_, $lines[$_]) for 0.. $#lines;
790#} 867
868 $overlay
869}
791 870
792=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 871=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
793 872
794Create a new (empty) overlay at the given position with the given 873Create a new (empty) overlay at the given position with the given
795width/height. C<$rstyle> defines the initial rendition style 874width/height. C<$rstyle> defines the initial rendition style
… …
862 941
863=item $string = $term->locale_decode ($octets) 942=item $string = $term->locale_decode ($octets)
864 943
865Convert the given locale-encoded octets into a perl string. 944Convert the given locale-encoded octets into a perl string.
866 945
946=item $term->scr_bell
947
948Ring the bell!
949
867=item $term->scr_add_lines ($string) 950=item $term->scr_add_lines ($string)
868 951
869Write the given text string to the screen, as if output by the application 952Write the given text string to the screen, as if output by the application
870running inside the terminal. It may not contain command sequences (escape 953running inside the terminal. It may not contain command sequences (escape
871codes), but is free to use line feeds, carriage returns and tabs. The 954codes), but is free to use line feeds, carriage returns and tabs. The
… …
884=item $term->tt_write ($octets) 967=item $term->tt_write ($octets)
885 968
886Write the octets given in C<$data> to the tty (i.e. as program input). To 969Write the octets given in C<$data> to the tty (i.e. as program input). To
887pass characters instead of octets, you should convert your strings first 970pass characters instead of octets, you should convert your strings first
888to the locale-specific encoding using C<< $term->locale_encode >>. 971to the locale-specific encoding using C<< $term->locale_encode >>.
972
973=item $old_events = $term->pty_ev_events ([$new_events])
974
975Replaces the event mask of the pty watcher by the given event mask. Can
976be used to suppress input and output handling to the pty/tty. See the
977description of C<< urxvt::timer->events >>. Make sure to always restore
978the previous value.
889 979
890=item $windowid = $term->parent 980=item $windowid = $term->parent
891 981
892Return the window id of the toplevel window. 982Return the window id of the toplevel window.
893 983
… …
1300 1390
1301 $term->{socket} = ... 1391 $term->{socket} = ...
1302 $term->{iow} = urxvt::iow 1392 $term->{iow} = urxvt::iow
1303 ->new 1393 ->new
1304 ->fd (fileno $term->{socket}) 1394 ->fd (fileno $term->{socket})
1305 ->events (1) # wait for read data 1395 ->events (urxvt::EVENT_READ)
1306 ->start 1396 ->start
1307 ->cb (sub { 1397 ->cb (sub {
1308 my ($iow, $revents) = @_; 1398 my ($iow, $revents) = @_;
1309 # $revents must be 1 here, no need to check 1399 # $revents must be 1 here, no need to check
1310 sysread $term->{socket}, my $buf, 8192 1400 sysread $term->{socket}, my $buf, 8192
… …
1327 1417
1328Set the filedescriptor (not handle) to watch. 1418Set the filedescriptor (not handle) to watch.
1329 1419
1330=item $iow = $iow->events ($eventmask) 1420=item $iow = $iow->events ($eventmask)
1331 1421
1332Set the event mask to watch. Bit #0 (value C<1>) enables watching for read 1422Set the event mask to watch. The only allowed values are
1333data, Bit #1 (value C<2>) enables watching for write data. 1423C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed
1424together, or C<urxvt::EVENT_NONE>.
1334 1425
1335=item $iow = $iow->start 1426=item $iow = $iow->start
1336 1427
1337Start watching for requested events on the given handle. 1428Start watching for requested events on the given handle.
1338 1429

Diff Legend

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