CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Class

DocumentSelection (engine/model)

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

class
See source

DocumentSelection is a special selection which is used as the document's selection. There can be only one instance of DocumentSelection per document.

Document selection can only be changed by using the Writer instance inside the change() block, as it provides a secure way to modify model.

DocumentSelection is automatically updated upon changes in the document to always contain valid ranges. Its attributes are inherited from the text unless set explicitly.

Differences between Selection and DocumentSelection are:

  • there is always a range in DocumentSelection - even if no ranges were added there is a "default range" present in the selection,
  • ranges added to this selection updates automatically when the document changes,
  • attributes of DocumentSelection are updated automatically according to selection ranges.

Since DocumentSelection uses live ranges and is updated when document changes, it cannot be set on nodes that are inside document fragment. If you need to represent a selection in document fragment, use Selection class instead.

Filtering

Properties

  • readonly

    anchor : null | Position

    See source

    Selection anchor. Anchor may be described as a position where the most recent part of the selection starts. Together with focus they define the direction of selection, which is important when expanding/shrinking selection. Anchor is always start or end position of the most recently added range.

    Is set to null if there are no ranges in selection.

  • readonly

    focus : null | Position

    See source

    Selection focus. Focus is a position where the selection ends.

    Is set to null if there are no ranges in selection.

  • readonly

    hasOwnRange : boolean

    See source

    Describes whether Documentselection has own range(s) set, or if it is defaulted to document's default range.

  • readonly

    isBackward : boolean

    See source

    Specifies whether the focus precedes anchor.

  • readonly

    isCollapsed : boolean

    See source

    Describes whether the selection is collapsed. Selection is collapsed when there is exactly one range which is collapsed.

  • readonly

    isGravityOverridden : boolean

    See source

    Describes whether the gravity is overridden (using overrideSelectionGravity) or not.

    Note that the gravity remains overridden as long as will not be restored the same number of times as it was overridden.

  • readonly

    markers : Collection<Marker>

    See source

    A collection of selection markers. Marker is a selection marker when selection range is inside the marker range.

    Note: Only markers from observed markers groups are collected.

  • readonly

    rangeCount : number

    See source

    Number of ranges in selection.

  • internal readonly

    _ranges : Array<Range>

    See source

    Used for the compatibility with the isEqual method.

  • private

    _selection : LiveSelection

    See source

    Selection used internally by that class (DocumentSelection is a proxy to that selection).

Methods

  • constructor( doc )

    See source

    Creates an empty live selection for given Document.

    Parameters

    doc : Document

    Document which owns this selection.

  • containsEntireContent( element ) → boolean

    See source

    Checks whether the selection contains the entire content of the given element. This means that selection must start at a position touching the element's start and ends at position touching the element's end.

    By default, this method will check whether the entire content of the selection's current root is selected. Useful to check if e.g. the user has just pressed Ctrl + A.

    Parameters

    element : Element

    Returns

    boolean

  • 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

    Unbinds all events previously bound by document selection.

    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).

  • getAttribute( key ) → unknown

    See source

    Gets an attribute value for given key or undefined if that attribute is not set on the selection.

    Parameters

    key : string

    Key of attribute to look for.

    Returns

    unknown

    Attribute value or undefined.

  • getAttributeKeys() → IterableIterator<string>

    See source

    Returns iterable that iterates over this selection's attribute keys.

    Returns

    IterableIterator<string>

  • getAttributes() → IterableIterator<tuple>

    See source

    Returns iterable that iterates over this selection's attributes.

    Attributes are returned as arrays containing two items. First one is attribute key and second is attribute value. This format is accepted by native Map object and also can be passed in Node constructor.

    Returns

    IterableIterator<tuple>

  • getFirstPosition() → null | Position

    See source

    Returns the first position in the selection. First position is the position that is before any other position in the selection.

    Returns null if there are no ranges in selection.

    Returns

    null | Position

  • getFirstRange() → null | Range

    See source

    Returns a copy of the first range in the selection. First range is the one which start position is before start position of all other ranges (not to confuse with the first range added to the selection).

    Returns null if there are no ranges in selection.

    Returns

    null | Range

  • getLastPosition() → null | Position

    See source

    Returns the last position in the selection. Last position is the position that is after any other position in the selection.

    Returns null if there are no ranges in selection.

    Returns

    null | Position

  • getLastRange() → null | Range

    See source

    Returns a copy of the last range in the selection. Last range is the one which end position is after end position of all other ranges (not to confuse with the range most recently added to the selection).

    Returns null if there are no ranges in selection.

    Returns

    null | Range

  • getRanges() → IterableIterator<Range>

    See source

    Returns an iterable that iterates over copies of selection ranges.

    Returns

    IterableIterator<Range>

  • getSelectedBlocks() → IterableIterator<Element>

    See source

    Gets elements of type "block" touched by the selection.

    This method's result can be used for example to apply block styling to all blocks covered by this selection.

    Note: getSelectedBlocks() returns blocks that are nested in other non-block elements but will not return blocks nested in other blocks.

    In this case the function will return exactly all 3 paragraphs (note: <blockQuote> is not a block itself):

    <paragraph>[a</paragraph>
<blockQuote>
	<paragraph>b</paragraph>
</blockQuote>
<paragraph>c]d</paragraph>

    In this case the paragraph will also be returned, despite the collapsed selection:

    <paragraph>[]a</paragraph>

    In such a scenario, however, only blocks A, B & E will be returned as blocks C & D are nested in block B:

    [<blockA></blockA>
<blockB>
	<blockC></blockC>
	<blockD></blockD>
</blockB>
<blockE></blockE>]

    If the selection is inside a block all the inner blocks (A & B) are returned:

    <block>
	<blockA>[a</blockA>
	<blockB>b]</blockB>
</block>

    Special case: If a selection ends at the beginning of a block, that block is not returned as from user perspective this block wasn't selected. See #984 for more details.

    <paragraph>[a</paragraph>
<paragraph>b</paragraph>
<paragraph>]c</paragraph> // this block will not be returned

    Returns

    IterableIterator<Element>

  • getSelectedElement() → null | Element

    See source

    Returns the selected element. Element is considered as selected if there is only one range in the selection, and that range contains exactly one element. Returns null if there is no selected element.

    Returns

    null | Element

  • hasAttribute( key ) → boolean

    See source

    Checks if the selection has an attribute for given key.

    Parameters

    key : string

    Key of attribute to check.

    Returns

    boolean

    true if attribute with given key is set on selection, false otherwise.

  • inherited

    is( type ) → this is Element | RootElement

    See source

    Checks whether the object is of type Element or its subclass.

    element.is( 'element' ); // -> true
element.is( 'node' ); // -> true
element.is( 'model:element' ); // -> true
element.is( 'model:node' ); // -> true

element.is( 'view:element' ); // -> false
element.is( 'documentSelection' ); // -> false

    Assuming that the object being checked is an element, you can also check its name:

    element.is( 'element', 'imageBlock' ); // -> true if this is an <imageBlock> element
text.is( 'element', 'imageBlock' ); -> false

    Parameters

    type : 'element' | 'model:element'

    Returns

    this is Element | RootElement

  • inherited

    is( type ) → this is Text

    See source

    Checks whether the object is of type Text.

    text.is( '$text' ); // -> true
text.is( 'node' ); // -> true
text.is( 'model:$text' ); // -> true
text.is( 'model:node' ); // -> true

text.is( 'view:$text' ); // -> false
text.is( 'documentSelection' ); // -> false

    Note: Until version 20.0.0 this method wasn't accepting '$text' type. The legacy 'text' type is still accepted for backward compatibility.

    Parameters

    type : '$text' | 'model:$text'

    Returns

    this is Text

  • inherited

    is( type ) → this is RootElement

    See source

    Checks whether the object is of type RootElement.

    rootElement.is( 'rootElement' ); // -> true
rootElement.is( 'element' ); // -> true
rootElement.is( 'node' ); // -> true
rootElement.is( 'model:rootElement' ); // -> true
rootElement.is( 'model:element' ); // -> true
rootElement.is( 'model:node' ); // -> true

rootElement.is( 'view:element' ); // -> false
rootElement.is( 'documentFragment' ); // -> false

    Assuming that the object being checked is an element, you can also check its name:

    rootElement.is( 'rootElement', '$root' ); // -> same as above

    Parameters

    type : 'rootElement' | 'model:rootElement'

    Returns

    this is RootElement

  • inherited

    is( type ) → this is LiveRange

    See source

    Checks whether the object is of type LiveRange.

    liveRange.is( 'range' ); // -> true
liveRange.is( 'model:range' ); // -> true
liveRange.is( 'liveRange' ); // -> true
liveRange.is( 'model:liveRange' ); // -> true

liveRange.is( 'view:range' ); // -> false
liveRange.is( 'documentSelection' ); // -> false

    Parameters

    type : 'liveRange' | 'model:liveRange'

    Returns

    this is LiveRange

  • inherited

    is( type ) → this is Range | LiveRange

    See source

    Checks whether the object is of type Range or its subclass.

    range.is( 'range' ); // -> true
range.is( 'model:range' ); // -> true

range.is( 'view:range' ); // -> false
range.is( 'documentSelection' ); // -> false

    Parameters

    type : 'range' | 'model:range'

    Returns

    this is Range | LiveRange

  • inherited

    is( type ) → this is LivePosition

    See source

    Checks whether the object is of type LivePosition.

    livePosition.is( 'position' ); // -> true
livePosition.is( 'model:position' ); // -> true
livePosition.is( 'liveposition' ); // -> true
livePosition.is( 'model:livePosition' ); // -> true

livePosition.is( 'view:position' ); // -> false
livePosition.is( 'documentSelection' ); // -> false

    Parameters

    type : 'livePosition' | 'model:livePosition'

    Returns

    this is LivePosition

  • inherited

    is( type ) → this is Position | LivePosition

    See source

    Checks whether the object is of type Position or its subclass.

    position.is( 'position' ); // -> true
position.is( 'model:position' ); // -> true

position.is( 'view:position' ); // -> false
position.is( 'documentSelection' ); // -> false

    Parameters

    type : 'position' | 'model:position'

    Returns

    this is Position | LivePosition

  • inherited

    is( type ) → this is Selection | DocumentSelection

    See source

    Checks whether the object is of type Selection or DocumentSelection.

    selection.is( 'selection' ); // -> true
selection.is( 'model:selection' ); // -> true

selection.is( 'view:selection' ); // -> false
selection.is( 'range' ); // -> false

    Parameters

    type : 'selection' | 'model:selection'

    Returns

    this is Selection | DocumentSelection

  • inherited

    is( type, name ) → boolean

    See source

    Checks whether the object is of type Element or its subclass and has the specified name.

    element.is( 'element', 'imageBlock' ); // -> true if this is an <imageBlock> element
text.is( 'element', 'imageBlock' ); -> false

    Type parameters

    N : extends string

    Parameters

    type : 'element' | 'model:element'
    name : N

    Returns

    boolean

  • inherited

    is( type, name ) → boolean

    See source

    Checks whether the object is of type RootElement and has the specified name.

    rootElement.is( 'rootElement', '$root' );

    Type parameters

    N : extends string

    Parameters

    type : 'rootElement' | 'model:rootElement'
    name : N

    Returns

    boolean

  • inherited

    is( type ) → this is TextProxy

    See source

    Checks whether the object is of type TextProxy.

    textProxy.is( '$textProxy' ); // -> true
textProxy.is( 'model:$textProxy' ); // -> true

textProxy.is( 'view:$textProxy' ); // -> false
textProxy.is( 'range' ); // -> false

    Note: Until version 20.0.0 this method wasn't accepting '$textProxy' type. The legacy 'textProxt' type is still accepted for backward compatibility.

    Parameters

    type : '$textProxy' | 'model:$textProxy'

    Returns

    this is TextProxy

  • inherited

    is( type ) → this is Marker

    See source

    Checks whether the object is of type Marker.

    marker.is( 'marker' ); // -> true
marker.is( 'model:marker' ); // -> true

marker.is( 'view:element' ); // -> false
marker.is( 'documentSelection' ); // -> false

    Parameters

    type : 'marker' | 'model:marker'

    Returns

    this is Marker

  • inherited

    is( type ) → this is DocumentSelection

    See source

    Checks whether the object is of type DocumentSelection.

    selection.is( 'selection' ); // -> true
selection.is( 'documentSelection' ); // -> true
selection.is( 'model:selection' ); // -> true
selection.is( 'model:documentSelection' ); // -> true

selection.is( 'view:selection' ); // -> false
selection.is( 'element' ); // -> false
selection.is( 'node' ); // -> false

    Parameters

    type : 'documentSelection' | 'model:documentSelection'

    Returns

    this is DocumentSelection

  • inherited

    is( type ) → this is DocumentFragment

    See source

    Checks whether the object is of type DocumentFragment.

    docFrag.is( 'documentFragment' ); // -> true
docFrag.is( 'model:documentFragment' ); // -> true

docFrag.is( 'view:documentFragment' ); // -> false
docFrag.is( 'element' ); // -> false
docFrag.is( 'node' ); // -> false

    Parameters

    type : 'documentFragment' | 'model:documentFragment'

    Returns

    this is DocumentFragment

  • inherited

    is( type ) → this is Node | Text | Element | RootElement

    See source

    Checks whether the object is of type Node or its subclass.

    This method is useful when processing model objects that are of unknown type. For example, a function may return a DocumentFragment or a Node that can be either a text node or an element. This method can be used to check what kind of object is returned.

    someObject.is( 'element' ); // -> true if this is an element
someObject.is( 'node' ); // -> true if this is a node (a text node or an element)
someObject.is( 'documentFragment' ); // -> true if this is a document fragment

    Since this method is also available on a range of view objects, you can prefix the type of the object with model: or view: to check, for example, if this is the model's or view's element:

    modelElement.is( 'model:element' ); // -> true
modelElement.is( 'view:element' ); // -> false

    By using this method it is also possible to check a name of an element:

    imageElement.is( 'element', 'imageBlock' ); // -> true
imageElement.is( 'element', 'imageBlock' ); // -> same as above
imageElement.is( 'model:element', 'imageBlock' ); // -> same as above, but more precise

    Parameters

    type : 'node' | 'model:node'

    Returns

    this is Node | Text | Element | RootElement

  • 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

  • observeMarkers( prefixOrName ) → void

    See source

    Registers a marker group prefix or a marker name to be collected in the selection markers collection.

    See also MarkerCollection#getMarkersGroup().

    Parameters

    prefixOrName : string

    The marker group prefix or marker name.

    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

  • refresh() → void

    See source

    Refreshes selection attributes and markers according to the current position in the model.

    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

    _getStoredAttributes() → Iterable<tuple>

    See source

    Returns an iterable that iterates through all selection attributes stored in current selection's parent.

    Returns

    Iterable<tuple>

  • internal

    _overrideGravity() → string

    See source

    Temporarily changes the gravity of the selection from the left to the right.

    The gravity defines from which direction the selection inherits its attributes. If it's the default left gravity, the selection (after being moved by the the user) inherits attributes from its left hand side. This method allows to temporarily override this behavior by forcing the gravity to the right.

    It returns an unique identifier which is required to restore the gravity. It guarantees the symmetry of the process.

    Returns

    string

    The unique id which allows restoring the gravity.

    Related:

  • internal

    _removeAttribute( key ) → void

    See source

    Removes an attribute with given key from the selection. If the given attribute was set on the selection, fires the event-change:range event with removed attribute key. Should be used only within the removeSelectionAttribute method.

    Parameters

    key : string

    Key of the attribute to remove.

    Returns

    void

    Related:

  • internal

    _restoreGravity( uid ) → void

    See source

    Restores the overridden gravity.

    Restoring the gravity is only possible using the unique identifier returned by _overrideGravity. Note that the gravity remains overridden as long as won't be restored the same number of times it was overridden.

    Parameters

    uid : string

    The unique id returned by _overrideGravity.

    Returns

    void

    Related:

  • internal

    _setAttribute( key, value ) → void

    See source

    Sets attribute on the selection. If attribute with the same key already is set, it's value is overwritten. Should be used only within the setSelectionAttribute method.

    Parameters

    key : string

    Key of the attribute to set.

    value : unknown

    Attribute value.

    Returns

    void

    Related:

  • internal

    _setFocus( itemOrPosition, [ offset ] ) → void

    See source

    Moves focus to the specified location. Should be used only within the setSelectionFocus method.

    The location can be specified in the same form as writer.createPositionAt() parameters.

    Parameters

    itemOrPosition : Position | Item
    [ offset ] : PositionOffset

    Offset or one of the flags. Used only when first parameter is a model item.

    Returns

    void

    Related:

  • internal

    _setTo( args ) → void

    See source

    Sets this selection's ranges and direction to the specified location based on the given selectable. Should be used only within the setSelection method.

    Parameters

    args : tuple

    Returns

    void

    Related:

Static methods

  • internal static

    _getStoreAttributeKey( key ) → string

    See source

    Generates and returns an attribute key for selection attributes store, basing on original attribute key.

    Parameters

    key : string

    Attribute key to convert.

    Returns

    string

    Converted attribute key, applicable for selection store.

  • internal static

    _isStoreAttributeKey( key ) → boolean

    See source

    Checks whether the given attribute key is an attribute stored on an element.

    Parameters

    key : string

    Returns

    boolean

Events

  • change( eventInfo, directChange = { [directChange.attributeKeys], directChange.directChange, [directChange.oldMarkers] } )

    See source

    Fired when selection range(s), attribute(s) or marker(s) changed.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    directChange : object

    This is always set to false in case of change:marker event as there is no possibility to change markers directly through DocumentSelection API. See also event-change:range and event-change:attribute.

    Properties
    [ directChange.attributeKeys ] : Array<string>
    directChange.directChange : boolean
    [ directChange.oldMarkers ] : Array<Marker>

  • change:attribute( eventInfo, directChange = { directChange.attributeKeys, directChange.directChange } )

    See source

    Fired when selection attribute changed.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    directChange : object

    In case of Selection class it is always set to true which indicates that the selection change was caused by a direct use of selection's API. The DocumentSelection, however, may change because its attributes were directly changed through the writer or because its position was changed in the model and its attributes were refreshed (which means an indirect change). The indirect change does not occur in case of normal (detached) selections because they are "static" (as "not live") which mean that they are not updated once the document changes.

    Properties
    directChange.attributeKeys : Array<string>
    directChange.directChange : boolean

  • change:marker( eventInfo, directChange = { directChange.directChange, directChange.oldMarkers } )

    See source

    Fired when selection marker(s) changed.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    directChange : object

    This is always set to false in case of change:marker event as there is no possibility to change markers directly through DocumentSelection API. See also event-change:range and event-change:attribute.

    Properties
    directChange.directChange : boolean
    directChange.oldMarkers : Array<Marker>

  • change:range( eventInfo, directChange = { directChange.directChange } )

    See source

    Fired when selection range(s) changed.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    directChange : object

    In case of Selection class it is always set to true which indicates that the selection change was caused by a direct use of selection's API. The DocumentSelection, however, may change because its position was directly changed through the writer or because its position was changed because the structure of the model has been changed (which means an indirect change). The indirect change does not occur in case of normal (detached) selections because they are "static" (as "not live") which mean that they are not updated once the document changes.

    Properties
    directChange.directChange : boolean