view release on metacpan or  search on metacpan

lib/HTML/DOM/EventTarget.pm  view on Meta::CPAN

If a subclass needs to store event handlers and listeners elsewhere (e.g.,
associating them with another object), it can override C<addEventListener>,
C<removeEventListener>, C<event_handler> and C<get_event_listeners>.

=over

=item addEventListener($event_name, $listener, $capture)

The C<$listener> should be either a coderef or an object with a
C<handleEvent> method. (HTML::DOM does not implement any such object since
it would just be a wrapper around a coderef anyway, but has support for
them.) An object with C<&{}> overloading will also do.

C<$capture> is a boolean indicating whether this is to be triggered during
the 'capture' phase.

=cut

sub addEventListener {
	my ($self,$name,$listener, $capture) = @_;
	(\(%cevh, %evh))[!$capture]->{$self}
		{lc $name}{refaddr $listener} = $listener;
	return;
}


=item removeEventListener($event_name, $listener, $capture)

The C<$listener> should be the same reference passed to 
C<addEventListener>.

=cut

sub removeEventListener {
	my ($self,$name,$listener, $capture) = @_;
	$name = lc $name;
	my $h = (\(%cevh, %evh))[!$capture];
	exists $h->{$self}
	  and exists $$h{$self}{$name}
	  and delete $$h{$self}{$name}{refaddr $listener};
	return;
}


=item on* (onthis, onthat, onclick, onfoo, etc.)

This applies to any all-lowercase method beginning with C<on>. Basically,
C<< $target->onclick(\&sub) >> is equivalent to
C<< $target->addEventListener('click', \&sub, 0) >>, except that it
replaces any event handler already assigned via C<onclick>, returning it.
C<< $target->onclick >> (without arguments) returns the event handler
previously assigned to C<onclick> if there is one.

=cut

sub AUTOLOAD {
	my($pack,$meth) = our $AUTOLOAD =~ /(.*)::(.*)/s;
	$meth =~ /^on([a-z]+)\z/
		or die "Can't locate object method \"$meth\" via package "
			. qq'"$pack" at '.join' line ',(caller)[1,2]
			,. "\n";
	shift->event_handler($1, @_);
}
sub DESTROY{}

=item event_handler ( $name )

=item event_handler ( $name, $new_value )

This is an accessor method for event listeners created by HTML or DOM
attributes beginning with 'on'. This is used internally by the C<on*>
methods. You can use it directly for efficiency's sake.

This method used to be called C<attr_event_listener>, but that was a
mistake, as there is a distinction between handlers and listeners. The old
name is still available but will be removed in a future release. It simply
calls C<event_handler>.

=cut

sub event_handler {
	my ($self,$name) = (shift,shift);
	$name = lc $name;
	my $old = exists $aevh{$self} && exists $aevh{$self}{$name}
	 && $aevh{$self}{$name};
	@_ and $aevh{$self}{$name} = shift;
	$old ||();
}
sub attr_event_listener { shift->event_handler(@_) }


=item get_event_listeners($event_name, $capture)

This is not a DOM method (hence the underscores in the name). It returns a
list of all event listeners for the given event name. C<$capture> is a
boolean that indicates which list to return, either 'capture' listeners or
normal ones.

If there is an event handler for this event (and C<$capture> is false),
then C<get_event_listeners> tacks a wrapper for the event handler on to the
end of the list it returns.

=for comment
This is no longer true. But we may need a similar warning in case other packages install listeners that must not be removed.
B<Warning:> This method is intended mostly for internal use, but you can
go ahead and use it if you like. Just beware that some of the event
handlers returned may have been installed automatically by HTML::DOM, and
are necessary for its internal workings, so don't go passing those to
C<removeEventListener> and expect all to go well.

=cut

sub get_event_listeners { # uses underscores because it is not a DOM method
	my($self,$name,$capture) = @_;
	$name = lc $name;
	my $h = (\(%cevh, %evh))[!$capture]->{$self};
	my @ret = $h && exists $$h{$name}
		? values %{$$h{$name}}
		: ();
	if(!$capture && exists $aevh{$self} && exists $aevh{$self}{$name}