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.221 by sf-exg, Thu Jun 21 06:08:05 2012 UTC vs.
Revision 1.222 by root, Sat Jul 7 07:00:17 2012 UTC

… …
103internal use. 103internal use.
104 104
105Although it isn't a C<urxvt::term> object, you can call all methods of the 105Although it isn't a C<urxvt::term> object, you can call all methods of the
106C<urxvt::term> class on this object. 106C<urxvt::term> class on this object.
107 107
108It has the following methods and data members: 108Additional methods only supported for extension objects are described in
109 109the C<urxvt::extension> section below.
110=over 4
111
112=item $urxvt_term = $self->{term}
113
114Returns the C<urxvt::term> object associated with this instance of the
115extension. This member I<must not> be changed in any way.
116
117=item $self->enable ($hook_name => $cb[, $hook_name => $cb..])
118
119Dynamically enable the given hooks (named without the C<on_> prefix) for
120this extension, replacing any previous hook. This is useful when you want
121to overwrite time-critical hooks only temporarily.
122
123To install additional callbacks for the same hook, you can use the C<on>
124method of the C<urxvt::term> class.
125
126=item $self->disable ($hook_name[, $hook_name..])
127
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.
137
138=back
139 110
140=head2 Hooks 111=head2 Hooks
141 112
142The following subroutines can be declared in extension files, and will be 113The following subroutines can be declared in extension files, and will be
143called whenever the relevant event happens. 114called whenever the relevant event happens.
… …
801 ($mask, @color{qw(fg bg)}, \@failed) 772 ($mask, @color{qw(fg bg)}, \@failed)
802} 773}
803 774
804package urxvt::term::extension; 775package urxvt::term::extension;
805 776
806sub enable { 777=head2 The C<urxvt::term::extension> class
807 my ($self, %hook) = @_;
808 my $pkg = $self->{_pkg};
809 778
810 while (my ($name, $cb) = each %hook) { 779Each extension attached to a terminal object is represented by
811 my $htype = $HOOKTYPE{uc $name}; 780a C<urxvt::term::extension> object.
812 defined $htype
813 or Carp::croak "unsupported hook type '$name'";
814 781
815 $self->set_should_invoke ($htype, +1) 782You can use these objects, which are passed to all callbacks to store any
816 unless exists $self->{term}{_hook}[$htype]{$pkg}; 783state related to the terminal and extension instance.
817 784
818 $self->{term}{_hook}[$htype]{$pkg} = $cb; 785The methods (And data members) documented below can be called on extension
819 } 786objects, in addition to call methods documented for the <urxvt::term>
820} 787class.
821 788
822sub disable { 789=over 4
823 my ($self, @hook) = @_;
824 my $pkg = $self->{_pkg};
825 790
826 for my $name (@hook) { 791=item $urxvt_term = $self->{term}
827 my $htype = $HOOKTYPE{uc $name};
828 defined $htype
829 or Carp::croak "unsupported hook type '$name'";
830 792
831 $self->set_should_invoke ($htype, -1) 793Returns the C<urxvt::term> object associated with this instance of the
832 if delete $self->{term}{_hook}[$htype]{$pkg}; 794extension. This member I<must not> be changed in any way.
833 } 795
834} 796=cut
835 797
836our $AUTOLOAD; 798our $AUTOLOAD;
837 799
838sub AUTOLOAD { 800sub AUTOLOAD {
839 $AUTOLOAD =~ /:([^:]+)$/ 801 $AUTOLOAD =~ /:([^:]+)$/
… …
852 814
853sub DESTROY { 815sub DESTROY {
854 # nop 816 # nop
855} 817}
856 818
857# urxvt::destroy_hook 819# urxvt::destroy_hook (basically a cheap Guard:: implementation)
858 820
859sub urxvt::destroy_hook::DESTROY { 821sub urxvt::destroy_hook::DESTROY {
860 ${$_[0]}->(); 822 ${$_[0]}->();
861} 823}
862 824
863sub urxvt::destroy_hook(&) { 825sub urxvt::destroy_hook(&) {
864 bless \shift, urxvt::destroy_hook:: 826 bless \shift, urxvt::destroy_hook::
865} 827}
828
829=item $self->enable ($hook_name => $cb[, $hook_name => $cb..])
830
831Dynamically enable the given hooks (named without the C<on_> prefix) for
832this extension, replacing any previous hook. This is useful when you want
833to overwrite time-critical hooks only temporarily.
834
835To install additional callbacks for the same hook, you can use the C<on>
836method of the C<urxvt::term> class.
837
838=item $self->disable ($hook_name[, $hook_name..])
839
840Dynamically disable the given hooks.
841
842=cut
843
844sub enable {
845 my ($self, %hook) = @_;
846 my $pkg = $self->{_pkg};
847
848 while (my ($name, $cb) = each %hook) {
849 my $htype = $HOOKTYPE{uc $name};
850 defined $htype
851 or Carp::croak "unsupported hook type '$name'";
852
853 $self->set_should_invoke ($htype, +1)
854 unless exists $self->{term}{_hook}[$htype]{$pkg};
855
856 $self->{term}{_hook}[$htype]{$pkg} = $cb;
857 }
858}
859
860sub disable {
861 my ($self, @hook) = @_;
862 my $pkg = $self->{_pkg};
863
864 for my $name (@hook) {
865 my $htype = $HOOKTYPE{uc $name};
866 defined $htype
867 or Carp::croak "unsupported hook type '$name'";
868
869 $self->set_should_invoke ($htype, -1)
870 if delete $self->{term}{_hook}[$htype]{$pkg};
871 }
872}
873
874=item $guard = $self->on ($hook_name => $cb[, $hook_name => $cb..])
875
876Similar to the C<enable> enable, but installs additional callbacks for
877the given hook(s) (that is, it doesn't replace existing callbacks), and
878returns a guard object. When the guard object is destroyed the callbacks
879are disabled again.
880
881=cut
882
883sub urxvt::extension::on_disable::DESTROY {
884 my $disable = shift;
885
886 my $self = delete $disable->{""};
887
888 while (my ($htype, $id) = each %$disable) {
889 delete $self->{_hook}[$htype]{$id};
890 $self->set_should_invoke ($htype, -1);
891 }
892}
893
894sub on {
895 my ($self, %hook) = @_;
896
897 my %disable = ( "" => $self );
898
899 while (my ($name, $cb) = each %hook) {
900 my $htype = $HOOKTYPE{uc $name};
901 defined $htype
902 or Carp::croak "unsupported hook type '$name'";
903
904 my $id = $cb+0;
905
906 $self->set_should_invoke ($htype, +1);
907 $disable{$htype} = $id;
908 $self->{_hook}[$htype]{$id} = sub { shift; $cb->($self, @_) }; # very ugly indeed
909 }
910
911 bless \%disable, "urxvt::extension::on_disable"
912}
913
914=item $self->x_resource ($pattern)
915
916=item $self->x_resource_boolean ($pattern)
917
918These methods support an additional C<%> prefix when called on an
919extension object - see the description of these methods in the
920C<urxvt::term> class for details.
921
922=cut
866 923
867sub x_resource { 924sub x_resource {
868 my ($self, $name) = @_; 925 my ($self, $name) = @_;
869 $name =~ s/^%(\.|$)/$_[0]{_name}$1/; 926 $name =~ s/^%(\.|$)/$_[0]{_name}$1/;
870 $self->{term}->x_resource ($name) 927 $self->{term}->x_resource ($name)
… …
873sub x_resource_boolean { 930sub x_resource_boolean {
874 my ($self, $name) = @_; 931 my ($self, $name) = @_;
875 $name =~ s/^%(\.|$)/$_[0]{_name}$1/; 932 $name =~ s/^%(\.|$)/$_[0]{_name}$1/;
876 $self->{term}->x_resource_boolean ($name) 933 $self->{term}->x_resource_boolean ($name)
877} 934}
935
936=back
937
938=cut
878 939
879package urxvt::anyevent; 940package urxvt::anyevent;
880 941
881=head2 The C<urxvt::anyevent> Class 942=head2 The C<urxvt::anyevent> Class
882 943
… …
1069 1130
1070Destroy the terminal object (close the window, free resources 1131Destroy the terminal object (close the window, free resources
1071etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event 1132etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event
1072watchers (timers, io watchers) are still active. 1133watchers (timers, io watchers) are still active.
1073 1134
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 given 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 parameters, 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
1117=item $term->exec_async ($cmd[, @args]) 1135=item $term->exec_async ($cmd[, @args])
1118 1136
1119Works like the combination of the C<fork>/C<exec> builtins, which executes 1137Works like the combination of the C<fork>/C<exec> builtins, which executes
1120("starts") programs in the background. This function takes care of setting 1138("starts") programs in the background. This function takes care of setting
1121the user environment before exec'ing the command (e.g. C<PATH>) and should 1139the user environment before exec'ing the command (e.g. C<PATH>) and should

Diff Legend

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