HTML::DOM::EventTarget - Perl implementation of the DOM EventTarget interface
use HTML::DOM; $doc = HTML::DOM->new; $doc->isa('HTML::DOM::EventTarget'); # true
$event = $doc->createEvent('MouseEvents'); $event->initEvent('click',1,1);
$doc->trigger_event('click'); $doc->dispatchEvent($event); # etc
This class provides the W3C's EventTarget DOM interface. It serves as a base class for the HTML::DOM::Node manpage and the HTML::DOM::Attr manpage, but any class you write can inherit from it.
This class provides the methods listed under METHODS, but will also use a few others defined by subclasses, if they are present:
These are used to determine the 'ancestry' of the event target, through
which the event will be dispatched. For each object, starting with the
target, the parentNode method is called; if it doesn't exist or returns
false, the event_parent method is tried. If that fails, then the object
is taken to be the topmost object.
The return value of this method, if it exists and returns one, is presumed
to be a code ref, and is called whenever an event handler (listener) dies.
If there is no error_handler method that returns true, then
$target->ownerDocument->error_handler is used instead. If that
fails, then errors are ignored.
If this method exists and returns false, then event handlers are not
called.
If there is no event_listeners_enabled method,
then
$target->ownerDocument->event_listeners_enabled is used instead.
See error_handler and event_listeners_enabled.
The $listener should be either a coderef or an object with a
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 &{} overloading will also do.
$capture is a boolean indicating whether this is to be triggered during
the 'capture' phase.
The $listener should be the same reference passed to
addEventListener.
This applies to any all-lowercase method beginning with on. Basically,
$target->onclick(\&sub) is equivalent to
$target->addEventListener('click', \&sub, 0), except that it
replaces any event handler already assigned via onclick, returning it.
$target->onclick (without arguments) returns the event handler
previously assigned to onclick if there is one.
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. $capture is a
boolean that indicates which list to return, either 'capture' listeners or
normal ones.
dispatchEvent($event_object)$event_object is an object returned by HTML::DOM's createEvent method,
or any object that implements the interface documented in
the HTML::DOM::Event manpage.
dispatchEvent does not automatically call the handler passed to the
document's default_event_handler. It is expected that the code that
calls this method will do that (see also trigger_event).
The return value is a boolean indicating whether the default action should be taken (i.e., whether preventDefault was not called).
Here is another non-DOM method. $event can be an event object or simply
an event name. This method triggers an
event for real, first calling dispatchEvent and then running the default
action for the event unless an event listener cancels it.
It can take named args following the $event arg. These are passed to the
event object's init method. Any
omitted args will be filled in with reasonable defaults. These are
completely ignored if $event is an event object.
Also, you can use the default arg to provide a coderef that will be
called as the default event handler. the HTML::DOM::Node manpage overrides it to do
just that, so you shouldn't need to use this arg except on a custom
subclass of EventTarget.
When $event is an event name, trigger_event automatically chooses the
right event class and a set of default args for that event name, so you can
supply just a few. E.g.,
$elem->trigger_event('click', shift => 1, button => 1);