Class Event
- Namespace
- CSharpToJavaScript.APIs.JS
- Assembly
- CSharpToJavaScript.dll
The Event interface represents an event which takes place on an EventTarget.
[Value("Event")]
public class Event- Inheritance
-
Event
- Derived
- Inherited Members
Remarks
An event can be triggered by the user action e.g., clicking the mouse button or tapping keyboard, or generated by APIs to represent the progress of an asynchronous task. It can also be triggered programmatically, such as by calling the HTMLElement.click() method of an element, or by defining the event, then sending it to a specified target using EventTarget.dispatchEvent().
There are many types of events, some of which use other interfaces based on the main Event interface. Event itself contains the properties and methods which are common to all events.
Many DOM elements can be set up to accept (or "listen" for) these events, and execute code in response to process (or "handle") them. Event-handlers are usually connected (or "attached") to various HTML elements (such as <button>, <div>, <span>, etc.) using EventTarget.addEventListener(), and this generally replaces using the old HTML event handler attributes. Further, when properly added, such handlers can also be disconnected if needed using removeEventListener().
NOTE
One element can have several such handlers, even for the exact same event—particularly if separate, independent code modules attach them, each for its own independent purposes. (For example, a webpage with an advertising-module and statistics-module both monitoring video-watching.)
When there are many nested elements, each with its own handler(s), event processing can become very complicated—especially where a parent element receives the very same event as its child elements because "spatially" they overlap so the event technically occurs in both, and the processing order of such events depends on the Event bubbling settings of each handler triggered.
-Event index
-Learn: Introduction to events
-Learn: Event bubbling
-Creating and triggering custom events
Constructors
Event()
public Event()Event(string, EventInit)
The Event() constructor creates a new 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.
public Event(string type, EventInit eventInitDict = null)Parameters
Remarks
Fields
AT_TARGET
[Value("AT_TARGET")]
public const ushort AT_TARGET = 2Field Value
BUBBLING_PHASE
[Value("BUBBLING_PHASE")]
public const ushort BUBBLING_PHASE = 3Field Value
CAPTURING_PHASE
[Value("CAPTURING_PHASE")]
public const ushort CAPTURING_PHASE = 1Field Value
NONE
[Value("NONE")]
public const ushort NONE = 0Field Value
Properties
Bubbles
The bubbles read-only property of the Event interface indicates whether the event bubbles up through the DOM tree or not.
[Value("bubbles")]
public bool Bubbles { get; }Property Value
- bool
A boolean value, which is
trueif the event bubbles up through the DOM tree.
Remarks
NOTE
See Event bubbling for more information on bubbling.
-StopPropagation() to prevent further propagation of the current event in the capturing and bubbling phases
-StopImmediatePropagation() to not call any further listeners for the same event at the same level in the DOM
-PreventDefault() to allow propagation to continue but to disallow the browser to perform its default action should no listeners handle the event
CancelBubble
IMPORTANT
DeprecatedcancelBubble property of the Eventinterface is deprecated. Use StopPropagation() instead.
Setting its value to
true before returning from an event handler prevents propagationof the event. In later implementations, setting this to
false does nothing.See Browser compatibility for details.
[Value("cancelBubble")]
public bool CancelBubble { get; set; }Property Value
- bool
A boolean value. The value
truemeans that the event must not be propagated further.
Remarks
Cancelable
The cancelable read-only property of the Event interface indicates whether the event
can be canceled, and therefore prevented as if the event never happened.
[Value("cancelable")]
public bool Cancelable { get; }Property Value
- bool
A boolean value, which is
trueif the event can be
canceled.
Remarks
If the event is not cancelable, then its cancelable property will befalse and the event listener cannot stop the event from occurring.
Most browser-native events that can be canceled are the ones that result from the user
interacting with the page. Canceling the Elementclick,
Elementwheel, or
Windowbeforeunload events would prevent the user
from clicking on something, scrolling the page with the mouse wheel, or
navigating away from the page, respectively.
Synthetic events created by other JavaScript
code define if they can be canceled when they are created.
To cancel an event, call the PreventDefault()
method on the event. This keeps the implementation from executing the default action
that is associated with the event.
Event listeners that handle multiple kinds of events may want to checkcancelable before invoking their PreventDefault() methods.
Composed
The read-only composed property of the
Event interface returns a boolean value which indicates whether
or not the event will propagate across the shadow DOM boundary into the standard DOM.
[Value("composed")]
public bool Composed { get; }Property Value
- bool
A boolean value which is
trueif the event will cross from the
shadow DOM into the standard DOM after reaching the shadow root. (That is, the first
node in the shadow DOM in which the event began to propagate.)If this value isfalse, the shadow root will be the last node to be
offered the event.
Remarks
All UA-dispatched UI events are composed (click/touch/mouseover/copy/paste, etc.). Most
other types of events are not composed, and so will return false. For
example, this includes synthetic events that are created without theircomposed option set to true.
Propagation only occurs if the Bubbles property is alsotrue. However, capturing only composed events are also handled at host as
if they were in AT_TARGET phase. You can determine the path the event will
follow through the shadow root to the DOM root by calling
ComposedPath().
CurrentTarget
The currentTarget read-only property of the Event interface identifies the element to which the event handler has been attached.
[Value("currentTarget")]
public EventTarget? CurrentTarget { get; }Property Value
- EventTarget
An EventTarget representing the object to which the current event handler is attached.
Remarks
This will not always be the same as the element on which the event was fired, because the event may have fired on a descendant of the element with the handler, and then bubbled up to the element with the handler. The element on which the event was fired is given by Target.
Note that the value of currentTarget is only available in a handler for the event. Outside an event handler it will be null. This means that, for example, if you take a reference to the Event object inside an event handler and then access its currentTarget property outside the event handler, its value will be null.
DefaultPrevented
The defaultPrevented read-only property of the Event interface returns a boolean value indicating whether or not the call to PreventDefault() canceled the event.
[Value("defaultPrevented")]
public bool DefaultPrevented { get; }Property Value
- bool
A boolean value, where
trueindicates that the default user agent action was prevented, andfalseindicates that it was not.
Remarks
EventPhase
The eventPhase read-only property of the
Event interface indicates which phase of the event flow is currently
being evaluated.
[Value("eventPhase")]
public ushort EventPhase { get; }Property Value
- ushort
Returns an integer value which specifies the current evaluation phase of the event
flow. Possible values are:
Remarks
IsTrusted
The isTrusted read-only property of the
Event interface is a boolean value that 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
DispatchEvent(Event).
The only exception is the click event, which initializes the isTrusted
property to false in user agents.
[Value("isTrusted")]
public bool IsTrusted { get; }Property Value
- bool
A boolean value.
Remarks
ReturnValue
IMPORTANT
DeprecatedreturnValue indicates whether the default action forthis event has been prevented or not.
[Value("returnValue")]
public bool ReturnValue { get; set; }Property Value
- bool
A boolean value which is
trueif the event has not been
canceled; otherwise, if the event has been canceled or the default has been prevented,
the value isfalse.The value ofreturnValueis the opposite of the value returned by
DefaultPrevented.
Remarks
It is set to true by
default, allowing the default action to occur. Setting this property tofalse prevents the default action.
NOTE
While
returnValuehas been adopted into the DOM
standard, it is present primarily to support existing code. Use
PreventDefault(), and
DefaultPrevented instead of this historical
property.
-ReturnValue: the return value for the {{HTMLElement("dialog")}}.
SrcElement
IMPORTANT
DeprecatedEvent.srcElement is an alias for the Target property. Use Target instead.
[Value("srcElement")]
public EventTarget? SrcElement { get; }Property Value
Remarks
Target
The read-only target property of the
Event interface is a reference to the object onto which the event was
dispatched. It is different from CurrentTarget when the event
handler is called during the bubbling or capturing phase of the event.
[Value("target")]
public EventTarget? Target { get; }Property Value
- EventTarget
The associated EventTarget.
Remarks
TimeStamp
The timeStamp read-only property of the Event interface returns the time (in milliseconds) at which the event was created.
[Value("timeStamp")]
public Number TimeStamp { get; }Property Value
- Number
This value is the number of milliseconds elapsed from the beginning of the time origin until the event was created.
If the global object is Window, the time origin is the moment the user clicked on the link, or the script that initiated the loading of the document.
In a worker, the time origin is the moment of creation of the worker.The value is a Number accurate to 5 microseconds (0.005 ms), but the precision is reduced to prevent fingerprinting.
Remarks
Type
The type read-only property of the Event
interface returns a string containing the event's type. It is set when the event is
constructed and is the name commonly used to refer to the specific event, such asclick, load, or error.
[Value("type")]
public string Type { get; }Property Value
Remarks
Methods
ComposedPath()
The composedPath() method of the Event
interface returns the event's path which is an array of the objects on which listeners
will be invoked. This does not include nodes in shadow trees if the shadow root was
created with its Mode closed.
[Value("composedPath")]
public List<EventTarget> ComposedPath()Returns
- List<EventTarget>
An array of EventTarget objects representing the objects on which an
event listener will be invoked.
Remarks
InitEvent(string, bool, bool)
IMPORTANT
DeprecatedEvent.initEvent() method is used to initialize thevalue of an Event created using CreateEvent(string).
[Value("initEvent")]
public GlobalObject.Undefined InitEvent(string type, bool bubbles = false, bool cancelable = false)Parameters
Returns
- GlobalObject.Undefined
None.
Remarks
Events initialized in this way must have been created with the
CreateEvent(string) method.
This method must be called to set the event
before it is dispatched, using DispatchEvent(Event).
Once dispatched, it doesn't do anything anymore.
NOTE
Do not use this method anymore as it is deprecated.
Instead use specific event constructors, like Event(string, EventInit).
The section on Creating and dispatching events gives more information about the way to use these.
-The constructor to use instead of this deprecated method:
Event(string, EventInit). To create more specific event interfaces than Event, use the constructor defined for the desired event interface.
PreventDefault()
The preventDefault() method of the Event interface tells the {{Glossary("user agent")}} that the event is being explicitly handled, so its default action, such as page scrolling, link navigation, or pasting text, should not be taken.
[Value("preventDefault")]
public GlobalObject.Undefined PreventDefault()Returns
Remarks
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
DispatchEvent(Event), without specifyingcancelable: true has no effect.
If a passive listener calls preventDefault(), nothing will happen and a console warning may be generated.
NOTE
Look for better alternatives than using
preventDefault()to block default actions. For example, you can use thedisabledorreadonlyattribute on a form control to prevent it from being interacted with, use HTML constraint validation to reject invalid input, or use the overflow property to prevent scrolling.
StopImmediatePropagation()
The stopImmediatePropagation() method of the
Event interface prevents other listeners of the same event from being called.
[Value("stopImmediatePropagation")]
public GlobalObject.Undefined StopImmediatePropagation()Returns
Remarks
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.
StopPropagation()
The stopPropagation() method of the Event
interface prevents further propagation of the current event in the capturing and
bubbling phases. It does not, however, prevent any default behaviors from occurring; for
instance, clicks on links are still processed. If you want to stop those behaviors, see
the PreventDefault() method. It also does not
prevent propagation to other event-handlers of the current element. If you want to stop those,
see StopImmediatePropagation().
[Value("stopPropagation")]
public GlobalObject.Undefined StopPropagation()Returns
- GlobalObject.Undefined
None.