CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Class

MarkerCollection (engine/model)

@ckeditor/ckeditor5-engine/src/model/markercollection

class
See source

The collection of all markers attached to the document. It lets you get markers or track them using event-update event.

To create, change or remove makers use model writers' methods: addMarker or removeMarker. Since the writer is the only proper way to change the data model it is not possible to change markers directly using this collection. All markers created by the writer will be automatically added to this collection.

By default there is one marker collection available as model property.

Filtering

Properties

Methods

  • inherited

    constructor()

    See source

  • Symbol.iterator() → IterableIterator<Marker>

    See source

    Iterable interface.

    Iterates over all markers added to the collection.

    Returns

    IterableIterator<Marker>

  • 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

  • destroy() → void

    See source

    Destroys marker collection and all markers inside it.

    Returns

    void

  • inherited

    fire( eventOrInfo, args ) → GetEventInfo<TEvent>[ 'return' ]

    See source

    Fires an event, executing all callbacks registered for it.

    The first parameter passed to callbacks is an EventInfo object, followed by the optional args provided in the fire() method call.

    Type parameters

    TEvent : extends BaseEvent

    The type describing the event. See BaseEvent.

    Parameters

    eventOrInfo : GetNameOrEventInfo<TEvent>

    The name of the event or EventInfo object if event is delegated.

    args : TEvent[ 'args' ]

    Additional arguments to be passed to the callbacks.

    Returns

    GetEventInfo<TEvent>[ 'return' ]

    By default the method returns undefined. However, the return value can be changed by listeners through modification of the evt.return's property (the event info is the first param of every callback).

  • get( markerName ) → null | Marker

    See source

    Returns marker with given markerName.

    Parameters

    markerName : string

    Name of marker to get.

    Returns

    null | Marker

    Marker with given name or null if such marker was not added to the collection.

  • getMarkersAtPosition( position ) → IterableIterator<Marker>

    See source

    Returns iterator that iterates over all markers, which ranges contain given position.

    Parameters

    position : Position

    Returns

    IterableIterator<Marker>

  • getMarkersGroup( prefix ) → IterableIterator<Marker>

    See source

    Iterates over all markers that starts with given prefix.

    const markerFooA = markersCollection._set( 'foo:a', rangeFooA );
const markerFooB = markersCollection._set( 'foo:b', rangeFooB );
const markerBarA = markersCollection._set( 'bar:a', rangeBarA );
const markerFooBarA = markersCollection._set( 'foobar:a', rangeFooBarA );
Array.from( markersCollection.getMarkersGroup( 'foo' ) ); // [ markerFooA, markerFooB ]
Array.from( markersCollection.getMarkersGroup( 'a' ) ); // []

    Parameters

    prefix : string

    Returns

    IterableIterator<Marker>

  • getMarkersIntersectingRange( range ) → Iterable<Marker>

    See source

    Returns iterator that iterates over all markers, which intersects with given range.

    Parameters

    range : Range

    Returns

    Iterable<Marker>

  • has( markerOrName ) → boolean

    See source

    Checks if given marker or marker name is in the collection.

    Parameters

    markerOrName : string | Marker

    Name of marker or marker instance to check.

    Returns

    boolean

    true if marker is in the collection, false otherwise.

  • 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 ] : GetCallbackOptions<TEvent>

    Additional options.

    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

  • 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:

    • 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 ] : 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

  • internal

    _refresh( markerOrName ) → void

    See source

    Fires an event-update event for the given marker but does not change the marker. Useful to force downcast conversion for the marker.

    Parameters

    markerOrName : string | Marker

    Marker or name of a marker to refresh.

    Returns

    void

    Fires

  • internal

    _remove( markerOrName ) → boolean

    See source

    Removes given marker or a marker with given name from the MarkerCollection.

    Parameters

    markerOrName : string | Marker

    Marker or name of a marker to remove.

    Returns

    boolean

    true if marker was found and removed, false otherwise.

    Fires

  • internal

    _set( markerOrName, range, managedUsingOperations, affectsData ) → Marker

    See source

    Creates and adds a marker to the MarkerCollection with given name on given range.

    If MarkerCollection already had a marker with given name (or marker was passed), the marker in collection is updated and event-update event is fired but only if there was a change (marker range or managedUsingOperations flag has changed.

    Parameters

    markerOrName : string | Marker

    Name of marker to set or marker instance to update.

    range : Range

    Marker range.

    managedUsingOperations : boolean

    Specifies whether the marker is managed using operations.

    Defaults to false

    affectsData : boolean

    Specifies whether the marker affects the data produced by the data pipeline (is persisted in the editor's data).

    Defaults to false

    Returns

    Marker

    Marker instance which was added or updated.

    Fires

  • private

    _destroyMarker( marker ) → void

    See source

    Destroys the marker.

    Parameters

    marker : Marker

    Returns

    void

Events

  • update( eventInfo, marker, oldRange, newRange, oldMarkerData )

    See source

    Fired whenever marker is added, updated or removed from MarkerCollection.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    marker : Marker

    Updated Marker.

    oldRange : Range | null

    Marker range before the update. When is not defined it means that marker is just added.

    newRange : Range | null

    Marker range after update. When is not defined it means that marker is just removed.

    oldMarkerData : MarkerData

    Data of the marker before the change.