CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Class

DomEventObserver (engine/view/observer)

@ckeditor/ckeditor5-engine/src/view/observer/domeventobserver

class
See source

Base class for DOM event observers. This class handles adding listeners to DOM elements, disabling and re-enabling events. Child class needs to define DOM event type and callback.

For instance:

class ClickObserver extends DomEventObserver<'click'> {
	// It can also be defined as a normal property in the constructor.
	get domEventType(): 'click' {
		return 'click';
	}

	onDomEvent( domEvent: MouseEvent ): void {
		this.fire( 'click', domEvent );
	}
}

Filtering

Type parameters

  • EventType : extends keyof HTMLElementEventMap

    DOM Event type name or an union of those.

  • AdditionalData : extends object = object

    Additional data passed along with the event.

Properties

  • readonly inherited

    document : Document

    See source

    A reference to the Document object.

  • readonly

    domEventType : EventType | readonly Array<EventType>

    See source

    Type of the DOM event the observer should listen to. Array of types can be defined if the observer should listen to multiple DOM events.

  • readonly inherited

    isEnabled : boolean

    See source

    The state of the observer. If it is disabled, no events will be fired.

  • useCapture : boolean

    See source

    If set to true DOM events will be listened on the capturing phase. Default value is false.

  • usePassive : boolean

    See source

    If set to true, indicates that the function specified by listener will never call preventDefault(). Default value is false.

  • readonly inherited

    view : View

    See source

    An instance of the view controller.

Methods

  • inherited

    constructor( view )

    See source

    Creates an instance of the observer.

    Type parameters

    EventType : extends keyof HTMLElementEventMap
    AdditionalData : extends object = object

    Parameters

    view : View

  • inherited

    checkShouldIgnoreEventFromTarget( domTarget ) → boolean

    See source

    Checks whether a given DOM event should be ignored (should not be turned into a synthetic view document event).

    Currently, an event will be ignored only if its target or any of its ancestors has the data-cke-ignore-events attribute. This attribute can be used inside the structures generated by DowncastWriter#createUIElement() to ignore events fired within a UI that should be excluded from CKEditor 5's realms.

    Parameters

    domTarget : null | Node

    The DOM event target to check (usually an element, sometimes a text node and potentially sometimes a document, too).

    Returns

    boolean

    Whether this event should be ignored by the observer.

  • inherited

    delegate( events ) → EmitterMixinDelegateChain

    See source

    Delegates selected events to another Emitter. For instance:

    emitterA.delegate( 'eventX' ).to( emitterB );
emitterA.delegate( 'eventX', 'eventY' ).to( emitterC );

    then eventX is delegated (fired by) emitterB and emitterC along with data:

    emitterA.fire( 'eventX', data );

    and eventY is delegated (fired by) emitterC along with data:

    emitterA.fire( 'eventY', data );

    Parameters

    events : Array<string>

    Event names that will be delegated to another emitter.

    Returns

    EmitterMixinDelegateChain

  • inherited

    destroy() → void

    See source

    Disables and destroys the observer, among others removes event listeners created by the observer.

    Returns

    void

  • inherited

    disable() → void

    See source

    Disables the observer. This method is called before rendering to prevent firing events during rendering.

    Returns

    void

    Related:

  • inherited

    enable() → void

    See source

    Enables the observer. This method is called when the observer is registered to the View and after rendering (all observers are disabled before rendering).

    A typical use case for disabling observers is that mutation observers need to be disabled for the rendering. However, a child class may not need to be disabled, so it can implement an empty method.

    Returns

    void

    Related:

  • fire( eventType, domEvent, [ additionalData ] ) → void

    See source

    Calls Document#fire() if observer is enabled.

    Parameters

    eventType : string | EventInfo<string, unknown>

    The event type (name).

    domEvent : Event

    The DOM event.

    [ additionalData ] : AdditionalData

    The additional data which should extend the event data object.

    Returns

    void

    Related:

  • inherited

    listenTo( emitter, event, callback, [ options ] ) → void

    See source

    Registers a callback function to be executed when an event is fired in a specific (emitter) object.

    Events can be grouped in namespaces using :. When namespaced event is fired, it additionally fires all callbacks for that namespace.

    // myEmitter.on( ... ) is a shorthand for myEmitter.listenTo( myEmitter, ... ).
myEmitter.on( 'myGroup', genericCallback );
myEmitter.on( 'myGroup:myEvent', specificCallback );

// genericCallback is fired.
myEmitter.fire( 'myGroup' );
// both genericCallback and specificCallback are fired.
myEmitter.fire( 'myGroup:myEvent' );
// genericCallback is fired even though there are no callbacks for "foo".
myEmitter.fire( 'myGroup:foo' );

    An event callback can stop the event and set the return value of the fire method.

    Type parameters

    TEvent : extends BaseEvent

    The type describing the event. See BaseEvent.

    Parameters

    emitter : Emitter

    The object that fires the event.

    event : TEvent[ 'name' ]

    The name of the event.

    callback : GetCallback<TEvent>

    The function to be called on event.

    [ options ] : CallbackOptions

    Additional options.

    Returns

    void

  • inherited

    listenTo( emitter, event, callback, [ options ] ) → void

    See source

    Registers a callback function to be executed when an event is fired in a specific Emitter or DOM Node. It is backwards compatible with listenTo.

    Type parameters

    K : extends keyof DomEventMap

    Parameters

    emitter : Window | Node

    The object that fires the event.

    event : K

    The name of the event.

    callback : ( DomEventObserver<EventType, AdditionalData>, EventInfo<string, unknown>, DomEventMap[ K ] ) => void

    The function to be called on event.

    [ options ] : object

    Additional options.

    Returns

    void

  • observe( domElement ) → void

    See source

    Starts observing given DOM element.

    Parameters

    domElement : HTMLElement

    DOM element to observe.

    Returns

    void

  • inherited

    off( event, callback ) → void

    See source

    Stops executing the callback on the given event. Shorthand for this.stopListening( this, event, callback ).

    Parameters

    event : string

    The name of the event.

    callback : Function

    The function to stop being called.

    Returns

    void

  • inherited

    on( event, callback, [ options ] ) → void

    See source

    Registers a callback function to be executed when an event is fired.

    Shorthand for this.listenTo( this, event, callback, options ) (it makes the emitter listen on itself).

    Type parameters

    TEvent : extends BaseEvent

    The type descibing the event. See BaseEvent.

    Parameters

    event : TEvent[ 'name' ]

    The name of the event.

    callback : GetCallback<TEvent>

    The function to be called on event.

    [ options ] : GetCallbackOptions<TEvent>

    Additional options.

    Returns

    void

  • onDomEvent( event ) → void

    See source

    Callback which should be called when the DOM event occurred. Note that the callback will not be called if observer is not enabled.

    Parameters

    event : HTMLElementEventMap[ EventType ]

    Returns

    void

    Related:

  • inherited

    once( event, callback, [ options ] ) → void

    See source

    Registers a callback function to be executed on the next time the event is fired only. This is similar to calling on followed by off in the callback.

    Type parameters

    TEvent : extends BaseEvent

    The type descibing the event. See BaseEvent.

    Parameters

    event : TEvent[ 'name' ]

    The name of the event.

    callback : GetCallback<TEvent>

    The function to be called on event.

    [ options ] : GetCallbackOptions<TEvent>

    Additional options.

    Returns

    void

  • inherited

    stopDelegating( [ event ], [ emitter ] ) → void

    See source

    Stops delegating events. It can be used at different levels:

    • To stop delegating all events.
    • To stop delegating a specific event to all emitters.
    • To stop delegating a specific event to a specific emitter.

    Parameters

    [ event ] : string

    The name of the event to stop delegating. If omitted, stops it all delegations.

    [ emitter ] : Emitter

    (requires event) The object to stop delegating a particular event to. If omitted, stops delegation of event to all emitters.

    Returns

    void

  • inherited

    stopListening( [ emitter ], [ event ], [ callback ] ) → void

    See source

    Stops listening for events. It can be used at different levels: It is backwards compatible with listenTo.

    • To stop listening to a specific callback.
    • To stop listening to a specific event.
    • To stop listening to all events fired by a specific object.
    • To stop listening to all events fired by all objects.

    Parameters

    [ emitter ] : Window | Node | Emitter

    The object to stop listening to. If omitted, stops it for all objects.

    [ event ] : string

    (Requires the emitter) The name of the event to stop listening to. If omitted, stops it for all events from emitter.

    [ callback ] : Function

    (Requires the event) The function to be removed from the call list for the given event.

    Returns

    void

  • stopObserving( domElement ) → void

    See source

    Stops observing given DOM element.

    Parameters

    domElement : HTMLElement

    Returns

    void