NAME
HTML::Object::Event - HTML Object Event Class
SYNOPSIS
use HTML::Object::Event;
my $event = HTML::Object::Event->new ||
die( HTML::Object::Event->error, "\n" );VERSION
v0.2.0DESCRIPTION
This module represents an event which takes place in the DOM.
Of course, unlike a web browser environment, there is no user interaction here, so all event "fired" are triggered programatically.
Events are attached to HTML elements
One element can have several such handlers, even for the exact same event
CONSTRUCTOR
new
Provided with a type and an hash or hash reference of options and this creates a new HTML::Object::Event object. An event created in this way is called a synthetic event, as opposed to an event fired by the browser, and can be dispatched by a script.
It returns the new event object upon success, or upon error, returns undef and sets an error
Parameters accepted:
- type
-
This is a string representing the type of the event.
- options hash or hash reference
-
The options can have the following properties. All of them are optional. Each of them can be accessed or modified by they equivalent method listed below.
- bubbles
-
A boolean value indicating whether the event bubbles. The default is true.
When true, this means the event will be passed on from the element that triggered it on to its parent and its parent's parent and so on up to the top element. This is the default behaviour. When set to false, the event will not bubble up.
- cancelable
-
A boolean value indicating whether the event can be cancelled. The default is true.
It can also be called as
cancellablefor non-American speakers. - composed
-
Because this is a perl environment, this value is always false, and discarded.
A boolean value indicating whether the event will trigger listeners outside of a shadow root (see "composed" for more details). The default is
false. - detail
-
An optional hash reference of arbitrary key-valu pairs that will be stored in the event object and can be later retrieved by the event handlers.
For example:
Create a look event that bubbles up and cannot be canceled
my $evt = HTML::Object::Event->new( look => { bubbles => 1, cancelable => 0 } );
$doc->dispatchEvent( $evt );
# event can be dispatched from any element, not only the document
$myDiv->dispatchEvent( $evt );PROPERTIES
bubbles
Read-only
A boolean value indicating whether or not the event bubbles up through the DOM. Default to false
When true, this means the event will be passed on from the element that triggered it on to its parent and its parent's parent and so on up to the top element. This is the default behaviour. When set to false, the event will not bubble up.
cancelable
Read-only
A boolean value indicating whether the event is cancelable. Default to true
It can also be called as cancellable for non-American speakers.
canceled
Read-only
An integer value indicating whether the event has been canceled. Its value is 1 if it has been cancelled with "stopPropagation" and 2 if it has been cancelled with "stopImmediatePropagation"
It can also be called as cancelled for non-American speakers.
cancellable
Alias for "cancelable"
cancelled
Alias for "canceled"
composed
Read-only
A boolean indicating whether or not the event can bubble across the boundary between the shadow DOM and the regular DOM. Default to false
Since this is a perl environment, this is always false, and its value is ignored.
currentTarget
Read-only
A reference to the currently registered target for the event. This is the object to which the event is currently slated to be sent. It's possible this has been changed along the way through retargeting.
defaultPrevented
Read-only
Indicates whether or not the call to "preventDefault" canceled the event. Default to false
detail
Set or get an hash reference of arbitrary key-value pairs that will be stored in this event.
eventPhase
Read-only
Returns an integer value which specifies the current evaluation phase of the event flow. Possible values are: NONE (0), CAPTURING_PHASE (1), AT_TARGET (2), BUBBLING_PHASE (3).
You can export those constants in your namespace by calling HTML::Object::Event like this:
use HTML::Object::Event qw( NONE CAPTURING_PHASE AT_TARGET BUBBLING_PHASE );or, more simply:
use HTML::Object::Event ':phase';isTrusted
Read-only
Obviously, since this is a perl environment, this is always true, because although it would be script-generated, it is fair to say your own script is trustworthy.
Indicates whether or not the event was initiated by the browser (after a user click, for instance) or by a script (using an event creation method, for example).
path
Returns the computed elements path by "composedPath", as an array object
target
Read-only
A reference to the object to which the event was originally dispatched.
timeStamp
Read-only
The time at which the event was created (in milliseconds). By specification, this value is time since epoch using Time::HiRes. This is actually a DateTime object. DateTime object supports nanoseconds.
type
Read-only
The case-insensitive type indentifying the event.
METHODS
composedPath
Returns the event's path (an array of objects on which listeners will be invoked).
dispatch
Provided with a node and this will dispatch this event to the given node.
It returns the value returned by "HTML::Object::EventTarget/dispatchEvent"
file
Returns the file path where this event was called from.
line
Returns the line at which this event was called from.
package
Returns the package name where this event was called from.
preventDefault
This does nothing under perl, except set the value of "defaultPrevented" to true.
Under JavaScript, this method is used to stop the browser’s default behavior when performing an action, such as checking a checkbox upon user click.
setTimestamp
Takes an optional unix timestamp or a DateTime object, and this will set the event timestamp. If no argument is provided, this will resort to set the timestamp using "time" in Time::HiRes, which provides a timestamp in milliseconds.
It returns a DateTime object.
stopImmediatePropagation
For this particular event, prevent all other listeners from being called. This includes listeners attached to the same element as well as those attached to elements that will be traversed later (during the capture phase, for instance).
stopPropagation
Stops the propagation of events further along in the DOM.
subroutine
Returns the subroutine where this event was called from.
CONSTANTS
NONE (0)
The event is not being processed at this time.
CAPTURING_PHASE (1)
The event is being propagated through the target's ancestor objects. This process starts with the Document, then the HTML html element, and so on through the elements until the target's parent is reached. Event listeners registered for capture mode when "addEventListener" in HTML::Object::EventTarget was called are triggered during this phase.
AT_TARGET (2)
The event has arrived at the event's target. Event listeners registered for this phase are called at this time. If "bubbles" is false, processing the event is finished after this phase is complete.
BUBBLING_PHASE (3)
The event is propagating back up through the target's ancestors in reverse order, starting with the parent, and eventually reaching the containing document. This is known as bubbling, and occurs only if "bubbles" is true. Event listeners registered for this phase are triggered during this process.
CANCEL_PROPAGATION (1)
State of the propagation being cancelled.
$event->stopPropagation();
$event->cancelled == CANCEL_PROPAGATION;CANCEL_IMMEDIATE_PROPAGATION (2)
State of immediate propagation being cancelled.
$event->stopImmediatePropagation();
$event->cancelled == CANCEL_IMMEDIATE_PROPAGATION;AUTHOR
Jacques Deguest <jack@deguest.jp>
SEE ALSO
https://developer.mozilla.org/en-US/docs/Web/API/Event
https://developer.mozilla.org/en-US/docs/Web/Events/Creating_and_triggering_events
https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Building_blocks/Events
https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent
COPYRIGHT & LICENSE
Copyright(c) 2021 DEGUEST Pte. Ltd.
All rights reserved
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.