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.222 by root, Sat Jul 7 07:00:17 2012 UTC vs.
Revision 1.247 by root, Fri Dec 26 19:19:30 2014 UTC

1=encoding utf8 1=encoding utf8
2 2
3=head1 NAME 3=head1 NAME
4 4
5@@RXVT_NAME@@perl - rxvt-unicode's embedded perl interpreter 5urxvtperl - rxvt-unicode's embedded perl interpreter
6 6
7=head1 SYNOPSIS 7=head1 SYNOPSIS
8 8
9 # create a file grab_test in $HOME: 9 # create a file grab_test in $HOME:
10 10
11 sub on_sel_grab { 11 sub on_sel_grab {
12 warn "you selected ", $_[0]->selection; 12 warn "you selected ", $_[0]->selection;
13 () 13 ()
14 } 14 }
15 15
16 # start a @@RXVT_NAME@@ using it: 16 # start a urxvt using it:
17 17
18 @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test 18 urxvt --perl-lib $HOME -pe grab_test
19 19
20=head1 DESCRIPTION 20=head1 DESCRIPTION
21 21
22Every time a terminal object gets created, extension scripts specified via 22Every time a terminal object gets created, extension scripts specified via
23the C<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 "vars"' and 'use utf8' environment, and 25Scripts are compiled in a 'use strict "vars"' 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 urxvtd, where
29scripts will be shared (but not enabled) for all terminals. 29scripts will be shared (but not enabled) for all terminals.
30 30
31You can disable the embedded perl interpreter by setting both "perl-ext" 31You can disable the embedded perl interpreter by setting both "perl-ext"
32and "perl-ext-common" resources to the empty string. 32and "perl-ext-common" resources to the empty string.
33 33
34=head1 PREPACKAGED EXTENSIONS 34=head1 PREPACKAGED EXTENSIONS
35 35
36A number of extensions are delivered with this release. You can find them 36A number of extensions are delivered with this release. You can find them
37in F<@@RXVT_LIBDIR@@/urxvt/perl/>, and the documentation can be viewed 37in F<< <libdir>/urxvt/perl/ >>, and the documentation can be viewed using
38using F<< man urxvt-<EXTENSIONNAME> >>. 38F<< man urxvt-<EXTENSIONNAME> >>.
39 39
40You can activate them like this: 40You can activate them like this:
41 41
42 @@RXVT_NAME@@ -pe <extensionname> 42 urxvt -pe <extensionname>
43 43
44Or by adding them to the resource for extensions loaded by default: 44Or by adding them to the resource for extensions loaded by default:
45 45
46 URxvt.perl-ext-common: default,selection-autotransform 46 URxvt.perl-ext-common: default,selection-autotransform
47 47
48Extensions that add command line parameters or resources on their own are 48Extensions may add additional resources and C<actions>, i.e., methods
49loaded automatically when used. 49which can be bound to a key and invoked by the user. An extension can
50define the resources it support and also default bindings for one or
51more actions it provides using so called META comments, described
52below. Similarly to builtin resources, extension resources can also be
53specified on the command line as long options (with C<.> replaced by
54C<->), in which case the corresponding extension is loaded
55automatically. For this to work the extension B<must> define META
56comments for its resources.
50 57
51=head1 API DOCUMENTATION 58=head1 API DOCUMENTATION
52 59
53=head2 General API Considerations 60=head2 General API Considerations
54 61
… …
106C<urxvt::term> class on this object. 113C<urxvt::term> class on this object.
107 114
108Additional methods only supported for extension objects are described in 115Additional methods only supported for extension objects are described in
109the C<urxvt::extension> section below. 116the C<urxvt::extension> section below.
110 117
118=head2 META comments
119
120Rxvt-unicode recognizes special meta comments in extensions that define
121different types of metadata.
122
123Currently, it recxognises only one such comment:
124
125=over 4
126
127=item #:META:RESOURCE:name:type:desc
128
129The RESOURCE comment defines a resource used by the extension, where
130C<name> is the resource name, C<type> is the resource type, C<boolean>
131or C<string>, and C<desc> is the resource description.
132
133=back
134
111=head2 Hooks 135=head2 Hooks
112 136
113The following subroutines can be declared in extension files, and will be 137The following subroutines can be declared in extension files, and will be
114called whenever the relevant event happens. 138called whenever the relevant event happens.
115 139
… …
281 305
282=item on_refresh_end $term 306=item on_refresh_end $term
283 307
284Called just after the screen gets redrawn. See C<on_refresh_begin>. 308Called just after the screen gets redrawn. See C<on_refresh_begin>.
285 309
310=item on_action $term, $string
311
312Called whenever an action is invoked for the corresponding extension
313(e.g. via a C<extension:string> builtin action bound to a key, see
314description of the B<keysym> resource in the urxvt(1) manpage). The
315event is simply the action string. Note that an action event is always
316associated to a single extension.
317
286=item on_user_command $term, $string 318=item on_user_command $term, $string *DEPRECATED*
287 319
288Called whenever a user-configured event is being activated (e.g. via 320Called whenever a user-configured event is being activated (e.g. via
289a C<perl:string> action bound to a key, see description of the B<keysym> 321a C<perl:string> action bound to a key, see description of the B<keysym>
290resource in the @@RXVT_NAME@@(1) manpage). 322resource in the urxvt(1) manpage).
291 323
292The event is simply the action string. This interface is assumed to change 324The event is simply the action string. This interface is going away in
293slightly in the future. 325preference to the C<on_action> hook.
294
295=item on_register_command $term, $keysym, $modifiermask, $string
296
297Called after parsing a keysym resource but before registering the
298associated binding. If this hook returns TRUE the binding is not
299registered. It can be used to modify a binding by calling
300C<register_command>.
301 326
302=item on_resize_all_windows $term, $new_width, $new_height 327=item on_resize_all_windows $term, $new_width, $new_height
303 328
304Called just after the new window size has been calculated, but before 329Called just after the new window size has been calculated, but before
305windows are actually being resized or hints are being set. If this hook 330windows are actually being resized or hints are being set. If this hook
306returns TRUE, setting of the window hints is being skipped. 331returns a true value, setting of the window hints is being skipped.
307 332
308=item on_x_event $term, $event 333=item on_x_event $term, $event
309 334
310Called on every X event received on the vt window (and possibly other 335Called on every X event received on the vt window (and possibly other
311windows). Should only be used as a last resort. Most event structure 336windows). Should only be used as a last resort. Most event structure
… …
350manpage), with the additional members C<row> and C<col>, which are the 375manpage), with the additional members C<row> and C<col>, which are the
351(real, not screen-based) row and column under the mouse cursor. 376(real, not screen-based) row and column under the mouse cursor.
352 377
353C<on_key_press> additionally receives the string rxvt-unicode would 378C<on_key_press> additionally receives the string rxvt-unicode would
354output, if any, in locale-specific encoding. 379output, if any, in locale-specific encoding.
355
356subwindow.
357 380
358=item on_client_message $term, $event 381=item on_client_message $term, $event
359 382
360=item on_wm_protocols $term, $event 383=item on_wm_protocols $term, $event
361 384
… …
564no warnings 'utf8'; 587no warnings 'utf8';
565 588
566sub parse_resource { 589sub parse_resource {
567 my ($term, $name, $isarg, $longopt, $flag, $value) = @_; 590 my ($term, $name, $isarg, $longopt, $flag, $value) = @_;
568 591
569 $name =~ y/-/./ if $isarg;
570
571 $term->scan_meta; 592 $term->scan_extensions;
572 593
573 my $r = $term->{meta}{resource}; 594 my $r = $term->{meta}{resource};
574 keys %$r; # reste iterator 595 keys %$r; # reset iterator
575 while (my ($pattern, $v) = each %$r) { 596 while (my ($k, $v) = each %$r) {
576 if ( 597 my $pattern = $k;
598 $pattern =~ y/./-/ if $isarg;
599 my $prefix = $name;
600 my $suffix;
577 $pattern =~ /\.$/ 601 if ($pattern =~ /\-$/) {
578 ? $pattern eq substr $name, 0, length $pattern 602 $prefix = substr $name, 0, length $pattern;
579 : $pattern eq $name 603 $suffix = substr $name, length $pattern;
580 ) { 604 }
605 if ($pattern eq $prefix) {
581 $name = "$urxvt::RESCLASS.$name"; 606 $name = "$urxvt::RESCLASS.$k$suffix";
582 607
583 push @{ $term->{perl_ext_3} }, $v->[0]; 608 push @{ $term->{perl_ext_3} }, $v->[0];
584 609
585 if ($v->[1] eq "boolean") { 610 if ($v->[1] eq "boolean") {
586 $term->put_option_db ($name, $flag ? "true" : "false"); 611 $term->put_option_db ($name, $flag ? "true" : "false");
… …
596} 621}
597 622
598sub usage { 623sub usage {
599 my ($term, $usage_type) = @_; 624 my ($term, $usage_type) = @_;
600 625
601 $term->scan_meta; 626 $term->scan_extensions;
602 627
603 my $r = $term->{meta}{resource}; 628 my $r = $term->{meta}{resource};
604 629
605 for my $pattern (sort keys %$r) { 630 for my $pattern (sort keys %$r) {
606 my ($ext, $type, $desc) = @{ $r->{$pattern} }; 631 my ($ext, $type, $desc) = @{ $r->{$pattern} };
… …
667# called by the rxvt core 692# called by the rxvt core
668sub invoke { 693sub invoke {
669 local $TERM = shift; 694 local $TERM = shift;
670 my $htype = shift; 695 my $htype = shift;
671 696
672 if ($htype == 0) { # INIT 697 if ($htype == HOOK_INIT) {
673 my @dirs = $TERM->perl_libdirs; 698 my @dirs = $TERM->perl_libdirs;
699
700 $TERM->scan_extensions;
674 701
675 my %ext_arg; 702 my %ext_arg;
676 703
677 { 704 {
678 my @init = @TERM_INIT; 705 my @init = @TERM_INIT;
… …
682 @TERM_EXT = (); 709 @TERM_EXT = ();
683 $TERM->register_package ($_) for @pkg; 710 $TERM->register_package ($_) for @pkg;
684 } 711 }
685 712
686 for ( 713 for (
714 (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2),
687 @{ delete $TERM->{perl_ext_3} }, 715 @{ delete $TERM->{perl_ext_3} }
688 grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2
689 ) { 716 ) {
690 if ($_ eq "default") { 717 if ($_ eq "default") {
718
719 $ext_arg{$_} = []
720 for
691 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback readline); 721 qw(selection option-popup selection-popup readline searchable-scrollback),
722 map $_->[0], values %{ $TERM->{meta}{binding} };
723
724 for ($TERM->_keysym_resources) {
725 next if /^(?:string|command|builtin|builtin-string|perl)/;
726 next unless /^([A-Za-z0-9_\-]+):/;
727
728 my $ext = $1;
729
730 $ext_arg{$ext} = [];
731 }
732
692 } elsif (/^-(.*)$/) { 733 } elsif (/^-(.*)$/) {
693 delete $ext_arg{$1}; 734 delete $ext_arg{$1};
735
694 } elsif (/^([^<]+)<(.*)>$/) { 736 } elsif (/^([^<]+)<(.*)>$/) {
695 push @{ $ext_arg{$1} }, $2; 737 push @{ $ext_arg{$1} }, $2;
738
696 } else { 739 } else {
697 $ext_arg{$_} ||= []; 740 $ext_arg{$_} ||= [];
741 }
742 }
743
744 # now register default key bindings
745 for my $ext (sort keys %ext_arg) {
746 while (my ($k, $v) = each %{ $TERM->{meta}{ext}{$ext}{binding} }) {
747 $TERM->bind_action ($k, "$v->[0]:$v->[1]");
698 } 748 }
699 } 749 }
700 750
701 for my $ext (sort keys %ext_arg) { 751 for my $ext (sort keys %ext_arg) {
702 my @files = grep -f $_, map "$_/$ext", @dirs; 752 my @files = grep -f $_, map "$_/$ext", @dirs;
… …
716 766
717 if (my $cb = $TERM->{_hook}[$htype]) { 767 if (my $cb = $TERM->{_hook}[$htype]) {
718 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")" 768 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
719 if $verbosity >= 10; 769 if $verbosity >= 10;
720 770
771 if ($htype == HOOK_ACTION) {
772 # this hook is only sent to the extension with the name
773 # matching the first arg
774 my $pkg = shift;
775 $pkg =~ y/-/_/;
776 $pkg = "urxvt::ext::$pkg";
777
778 $cb = $cb->{$pkg}
779 or return undef; #TODO: maybe warn user?
780
781 $cb = { $pkg => $cb };
782 }
783
721 for my $pkg (keys %$cb) { 784 for my $pkg (keys %$cb) {
722 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg} || $TERM, @_) }; 785 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg} || $TERM, @_) };
723 $retval ||= $retval_; 786 $retval ||= $retval_;
724 787
725 if ($@) { 788 if ($@) {
… …
730 793
731 verbose 11, "$HOOKNAME[$htype] returning <$retval>" 794 verbose 11, "$HOOKNAME[$htype] returning <$retval>"
732 if $verbosity >= 11; 795 if $verbosity >= 11;
733 } 796 }
734 797
735 if ($htype == 1) { # DESTROY 798 if ($htype == HOOK_DESTROY) {
736 # clear package objects 799 # clear package objects
737 %$_ = () for values %{ $TERM->{_pkg} }; 800 %$_ = () for values %{ $TERM->{_pkg} };
738 801
739 # clear package 802 # clear package
740 %$TERM = (); 803 %$TERM = ();
… …
827} 890}
828 891
829=item $self->enable ($hook_name => $cb[, $hook_name => $cb..]) 892=item $self->enable ($hook_name => $cb[, $hook_name => $cb..])
830 893
831Dynamically enable the given hooks (named without the C<on_> prefix) for 894Dynamically enable the given hooks (named without the C<on_> prefix) for
832this extension, replacing any previous hook. This is useful when you want 895this extension, replacing any hook previously installed via C<enable> in
833to overwrite time-critical hooks only temporarily. 896this extension.
897
898This is useful when you want to overwrite time-critical hooks only
899temporarily.
834 900
835To install additional callbacks for the same hook, you can use the C<on> 901To install additional callbacks for the same hook, you can use the C<on>
836method of the C<urxvt::term> class. 902method of the C<urxvt::term> class.
837 903
838=item $self->disable ($hook_name[, $hook_name..]) 904=item $self->disable ($hook_name[, $hook_name..])
… …
881=cut 947=cut
882 948
883sub urxvt::extension::on_disable::DESTROY { 949sub urxvt::extension::on_disable::DESTROY {
884 my $disable = shift; 950 my $disable = shift;
885 951
886 my $self = delete $disable->{""}; 952 my $term = delete $disable->{""};
887 953
888 while (my ($htype, $id) = each %$disable) { 954 while (my ($htype, $id) = each %$disable) {
889 delete $self->{_hook}[$htype]{$id}; 955 delete $term->{_hook}[$htype]{$id};
890 $self->set_should_invoke ($htype, -1); 956 $term->set_should_invoke ($htype, -1);
891 } 957 }
892} 958}
893 959
894sub on { 960sub on {
895 my ($self, %hook) = @_; 961 my ($self, %hook) = @_;
896 962
963 my $term = $self->{term};
964
897 my %disable = ( "" => $self ); 965 my %disable = ( "" => $term );
898 966
899 while (my ($name, $cb) = each %hook) { 967 while (my ($name, $cb) = each %hook) {
900 my $htype = $HOOKTYPE{uc $name}; 968 my $htype = $HOOKTYPE{uc $name};
901 defined $htype 969 defined $htype
902 or Carp::croak "unsupported hook type '$name'"; 970 or Carp::croak "unsupported hook type '$name'";
903 971
904 my $id = $cb+0;
905
906 $self->set_should_invoke ($htype, +1); 972 $term->set_should_invoke ($htype, +1);
907 $disable{$htype} = $id; 973 $term->{_hook}[$htype]{ $disable{$htype} = $cb+0 }
908 $self->{_hook}[$htype]{$id} = sub { shift; $cb->($self, @_) }; # very ugly indeed 974 = sub { shift; $cb->($self, @_) }; # very ugly indeed
909 } 975 }
910 976
911 bless \%disable, "urxvt::extension::on_disable" 977 bless \%disable, "urxvt::extension::on_disable"
912} 978}
913 979
980=item $self->bind_action ($hotkey, $action)
981
914=item $self->x_resource ($pattern) 982=item $self->x_resource ($pattern)
915 983
916=item $self->x_resource_boolean ($pattern) 984=item $self->x_resource_boolean ($pattern)
917 985
918These methods support an additional C<%> prefix when called on an 986These methods support an additional C<%> prefix for C<$action> or
919extension object - see the description of these methods in the 987C<$pattern> when called on an extension object, compared to the
988C<urxvt::term> methods of the same name - see the description of these
920C<urxvt::term> class for details. 989methods in the C<urxvt::term> class for details.
921 990
922=cut 991=cut
992
993sub bind_action {
994 my ($self, $hotkey, $action) = @_;
995 $action =~ s/^%:/$_[0]{_name}:/;
996 $self->{term}->bind_action ($hotkey, $action)
997}
923 998
924sub x_resource { 999sub x_resource {
925 my ($self, $name) = @_; 1000 my ($self, $name) = @_;
926 $name =~ s/^%(\.|$)/$_[0]{_name}$1/; 1001 $name =~ s/^%(\.|$)/$_[0]{_name}$1/;
927 $self->{term}->x_resource ($name) 1002 $self->{term}->x_resource ($name)
… …
1062 $ENV{URXVT_PERL_LIB}, 1137 $ENV{URXVT_PERL_LIB},
1063 "$ENV{HOME}/.urxvt/ext", 1138 "$ENV{HOME}/.urxvt/ext",
1064 "$LIBDIR/perl" 1139 "$LIBDIR/perl"
1065} 1140}
1066 1141
1067sub scan_meta { 1142# scan for available extensions and collect their metadata
1143sub scan_extensions {
1068 my ($self) = @_; 1144 my ($self) = @_;
1145
1146 return if exists $self->{meta};
1147
1069 my @libdirs = perl_libdirs $self; 1148 my @libdirs = perl_libdirs $self;
1070 1149
1071 return if $self->{meta_libdirs} eq join "\x00", @libdirs; 1150# return if $self->{meta_libdirs} eq join "\x00", @libdirs;#d#
1072 1151
1073 my %meta;
1074
1075 $self->{meta_libdirs} = join "\x00", @libdirs; 1152# $self->{meta_libdirs} = join "\x00", @libdirs;#d#
1076 $self->{meta} = \%meta; 1153 $self->{meta} = \my %meta;
1077 1154
1155 # first gather extensions
1078 for my $dir (reverse @libdirs) { 1156 for my $dir (reverse @libdirs) {
1079 opendir my $fh, $dir 1157 opendir my $fh, $dir
1080 or next; 1158 or next;
1081 for my $ext (readdir $fh) { 1159 for my $ext (readdir $fh) {
1082 $ext ne "." 1160 $ext !~ /^\./
1083 and $ext ne ".."
1084 and open my $fh, "<", "$dir/$ext" 1161 and open my $fh, "<", "$dir/$ext"
1085 or next; 1162 or next;
1086 1163
1164 my %ext = (dir => $dir);
1165
1087 while (<$fh>) { 1166 while (<$fh>) {
1088 if (/^#:META:X_RESOURCE:(.*)/) { 1167 if (/^#:META:(?:X_)?RESOURCE:(.*)/) {
1089 my ($pattern, $type, $desc) = split /:/, $1; 1168 my ($pattern, $type, $desc) = split /:/, $1;
1090 $pattern =~ s/^%(\.|$)/$ext$1/g; # % in pattern == extension name 1169 $pattern =~ s/^%(\.|$)/$ext$1/g; # % in pattern == extension name
1091 if ($pattern =~ /[^a-zA-Z0-9\-\.]/) { 1170 if ($pattern =~ /[^a-zA-Z0-9\-\.]/) {
1092 warn "$dir/$ext: meta resource '$pattern' contains illegal characters (not alphanumeric nor . nor *)\n"; 1171 warn "$dir/$ext: meta resource '$pattern' contains illegal characters (not alphanumeric nor . nor *)\n";
1093 } else { 1172 } else {
1094 $meta{resource}{$pattern} = [$ext, $type, $desc]; 1173 $ext{resource}{$pattern} = [$ext, $type, $desc];
1095 } 1174 }
1175 } elsif (/^#:META:BINDING:(.*)/) {
1176 my ($keysym, $action) = split /:/, $1;
1177 $ext{binding}{$keysym} = [$ext, $action];
1096 } elsif (/^\s*(?:#|$)/) { 1178 } elsif (/^\s*(?:#|$)/) {
1097 # skip other comments and empty lines 1179 # skip other comments and empty lines
1098 } else { 1180 } else {
1099 last; # stop parsing on first non-empty non-comment line 1181 last; # stop parsing on first non-empty non-comment line
1100 } 1182 }
1101 } 1183 }
1184
1185 $meta{ext}{$ext} = \%ext;
1102 } 1186 }
1187 }
1188
1189 # and now merge resources and bindings
1190 while (my ($k, $v) = each %{ $meta{ext} }) {
1191 #TODO: should check for extensions overriding each other
1192 %{ $meta{resource} } = (%{ $meta{resource} }, %{ $v->{resource} });
1193 %{ $meta{binding} } = (%{ $meta{binding} }, %{ $v->{binding} });
1103 } 1194 }
1104} 1195}
1105 1196
1106=item $term = new urxvt::term $envhashref, $rxvtname, [arg...] 1197=item $term = new urxvt::term $envhashref, $rxvtname, [arg...]
1107 1198
… …
1127} 1218}
1128 1219
1129=item $term->destroy 1220=item $term->destroy
1130 1221
1131Destroy the terminal object (close the window, free resources 1222Destroy the terminal object (close the window, free resources
1132etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event 1223etc.). Please note that urxvt will not exit as long as any event
1133watchers (timers, io watchers) are still active. 1224watchers (timers, io watchers) are still active.
1134 1225
1135=item $term->exec_async ($cmd[, @args]) 1226=item $term->exec_async ($cmd[, @args])
1136 1227
1137Works like the combination of the C<fork>/C<exec> builtins, which executes 1228Works like the combination of the C<fork>/C<exec> builtins, which executes
… …
1223Returns the X-Resource for the given pattern, excluding the program or 1314Returns the X-Resource for the given pattern, excluding the program or
1224class name, i.e. C<< $term->x_resource ("boldFont") >> should return the 1315class name, i.e. C<< $term->x_resource ("boldFont") >> should return the
1225same value as used by this instance of rxvt-unicode. Returns C<undef> if no 1316same value as used by this instance of rxvt-unicode. Returns C<undef> if no
1226resource with that pattern exists. 1317resource with that pattern exists.
1227 1318
1228Extensions that define extra resource or command line arguments also need 1319Extensions that define extra resources also need to call this method
1229to call this method to access their values. 1320to access their values.
1230 1321
1231If the method is called on an extension object (basically, from an 1322If the method is called on an extension object (basically, from an
1232extension), then the special prefix C<%.> will be replaced by the name of 1323extension), then the special prefix C<%.> will be replaced by the name of
1233the extension and a dot, and the lone string C<%> will be replaced by the 1324the extension and a dot, and the lone string C<%> will be replaced by the
1234extension name itself. This makes it possible to code extensions so you 1325extension name itself. This makes it possible to code extensions so you
1235can rename them and get a new set of commandline switches and resources 1326can rename them and get a new set of resources without having to change
1236without having to change the actual code. 1327the actual code.
1237 1328
1238This method should only be called during the C<on_start> hook, as there is 1329This method should only be called during the C<on_start> hook, as there is
1239only one resource database per display, and later invocations might return 1330only one resource database per display, and later invocations might return
1240the wrong resources. 1331the wrong resources.
1241 1332
… …
1253 my $res = &x_resource; 1344 my $res = &x_resource;
1254 1345
1255 $res =~ /^\s*(?:true|yes|on|1)\s*$/i ? 1 : defined $res && 0 1346 $res =~ /^\s*(?:true|yes|on|1)\s*$/i ? 1 : defined $res && 0
1256} 1347}
1257 1348
1258=item $success = $term->parse_keysym ($key, $octets) 1349=item $success = $term->bind_action ($key, $action)
1259 1350
1260Adds a key binding exactly as specified via a resource. See the 1351Adds a key binding exactly as specified via a C<keysym> resource. See the
1261C<keysym> resource in the @@RXVT_NAME@@(1) manpage. 1352C<keysym> resource in the urxvt(1) manpage.
1262 1353
1263=item $term->register_command ($keysym, $modifiermask, $string) 1354To add default bindings for an extension, the extension should call C<<
1355->bind_action >> on it's C<init> hook for every such binding. Doing it
1356in the C<init> hook allows users the override or remove the the binding
1357again.
1264 1358
1265Adds a key binding. This is a lower level api compared to 1359Example: the C<searchable-scrollback> by default binds itself
1266C<parse_keysym>, as it expects a parsed key description, and can be 1360on C<Meta-s>, using C<< $self->bind_action >>, which calls C<<
1267used only inside either the C<on_init> hook, to add a binding, or the 1361$term->bind_action >>.
1268C<on_register_command> hook, to modify a parsed binding. 1362
1363 sub init {
1364 my ($self) = @_;
1365
1366 $self->bind_action ("M-s" => "%:start");
1367 }
1269 1368
1270=item $rend = $term->rstyle ([$new_rstyle]) 1369=item $rend = $term->rstyle ([$new_rstyle])
1271 1370
1272Return and optionally change the current rendition. Text that is output by 1371Return and optionally change the current rendition. Text that is output by
1273the terminal application will use this style. 1372the terminal application will use this style.
… …
1431 1530
1432=item $term->scr_add_lines ($string) 1531=item $term->scr_add_lines ($string)
1433 1532
1434Write the given text string to the screen, as if output by the application 1533Write the given text string to the screen, as if output by the application
1435running inside the terminal. It may not contain command sequences (escape 1534running inside the terminal. It may not contain command sequences (escape
1436codes), but is free to use line feeds, carriage returns and tabs. The 1535codes - see C<cmd_parse> for that), but is free to use line feeds,
1437string is a normal text string, not in locale-dependent encoding. 1536carriage returns and tabs. The string is a normal text string, not in
1537locale-dependent encoding.
1438 1538
1439Normally its not a good idea to use this function, as programs might be 1539Normally its not a good idea to use this function, as programs might be
1440confused by changes in cursor position or scrolling. Its useful inside a 1540confused by changes in cursor position or scrolling. Its useful inside a
1441C<on_add_lines> hook, though. 1541C<on_add_lines> hook, though.
1442 1542
… …
1450locale-specific encoding of the terminal and can contain command sequences 1550locale-specific encoding of the terminal and can contain command sequences
1451(escape codes) that will be interpreted. 1551(escape codes) that will be interpreted.
1452 1552
1453=item $term->tt_write ($octets) 1553=item $term->tt_write ($octets)
1454 1554
1455Write the octets given in C<$octets> to the tty (i.e. as program input). To 1555Write the octets given in C<$octets> to the tty (i.e. as user input
1556to the program, see C<cmd_parse> for the opposite direction). To pass
1456pass characters instead of octets, you should convert your strings first 1557characters instead of octets, you should convert your strings first to the
1457to the locale-specific encoding using C<< $term->locale_encode >>. 1558locale-specific encoding using C<< $term->locale_encode >>.
1559
1560=item $term->tt_write_user_input ($octets)
1561
1562Like C<tt_write>, but should be used when writing strings in response to
1563the user pressing a key, to invoke the additional actions requested by
1564the user for that case (C<tt_write> doesn't do that).
1565
1566The typical use case would be inside C<on_action> hooks.
1458 1567
1459=item $term->tt_paste ($octets) 1568=item $term->tt_paste ($octets)
1460 1569
1461Write the octets given in C<$octets> to the tty as a paste, converting NL to 1570Write the octets given in C<$octets> to the tty as a paste, converting NL to
1462CR and bracketing the data with control sequences if bracketed paste mode 1571CR and bracketing the data with control sequences if bracketed paste mode
… …
1696} 1805}
1697 1806
1698sub urxvt::line::t { 1807sub urxvt::line::t {
1699 my ($self) = @_; 1808 my ($self) = @_;
1700 1809
1701 if (@_ > 1) 1810 if (@_ > 1) {
1702 {
1703 $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol}) 1811 $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
1704 for $self->{beg} .. $self->{end}; 1812 for $self->{beg} .. $self->{end};
1705 } 1813 }
1706 1814
1707 defined wantarray && 1815 defined wantarray &&
1708 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}), 1816 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
1709 0, $self->{len} 1817 0, $self->{len}
1710} 1818}
1711 1819
1712sub urxvt::line::r { 1820sub urxvt::line::r {
1713 my ($self) = @_; 1821 my ($self) = @_;
1714 1822
1715 if (@_ > 1) 1823 if (@_ > 1) {
1716 {
1717 $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol}) 1824 $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
1718 for $self->{beg} .. $self->{end}; 1825 for $self->{beg} .. $self->{end};
1719 } 1826 }
1720 1827
1721 if (defined wantarray) { 1828 if (defined wantarray) {
1722 my $rend = [ 1829 my $rend = [
1723 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end} 1830 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
1724 ]; 1831 ];

Diff Legend

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