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.248 by root, Fri Dec 26 21:01:46 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{$_} = []
691 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback readline); 720 for qw(selection option-popup selection-popup readline searchable-scrollback);
721
722 for ($TERM->_keysym_resources) {
723 next if /^(?:string|command|builtin|builtin-string|perl)/;
724 next unless /^([A-Za-z0-9_\-]+):/;
725
726 my $ext = $1;
727
728 $ext_arg{$ext} = [];
729 }
730
692 } elsif (/^-(.*)$/) { 731 } elsif (/^-(.*)$/) {
693 delete $ext_arg{$1}; 732 delete $ext_arg{$1};
733
694 } elsif (/^([^<]+)<(.*)>$/) { 734 } elsif (/^([^<]+)<(.*)>$/) {
695 push @{ $ext_arg{$1} }, $2; 735 push @{ $ext_arg{$1} }, $2;
736
696 } else { 737 } else {
697 $ext_arg{$_} ||= []; 738 $ext_arg{$_} ||= [];
698 } 739 }
699 } 740 }
700 741
… …
716 757
717 if (my $cb = $TERM->{_hook}[$htype]) { 758 if (my $cb = $TERM->{_hook}[$htype]) {
718 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")" 759 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
719 if $verbosity >= 10; 760 if $verbosity >= 10;
720 761
762 if ($htype == HOOK_ACTION) {
763 # this hook is only sent to the extension with the name
764 # matching the first arg
765 my $pkg = shift;
766 $pkg =~ y/-/_/;
767 $pkg = "urxvt::ext::$pkg";
768
769 $cb = $cb->{$pkg}
770 or return undef; #TODO: maybe warn user?
771
772 $cb = { $pkg => $cb };
773 }
774
721 for my $pkg (keys %$cb) { 775 for my $pkg (keys %$cb) {
722 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg} || $TERM, @_) }; 776 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg} || $TERM, @_) };
723 $retval ||= $retval_; 777 $retval ||= $retval_;
724 778
725 if ($@) { 779 if ($@) {
… …
730 784
731 verbose 11, "$HOOKNAME[$htype] returning <$retval>" 785 verbose 11, "$HOOKNAME[$htype] returning <$retval>"
732 if $verbosity >= 11; 786 if $verbosity >= 11;
733 } 787 }
734 788
735 if ($htype == 1) { # DESTROY 789 if ($htype == HOOK_DESTROY) {
736 # clear package objects 790 # clear package objects
737 %$_ = () for values %{ $TERM->{_pkg} }; 791 %$_ = () for values %{ $TERM->{_pkg} };
738 792
739 # clear package 793 # clear package
740 %$TERM = (); 794 %$TERM = ();
… …
827} 881}
828 882
829=item $self->enable ($hook_name => $cb[, $hook_name => $cb..]) 883=item $self->enable ($hook_name => $cb[, $hook_name => $cb..])
830 884
831Dynamically enable the given hooks (named without the C<on_> prefix) for 885Dynamically enable the given hooks (named without the C<on_> prefix) for
832this extension, replacing any previous hook. This is useful when you want 886this extension, replacing any hook previously installed via C<enable> in
833to overwrite time-critical hooks only temporarily. 887this extension.
888
889This is useful when you want to overwrite time-critical hooks only
890temporarily.
834 891
835To install additional callbacks for the same hook, you can use the C<on> 892To install additional callbacks for the same hook, you can use the C<on>
836method of the C<urxvt::term> class. 893method of the C<urxvt::term> class.
837 894
838=item $self->disable ($hook_name[, $hook_name..]) 895=item $self->disable ($hook_name[, $hook_name..])
… …
881=cut 938=cut
882 939
883sub urxvt::extension::on_disable::DESTROY { 940sub urxvt::extension::on_disable::DESTROY {
884 my $disable = shift; 941 my $disable = shift;
885 942
886 my $self = delete $disable->{""}; 943 my $term = delete $disable->{""};
887 944
888 while (my ($htype, $id) = each %$disable) { 945 while (my ($htype, $id) = each %$disable) {
889 delete $self->{_hook}[$htype]{$id}; 946 delete $term->{_hook}[$htype]{$id};
890 $self->set_should_invoke ($htype, -1); 947 $term->set_should_invoke ($htype, -1);
891 } 948 }
892} 949}
893 950
894sub on { 951sub on {
895 my ($self, %hook) = @_; 952 my ($self, %hook) = @_;
896 953
954 my $term = $self->{term};
955
897 my %disable = ( "" => $self ); 956 my %disable = ( "" => $term );
898 957
899 while (my ($name, $cb) = each %hook) { 958 while (my ($name, $cb) = each %hook) {
900 my $htype = $HOOKTYPE{uc $name}; 959 my $htype = $HOOKTYPE{uc $name};
901 defined $htype 960 defined $htype
902 or Carp::croak "unsupported hook type '$name'"; 961 or Carp::croak "unsupported hook type '$name'";
903 962
904 my $id = $cb+0;
905
906 $self->set_should_invoke ($htype, +1); 963 $term->set_should_invoke ($htype, +1);
907 $disable{$htype} = $id; 964 $term->{_hook}[$htype]{ $disable{$htype} = $cb+0 }
908 $self->{_hook}[$htype]{$id} = sub { shift; $cb->($self, @_) }; # very ugly indeed 965 = sub { shift; $cb->($self, @_) }; # very ugly indeed
909 } 966 }
910 967
911 bless \%disable, "urxvt::extension::on_disable" 968 bless \%disable, "urxvt::extension::on_disable"
912} 969}
913 970
971=item $self->bind_action ($hotkey, $action)
972
914=item $self->x_resource ($pattern) 973=item $self->x_resource ($pattern)
915 974
916=item $self->x_resource_boolean ($pattern) 975=item $self->x_resource_boolean ($pattern)
917 976
918These methods support an additional C<%> prefix when called on an 977These methods support an additional C<%> prefix for C<$action> or
919extension object - see the description of these methods in the 978C<$pattern> when called on an extension object, compared to the
979C<urxvt::term> methods of the same name - see the description of these
920C<urxvt::term> class for details. 980methods in the C<urxvt::term> class for details.
921 981
922=cut 982=cut
983
984sub bind_action {
985 my ($self, $hotkey, $action) = @_;
986 $action =~ s/^%:/$_[0]{_name}:/;
987 $self->{term}->bind_action ($hotkey, $action)
988}
923 989
924sub x_resource { 990sub x_resource {
925 my ($self, $name) = @_; 991 my ($self, $name) = @_;
926 $name =~ s/^%(\.|$)/$_[0]{_name}$1/; 992 $name =~ s/^%(\.|$)/$_[0]{_name}$1/;
927 $self->{term}->x_resource ($name) 993 $self->{term}->x_resource ($name)
… …
1062 $ENV{URXVT_PERL_LIB}, 1128 $ENV{URXVT_PERL_LIB},
1063 "$ENV{HOME}/.urxvt/ext", 1129 "$ENV{HOME}/.urxvt/ext",
1064 "$LIBDIR/perl" 1130 "$LIBDIR/perl"
1065} 1131}
1066 1132
1067sub scan_meta { 1133# scan for available extensions and collect their metadata
1134sub scan_extensions {
1068 my ($self) = @_; 1135 my ($self) = @_;
1136
1137 return if exists $self->{meta};
1138
1069 my @libdirs = perl_libdirs $self; 1139 my @libdirs = perl_libdirs $self;
1070 1140
1071 return if $self->{meta_libdirs} eq join "\x00", @libdirs; 1141# return if $self->{meta_libdirs} eq join "\x00", @libdirs;#d#
1072 1142
1073 my %meta;
1074
1075 $self->{meta_libdirs} = join "\x00", @libdirs; 1143# $self->{meta_libdirs} = join "\x00", @libdirs;#d#
1076 $self->{meta} = \%meta; 1144 $self->{meta} = \my %meta;
1077 1145
1146 # first gather extensions
1078 for my $dir (reverse @libdirs) { 1147 for my $dir (reverse @libdirs) {
1079 opendir my $fh, $dir 1148 opendir my $fh, $dir
1080 or next; 1149 or next;
1081 for my $ext (readdir $fh) { 1150 for my $ext (readdir $fh) {
1082 $ext ne "." 1151 $ext !~ /^\./
1083 and $ext ne ".."
1084 and open my $fh, "<", "$dir/$ext" 1152 and open my $fh, "<", "$dir/$ext"
1085 or next; 1153 or next;
1086 1154
1155 my %ext = (dir => $dir);
1156
1087 while (<$fh>) { 1157 while (<$fh>) {
1088 if (/^#:META:X_RESOURCE:(.*)/) { 1158 if (/^#:META:(?:X_)?RESOURCE:(.*)/) {
1089 my ($pattern, $type, $desc) = split /:/, $1; 1159 my ($pattern, $type, $desc) = split /:/, $1;
1090 $pattern =~ s/^%(\.|$)/$ext$1/g; # % in pattern == extension name 1160 $pattern =~ s/^%(\.|$)/$ext$1/g; # % in pattern == extension name
1091 if ($pattern =~ /[^a-zA-Z0-9\-\.]/) { 1161 if ($pattern =~ /[^a-zA-Z0-9\-\.]/) {
1092 warn "$dir/$ext: meta resource '$pattern' contains illegal characters (not alphanumeric nor . nor *)\n"; 1162 warn "$dir/$ext: meta resource '$pattern' contains illegal characters (not alphanumeric nor . nor *)\n";
1093 } else { 1163 } else {
1094 $meta{resource}{$pattern} = [$ext, $type, $desc]; 1164 $ext{resource}{$pattern} = [$ext, $type, $desc];
1095 } 1165 }
1096 } elsif (/^\s*(?:#|$)/) { 1166 } elsif (/^\s*(?:#|$)/) {
1097 # skip other comments and empty lines 1167 # skip other comments and empty lines
1098 } else { 1168 } else {
1099 last; # stop parsing on first non-empty non-comment line 1169 last; # stop parsing on first non-empty non-comment line
1100 } 1170 }
1101 } 1171 }
1172
1173 $meta{ext}{$ext} = \%ext;
1102 } 1174 }
1175 }
1176
1177 # and now merge resources
1178 while (my ($k, $v) = each %{ $meta{ext} }) {
1179 #TODO: should check for extensions overriding each other
1180 %{ $meta{resource} } = (%{ $meta{resource} }, %{ $v->{resource} });
1103 } 1181 }
1104} 1182}
1105 1183
1106=item $term = new urxvt::term $envhashref, $rxvtname, [arg...] 1184=item $term = new urxvt::term $envhashref, $rxvtname, [arg...]
1107 1185
… …
1127} 1205}
1128 1206
1129=item $term->destroy 1207=item $term->destroy
1130 1208
1131Destroy the terminal object (close the window, free resources 1209Destroy the terminal object (close the window, free resources
1132etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event 1210etc.). Please note that urxvt will not exit as long as any event
1133watchers (timers, io watchers) are still active. 1211watchers (timers, io watchers) are still active.
1134 1212
1135=item $term->exec_async ($cmd[, @args]) 1213=item $term->exec_async ($cmd[, @args])
1136 1214
1137Works like the combination of the C<fork>/C<exec> builtins, which executes 1215Works like the combination of the C<fork>/C<exec> builtins, which executes
… …
1223Returns the X-Resource for the given pattern, excluding the program or 1301Returns the X-Resource for the given pattern, excluding the program or
1224class name, i.e. C<< $term->x_resource ("boldFont") >> should return the 1302class 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 1303same value as used by this instance of rxvt-unicode. Returns C<undef> if no
1226resource with that pattern exists. 1304resource with that pattern exists.
1227 1305
1228Extensions that define extra resource or command line arguments also need 1306Extensions that define extra resources also need to call this method
1229to call this method to access their values. 1307to access their values.
1230 1308
1231If the method is called on an extension object (basically, from an 1309If the method is called on an extension object (basically, from an
1232extension), then the special prefix C<%.> will be replaced by the name of 1310extension), 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 1311the 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 1312extension name itself. This makes it possible to code extensions so you
1235can rename them and get a new set of commandline switches and resources 1313can rename them and get a new set of resources without having to change
1236without having to change the actual code. 1314the actual code.
1237 1315
1238This method should only be called during the C<on_start> hook, as there is 1316This 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 1317only one resource database per display, and later invocations might return
1240the wrong resources. 1318the wrong resources.
1241 1319
… …
1253 my $res = &x_resource; 1331 my $res = &x_resource;
1254 1332
1255 $res =~ /^\s*(?:true|yes|on|1)\s*$/i ? 1 : defined $res && 0 1333 $res =~ /^\s*(?:true|yes|on|1)\s*$/i ? 1 : defined $res && 0
1256} 1334}
1257 1335
1258=item $success = $term->parse_keysym ($key, $octets) 1336=item $success = $term->bind_action ($key, $action)
1259 1337
1260Adds a key binding exactly as specified via a resource. See the 1338Adds a key binding exactly as specified via a C<keysym> resource. See the
1261C<keysym> resource in the @@RXVT_NAME@@(1) manpage. 1339C<keysym> resource in the urxvt(1) manpage.
1262 1340
1263=item $term->register_command ($keysym, $modifiermask, $string) 1341To add default bindings for an extension, the extension should call C<<
1342->bind_action >> on it's C<init> hook for every such binding. Doing it
1343in the C<init> hook allows users the override or remove the the binding
1344again.
1264 1345
1265Adds a key binding. This is a lower level api compared to 1346Example: the C<searchable-scrollback> by default binds itself
1266C<parse_keysym>, as it expects a parsed key description, and can be 1347on 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 1348$term->bind_action >>.
1268C<on_register_command> hook, to modify a parsed binding. 1349
1350 sub init {
1351 my ($self) = @_;
1352
1353 $self->bind_action ("M-s" => "%:start");
1354 }
1269 1355
1270=item $rend = $term->rstyle ([$new_rstyle]) 1356=item $rend = $term->rstyle ([$new_rstyle])
1271 1357
1272Return and optionally change the current rendition. Text that is output by 1358Return and optionally change the current rendition. Text that is output by
1273the terminal application will use this style. 1359the terminal application will use this style.
… …
1431 1517
1432=item $term->scr_add_lines ($string) 1518=item $term->scr_add_lines ($string)
1433 1519
1434Write the given text string to the screen, as if output by the application 1520Write the given text string to the screen, as if output by the application
1435running inside the terminal. It may not contain command sequences (escape 1521running inside the terminal. It may not contain command sequences (escape
1436codes), but is free to use line feeds, carriage returns and tabs. The 1522codes - see C<cmd_parse> for that), but is free to use line feeds,
1437string is a normal text string, not in locale-dependent encoding. 1523carriage returns and tabs. The string is a normal text string, not in
1524locale-dependent encoding.
1438 1525
1439Normally its not a good idea to use this function, as programs might be 1526Normally 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 1527confused by changes in cursor position or scrolling. Its useful inside a
1441C<on_add_lines> hook, though. 1528C<on_add_lines> hook, though.
1442 1529
… …
1450locale-specific encoding of the terminal and can contain command sequences 1537locale-specific encoding of the terminal and can contain command sequences
1451(escape codes) that will be interpreted. 1538(escape codes) that will be interpreted.
1452 1539
1453=item $term->tt_write ($octets) 1540=item $term->tt_write ($octets)
1454 1541
1455Write the octets given in C<$octets> to the tty (i.e. as program input). To 1542Write the octets given in C<$octets> to the tty (i.e. as user input
1543to the program, see C<cmd_parse> for the opposite direction). To pass
1456pass characters instead of octets, you should convert your strings first 1544characters instead of octets, you should convert your strings first to the
1457to the locale-specific encoding using C<< $term->locale_encode >>. 1545locale-specific encoding using C<< $term->locale_encode >>.
1546
1547=item $term->tt_write_user_input ($octets)
1548
1549Like C<tt_write>, but should be used when writing strings in response to
1550the user pressing a key, to invoke the additional actions requested by
1551the user for that case (C<tt_write> doesn't do that).
1552
1553The typical use case would be inside C<on_action> hooks.
1458 1554
1459=item $term->tt_paste ($octets) 1555=item $term->tt_paste ($octets)
1460 1556
1461Write the octets given in C<$octets> to the tty as a paste, converting NL to 1557Write 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 1558CR and bracketing the data with control sequences if bracketed paste mode
… …
1696} 1792}
1697 1793
1698sub urxvt::line::t { 1794sub urxvt::line::t {
1699 my ($self) = @_; 1795 my ($self) = @_;
1700 1796
1701 if (@_ > 1) 1797 if (@_ > 1) {
1702 {
1703 $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol}) 1798 $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
1704 for $self->{beg} .. $self->{end}; 1799 for $self->{beg} .. $self->{end};
1705 } 1800 }
1706 1801
1707 defined wantarray && 1802 defined wantarray &&
1708 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}), 1803 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
1709 0, $self->{len} 1804 0, $self->{len}
1710} 1805}
1711 1806
1712sub urxvt::line::r { 1807sub urxvt::line::r {
1713 my ($self) = @_; 1808 my ($self) = @_;
1714 1809
1715 if (@_ > 1) 1810 if (@_ > 1) {
1716 {
1717 $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol}) 1811 $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
1718 for $self->{beg} .. $self->{end}; 1812 for $self->{beg} .. $self->{end};
1719 } 1813 }
1720 1814
1721 if (defined wantarray) { 1815 if (defined wantarray) {
1722 my $rend = [ 1816 my $rend = [
1723 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end} 1817 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
1724 ]; 1818 ];

Diff Legend

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