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.218 by root, Sun Jun 10 17:31:53 2012 UTC vs.
Revision 1.220 by root, Tue Jun 19 18:17:56 2012 UTC

… …
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 vewiwed 37in F<@@RXVT_LIBDIR@@/urxvt/perl/>, and the documentation can be viewed
38using F<< man urxvt-<EXTENSIONNAME> >>. 38using F<< 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 @@RXVT_NAME@@ -pe <extensionname>
… …
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 that add command line parameters or resources on their own are
49laoded automatically when used. 49loaded automatically when used.
50 50
51=head1 API DOCUMENTATION 51=head1 API DOCUMENTATION
52 52
53=head2 General API Considerations 53=head2 General API Considerations
54 54
… …
112=item $urxvt_term = $self->{term} 112=item $urxvt_term = $self->{term}
113 113
114Returns the C<urxvt::term> object associated with this instance of the 114Returns the C<urxvt::term> object associated with this instance of the
115extension. This member I<must not> be changed in any way. 115extension. This member I<must not> be changed in any way.
116 116
117=item $self->enable ($hook_name => $cb, [$hook_name => $cb..]) 117=item $self->enable ($hook_name => $cb[, $hook_name => $cb..])
118 118
119Dynamically enable the given hooks (named without the C<on_> prefix) for 119Dynamically enable the given hooks (named without the C<on_> prefix) for
120this extension, replacing any previous hook. This is useful when you want 120this extension, replacing any previous hook. This is useful when you want
121to overwrite time-critical hooks only temporarily. 121to overwrite time-critical hooks only temporarily.
122 122
123To install additional callbacks for the same hook, you cna use the C<on>
124method of the C<urxvt::term> class.
125
123=item $self->disable ($hook_name[, $hook_name..]) 126=item $self->disable ($hook_name[, $hook_name..])
124 127
125Dynamically disable the given hooks. 128Dynamically disable the given hooks.
129
130=item $self->x_resource ($pattern)
131
132=item $self->x_resource_boolean ($pattern)
133
134These methods support an additional C<%> prefix when called on an
135extension object - see the description of these methods in the
136C<urxvt::term> class for details.
126 137
127=back 138=back
128 139
129=head2 Hooks 140=head2 Hooks
130 141
… …
735 if (my $cb = $TERM->{_hook}[$htype]) { 746 if (my $cb = $TERM->{_hook}[$htype]) {
736 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")" 747 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
737 if $verbosity >= 10; 748 if $verbosity >= 10;
738 749
739 for my $pkg (keys %$cb) { 750 for my $pkg (keys %$cb) {
740 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg}, @_) }; 751 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg} || $TERM, @_) };
741 $retval ||= $retval_; 752 $retval ||= $retval_;
742 753
743 if ($@) { 754 if ($@) {
744 $TERM->ungrab; # better to lose the grab than the session 755 $TERM->ungrab; # better to lose the grab than the session
745 warn $@; 756 warn $@;
… …
1058 1069
1059Destroy the terminal object (close the window, free resources 1070Destroy the terminal object (close the window, free resources
1060etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event 1071etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event
1061watchers (timers, io watchers) are still active. 1072watchers (timers, io watchers) are still active.
1062 1073
1074=item $guard = $self->on ($hook_name => $cb[, $hook_name => $cb..])
1075
1076Similar to the extension method C<enable>, but installs additional
1077callbacks for the givne hook(s) (existing ones are not replaced), and
1078returns a guard object. When the guard object is destroyed the callbacks
1079are disabled again.
1080
1081Note that these callbacks receive the normal paramaters, but the first
1082argument (normally the extension) is currently undefined.
1083
1084=cut
1085
1086sub urxvt::term::on_disable::DESTROY {
1087 my $disable = shift;
1088
1089 my $self = delete $disable->{""};
1090
1091 while (my ($htype, $id) = each %$disable) {
1092 delete $self->{_hook}[$htype]{$id};
1093 $self->set_should_invoke ($htype, -1);
1094 }
1095}
1096
1097sub on {
1098 my ($self, %hook) = @_;
1099
1100 my %disable = ( "" => $self );
1101
1102 while (my ($name, $cb) = each %hook) {
1103 my $htype = $HOOKTYPE{uc $name};
1104 defined $htype
1105 or Carp::croak "unsupported hook type '$name'";
1106
1107 my $id = $cb+0;
1108
1109 $self->set_should_invoke ($htype, +1);
1110 $disable{$htype} = $id;
1111 $self->{_hook}[$htype]{$id} = $cb;
1112 }
1113
1114 bless \%disable, "urxvt::term::on_disable"
1115}
1116
1063=item $term->exec_async ($cmd[, @args]) 1117=item $term->exec_async ($cmd[, @args])
1064 1118
1065Works like the combination of the C<fork>/C<exec> builtins, which executes 1119Works like the combination of the C<fork>/C<exec> builtins, which executes
1066("starts") programs in the background. This function takes care of setting 1120("starts") programs in the background. This function takes care of setting
1067the user environment before exec'ing the command (e.g. C<PATH>) and should 1121the user environment before exec'ing the command (e.g. C<PATH>) and should
… …
1121 1175
1122Here is a likely non-exhaustive list of resource names, not all of which 1176Here is a likely non-exhaustive list of resource names, not all of which
1123are supported in every build, please see the source file F</src/rsinc.h> 1177are supported in every build, please see the source file F</src/rsinc.h>
1124to see the actual list: 1178to see the actual list:
1125 1179
1126 answerbackstring backgroundPixmap backspace_key blendtype blurradius 1180 answerbackstring backgroundPixmap backspace_key blurradius
1127 boldFont boldItalicFont borderLess buffered chdir color cursorBlink 1181 boldFont boldItalicFont borderLess buffered chdir color cursorBlink
1128 cursorUnderline cutchars delete_key depth display_name embed ext_bwidth 1182 cursorUnderline cutchars delete_key depth display_name embed ext_bwidth
1129 fade font geometry hold iconName iconfile imFont imLocale inputMethod 1183 fade font geometry hold iconName iconfile imFont imLocale inputMethod
1130 insecure int_bwidth intensityStyles iso14755 iso14755_52 italicFont 1184 insecure int_bwidth intensityStyles iso14755 iso14755_52 italicFont
1131 jumpScroll letterSpace lineSpace loginShell mapAlert meta8 modifier 1185 jumpScroll letterSpace lineSpace loginShell mapAlert meta8 modifier
… …
1156Extensions that define extra resource or command line arguments also need 1210Extensions that define extra resource or command line arguments also need
1157to call this method to access their values. 1211to call this method to access their values.
1158 1212
1159If the method is called on an extension object (basically, from an 1213If the method is called on an extension object (basically, from an
1160extension), then the special prefix C<%.> will be replaced by the name of 1214extension), then the special prefix C<%.> will be replaced by the name of
1161the extension and a dot, and the lone string C<%> will be replcaed by the 1215the extension and a dot, and the lone string C<%> will be replaced by the
1162extension name itself. This makes it possible to code extensions so you 1216extension name itself. This makes it possible to code extensions so you
1163can rename them and get a new set of commandline switches and resources 1217can rename them and get a new set of commandline switches and resources
1164without having to change the actual code. 1218without having to change the actual code.
1165 1219
1166This method should only be called during the C<on_start> hook, as there is 1220This method should only be called during the C<on_start> hook, as there is

Diff Legend

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