Events allow signalling something has occured and it can be anything from a simple user interaction to a website page loading !
For defining events, DOM Standard provides an IDL definition at DOM Standard - Events.

Reference: https://developer.mozilla.org/en-US/docs/Web/API/Event

Note: EventTargets here are base classes for big things like body element, paragraph element,etc..

Event

Definition and meaning for all attributes & methods along with info for JS Binding.

Almost all attributes are private and can only be accessed by member functions
Therefore, getter and setter functions for easier access are being provided for both read-only and full-access attributes !

Flags

stop_propagation_flag

Set to true for stopping propagation of current Event. stop_immediate_propagation_flag
Set to true for stopping propagation for all event handlers of current element and elements too.

Not Much Info about what these do :-

canceled_flag
in_passive_listener_flag
composed_flag
initialized_flag
dispatch_flag

Read-only Attributes

DOMString type

Initially, "" (empty string)
Type of the Event like click, haschange, submit, etc...

EventTarget *target

Initially nullptr
The Original EventTarget that triggered the event. It is reference to the object to which the event was originally dispatched.

EventTarget *srcElement is legacy support only for target. Only getter/setter methods are implemented for it.

Eventtarget *relatedTarget

Initially nullptr
For reference only, like storing the element the mouse came from or is going to !
Think of it like an extra toothbrush you might take for ur girlfriend :)

EventTarget *currentTarget

Initially nullptr
It's value is present only inside an event handler. Outside it, it will be null
It stores the element to which the event handler is currently pointing to.
Basically, it's null when dispatchEvent() is called from code, else when user interacts, it got an eventHandler and therefore, it's not null.

enum event_phase eventPhase

Initially, NONE (0)
Indicates which phase of the event flow is currently being evaluated.
Can be NONE, CAPTURING_PHASE, AT_TARGET or BUBBLING_PHASE.
Implemented using enum

bool bubbles

Indicates whether the event bubbles up the DOM tree or not.

bool cancelable

Indicates whether the event can be canceled, and therefore prevented as if the event never happened.
If the event is not cancelable, then its cancelable property will be false and the event listener cannot stop the event from occurring.

bool composed

Indicates whether or not the event will propagate across the shadow DOM boundary into the standard DOM.
In layman terms, whether while creating path, will it go inside the shadow DOM or not ! Know more about shadow DOM in shadow.md.

bool isTrusted

It is true when the event was generated by the user agent (including via user actions and programmatic methods such as HTMLElement.focus()), and false when the event was dispatched via EventTarget.dispatchEvent(). The only exception is the click event, which initializes the isTrusted property to false in user agents.

DOMHighResTimeStamp timeStamp

Stores the time at which Event was created.
You can get the string representation using ctime() function from ctime library

bool defaultPrevented is legacy only and is implemented as a getter function for cancelable value. The defaultPrevented read-only property of the Event interface returns a boolean value indicating whether or not the call to Event.preventDefault() canceled the event.

Editable Values

bool returnValue is legacy only and is implemented as a special getter/setter function for cancelable value. It returns whether default action for this event has been cancelled or not. Basically returning negation of canceled flag

std::vector<std::unique_ptr<path_structs>> path

Default Empty {}
The path where the elements will be stored in propagation from the element invoked till the top of document.

std::vector<EventTarget> touch_target_list = {}

Reserved for TouchEvent interface

Methods

std::vector<EventTarget*> composedPath()

Returns the event's path (an array of objects on which listeners will be invoked). This does not include nodes in shadow trees if the shadow root was created with its ShadowRoot.mode closed

void stopPropagation() inline

Just setting the stop_propagation_flag
Stops the propagation of events further along in the DOM
Prevents further propagation of the current event in the capturing and bubbling phases. It also does not prevent propagation to other event-handlers of the current element.

void stopImmediatePropagation() inline

Just setting the stop_propagation_flag and stop_immediate_propagation_flag
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).
If several listeners are attached to the same element for the same event type, they are called in the order in which they were added. If stopImmediatePropagation() is invoked during one such call, no remaining listeners will be called, either on that element or any other element.

void preventDefault()

Tells the browser not to perform the default action associated with the event.
Sets the canceled flag to true if cancelable attribute value is true and in_passive_listener_flag is not set (false).
The preventDefault() method of the Event interface tells the user agent that if the event does not get explicitly handled, its default action should not be taken as it normally would be.
The event continues to propagate as usual, unless one of its event listeners calls stopPropagation() or stopImmediatePropagation(), either of which terminates propagation at once.
As noted below, calling preventDefault() for a non-cancelable event, such as one dispatched via EventTarget.dispatchEvent(), without specifying cancelable: true has no effect.
If a passive listener calls preventDefault(), nothing will happen and a console warning may be generated.

void initEvent(DOMString &type, bool bubbles = false, bool cancelable = false)

Legacy baby
Initializes the value of an Event created. If the event has already been dispatched, this method does nothing. Use the constructor (Event() instead).

void set_canceled_flag() inline

Not in documentation
It just checks if canceled is true and in_passive_listener_flag is false, and then sets the canceled_flag to true.

Event(const DOMString &type, bool bubbles = false, bool cancelable = false, bool composed = false)

Initializes the event
Sets type for the Event
Calls inner_event_creation_steps with current time

Event::Event(const Event* temp)

Copy constructor baby
Copied values: bubbles,cancelable,composed,type

void inner_event_creation_steps(const Event* event, const Realm* realm, const DOMHighResTimeStamp &time, bool bubbles = false, bool cancelable = false, bool composed = false)

Just sets the initialized_flag & all the values passed.

Concept for shadow DOM

So, this was actually so confusing for me and that's why I am explaining this all. So when any event handler is attached and whenever event is provoked using user interaction or dispatchEvent(), this all happens.

First path is created starting from the element that had the event started and going to the top of the DOM. Then the composedPath() method does further processing when called. There can be different cases here !
1) The element is outside a shadow tree, then it just goes from that element to the top which could be Document or window. 2) The element is inside a shadow tree. It also has 4 cases:- 1) Shadow tree is closed and composed in event is true, then the path includes the shadow root to the top. The hierarchy inside the shadow tree isn't included. 2) Shadow tree is closed and composed in event is false, path just contains the shadow root. 3) Shadow tree is open and composed in event is true, then the path has the full order from the element invoked to the top including shadow tree hierarchy. 4) Shadow tree is open and composed in event is false, then the path has elements from the element invoked till the shadow root.

It also removes the shadow roots !

This is how the path for the current event is calculated. Furthermore, the composePath() method works on this path to have the shadow roots removed and also not including the shadow DOM notes if its mode is closed.

CustomEvent

It's a derived class of Event with an extra detail attribute to store information.

Read-only Attributes

std::any detail

Initially nullptr
Could be anything
From the any lib

Methods

CustomEvent(DOMString const &type, bool bubbles = false, bool cancelable = false, bool composed = false, std::any &detail = nullptr)

Just setting the detail attribute & calling the Event constructor

void initCustomEvent(DOMString const &type, bool bubbles = false, bool cancelable = false, std::any &detail = nullptr)

Just sets the detail attribute & calls the initEvent() method.
Legacy too

CustomEvent(const CustomEvent* temp)

Copy constructor
Copied values: detail,

Refer copy constructor for Event for other values copied.

EventTarget

It's the base class for anything inside of the DOM like nodes, document, elements, etc... It sets the base layer so that event listeners can be added and also events can easily propagate through the multiple EventTargets.