HTML::O...t::Event(3)

📦 version 0.6.0, in alpine 3.24

💖 NAME 💖

HTML::Object::Event — HTML Object Event Class

Hiii bestie 💖 This is the HTML::O...t::Event(3) page from the User Contributed Perl Documentation — aka the HTML::Object::Event manual — and we’re about to make DOM events make sense. ✨

✨ SYNOPSIS ✨

use HTML::Object::Event;
my $event = HTML::Object::Event->new ||
    die( HTML::Object::Event->error, "\n" );

🌸 VERSION 🌸

v0.2.1

🦋 DESCRIPTION 🦋

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 programmatically. No cap.

Events are attached to HTML elements.

One element can have several such handlers, even for the exact same event. Yes bestie, the same event can have multiple little handlers hanging out on one element. 💅

🎀 CONSTRUCTOR 🎀

new

Provided with a type and a 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 their 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 cancellable for 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-value 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 a 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';

See for more information https://developer.mozilla.org/en-US/docs/Web/API/Event/eventPhase 💖

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 identifying 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 🔥

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.

Okay that’s the whole manual, bestie 🫶 This page is from perl v5.42.2, dated 2026-02-15, and it’s the HTML::O...t::Event(3) page — go forth and dispatch responsibly 💅✨

📦 where this page comes from