CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Class

DocumentSelection (engine/view)

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

class
See source

Class representing the document selection in the view.

Its instance is available in Document#selection.

It is similar to Selection but it has a read-only API and can be modified only by the writer available in the View#change() block (so via DowncastWriter#setSelection()).

Filtering

Properties

  • readonly

    anchor : null | Position

    See source

    Selection anchor. Anchor may be described as a position where the selection starts. Together with focus they define the direction of selection, which is important when expanding/shrinking selection. Anchor is always the start or end of the most recent added range. It may be a bit unintuitive when there are multiple ranges in selection.

  • readonly

    editableElement : null | EditableElement

    See source

    EditableElement instance that contains this selection, or null if the selection is not inside an editable element.

  • readonly

    fakeSelectionLabel : string

    See source

    Returns fake selection label.

  • readonly

    focus : null | Position

    See source

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

  • readonly

    isBackward : boolean

    See source

    Specifies whether the focus precedes anchor.

  • readonly

    isCollapsed : boolean

    See source

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

  • readonly

    isFake : boolean

    See source

    Returns true if selection instance is marked as fake.

  • readonly

    rangeCount : number

    See source

    Returns number of ranges in selection.

  • internal readonly

    _ranges : Array<Range>

    See source

    Used for the compatibility with the isEqual method.

  • private readonly

    _selection : Selection

    See source

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

Methods

  • constructor( [ selectable ], [ options ] )

    See source

    Creates new DocumentSelection instance.

    // Creates empty selection without ranges.
const selection = new DocumentSelection();

// Creates selection at the given range.
const range = writer.createRange( start, end );
const selection = new DocumentSelection( range );

// Creates selection at the given ranges
const ranges = [ writer.createRange( start1, end2 ), writer.createRange( start2, end2 ) ];
const selection = new DocumentSelection( ranges );

// Creates selection from the other selection.
const otherSelection = writer.createSelection();
const selection = new DocumentSelection( otherSelection );

// Creates selection at the given position.
const position = writer.createPositionAt( root, offset );
const selection = new DocumentSelection( position );

    Selection's constructor allow passing additional options (backward, fake and label) as the last argument.

    // Creates backward selection.
const selection = new DocumentSelection( range, { backward: true } );

    Fake selection does not render as browser native selection over selected elements and is hidden to the user. This way, no native selection UI artifacts are displayed to the user and selection over elements can be represented in other way, for example by applying proper CSS class.

    Additionally fake's selection label can be provided. It will be used to describe fake selection in DOM (and be properly handled by screen readers).

    // Creates fake selection with label.
const selection = new DocumentSelection( range, { fake: true, label: 'foo' } );

    See also: constructor( node, placeOrOffset, options ).

    Parameters

    [ selectable ] : null | Position | Range | Selection | DocumentSelection | Iterable<Range>
    [ options ] : SelectionOptions

  • constructor( selectable, placeOrOffset, [ options ] )

    See source

    Creates new DocumentSelection instance.

    // Creates collapsed selection at the position of given item and offset.
const paragraph = writer.createContainerElement( 'paragraph' );
const selection = new DocumentSelection( paragraph, offset );

// Creates a range inside an element which starts before the
// first child of that element and ends after the last child of that element.
const selection = new DocumentSelection( paragraph, 'in' );

// Creates a range on an item which starts before the item and ends
// just after the item.
const selection = new DocumentSelection( paragraph, 'on' );

    Selection's constructor allow passing additional options (backward, fake and label) as the last argument.

    // Creates backward selection.
const selection = new DocumentSelection( element, 'in', { backward: true } );

    Fake selection does not render as browser native selection over selected elements and is hidden to the user. This way, no native selection UI artifacts are displayed to the user and selection over elements can be represented in other way, for example by applying proper CSS class.

    Additionally fake's selection label can be provided. It will be used to describe fake selection in DOM (and be properly handled by screen readers).

    // Creates fake selection with label.
const selection = new DocumentSelection( element, 'in', { fake: true, label: 'foo' } );

    See also: constructor( selectable, options ).

    Parameters

    selectable : Node
    placeOrOffset : PlaceOrOffset
    [ options ] : SelectionOptions

  • 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

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

  • getFirstPosition() → null | Position

    See source

    Returns copy of the first position in the selection. First position is the position that is before any other position in the selection ranges. Returns null if no ranges are added to selection.

    Returns

    null | Position

  • getFirstRange() → null | Range

    See source

    Returns 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 no ranges are added to selection.

    Returns

    null | Range

  • getLastPosition() → null | Position

    See source

    Returns copy of the last position in the selection. Last position is the position that is after any other position in the selection ranges. Returns null if no ranges are added to selection.

    Returns

    null | Position

  • getLastRange() → null | Range

    See source

    Returns 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 last range added to the selection). Returns null if no ranges are added to selection.

    Returns

    null | Range

  • getRanges() → IterableIterator<Range>

    See source

    Returns an iterable that contains copies of all ranges added to the selection.

    Returns

    IterableIterator<Range>

  • 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

  • inherited

    is( type ) → this is Element | AttributeElement | ContainerElement | EditableElement | EmptyElement | RawElement | RootEditableElement | UIElement

    See source

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

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

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

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

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

    Parameters

    type : 'element' | 'view:element'

    Returns

    this is Element | AttributeElement | ContainerElement | EditableElement | EmptyElement | RawElement | RootEditableElement | UIElement

  • inherited

    is( type ) → this is ContainerElement | EditableElement | RootEditableElement

    See source

    Checks whether this object is of type ContainerElement or its subclass.

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

containerElement.is( 'model:element' ); // -> false
containerElement.is( 'documentFragment' ); // -> false

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

    containerElement.is( 'element', 'div' ); // -> true if this is a div container element
containerElement.is( 'contaienrElement', 'div' ); // -> same as above
text.is( 'element', 'div' ); -> false

    Parameters

    type : 'containerElement' | 'view:containerElement'

    Returns

    this is ContainerElement | EditableElement | RootEditableElement

  • inherited

    is( type ) → this is AttributeElement

    See source

    Checks whether this object is of type AttributeElement.

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

attributeElement.is( 'model:element' ); // -> false
attributeElement.is( 'documentFragment' ); // -> false

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

    attributeElement.is( 'element', 'b' ); // -> true if this is a bold element
attributeElement.is( 'attributeElement', 'b' ); // -> same as above
text.is( 'element', 'b' ); -> false

    Parameters

    type : 'attributeElement' | 'view:attributeElement'

    Returns

    this is AttributeElement

  • inherited

    is( type ) → this is EditableElement | RootEditableElement

    See source

    Checks whether this object is of type EditableElement or its subclass.

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

editableElement.is( 'model:element' ); // -> false
editableElement.is( 'documentFragment' ); // -> false

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

    editableElement.is( 'element', 'div' ); // -> true if this is a div element
editableElement.is( 'editableElement', 'div' ); // -> same as above
text.is( 'element', 'div' ); -> false

    Parameters

    type : 'editableElement' | 'view:editableElement'

    Returns

    this is EditableElement | RootEditableElement

  • inherited

    is( type ) → this is UIElement

    See source

    Checks whether this object is of type UIElement.

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

uiElement.is( 'model:element' ); // -> false
uiElement.is( 'documentFragment' ); // -> false

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

    uiElement.is( 'element', 'span' ); // -> true if this is a span ui element
uiElement.is( 'uiElement', 'span' ); // -> same as above
text.is( 'element', 'span' ); -> false

    Parameters

    type : 'uiElement' | 'view:uiElement'

    Returns

    this is UIElement

  • inherited

    is( type ) → this is TextProxy

    See source

    Checks whether this object is of type TextProxy.

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

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

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

    Parameters

    type : '$textProxy' | 'view:$textProxy'

    Returns

    this is TextProxy

  • inherited

    is( type ) → this is DocumentFragment

    See source

    hecks whether this object is of type DocumentFragment.

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

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

    Parameters

    type : 'documentFragment' | 'view:documentFragment'

    Returns

    this is DocumentFragment

  • inherited

    is( type ) → this is Text

    See source

    Checks whether this object is of type Text.

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

text.is( 'model:$text' ); // -> false
text.is( 'element' ); // -> false
text.is( 'range' ); // -> false

    Parameters

    type : '$text' | 'view:$text'

    Returns

    this is Text

  • inherited

    is( type ) → this is RootEditableElement

    See source

    Checks whether this object is of type RootEditableElement.

    rootEditableElement.is( 'rootElement' ); // -> true
rootEditableElement.is( 'editableElement' ); // -> true
rootEditableElement.is( 'element' ); // -> true
rootEditableElement.is( 'node' ); // -> true
rootEditableElement.is( 'view:editableElement' ); // -> true
rootEditableElement.is( 'view:element' ); // -> true
rootEditableElement.is( 'view:node' ); // -> true

rootEditableElement.is( 'model:element' ); // -> false
rootEditableElement.is( 'documentFragment' ); // -> false

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

    rootEditableElement.is( 'element', 'div' ); // -> true if this is a div root editable element
rootEditableElement.is( 'rootElement', 'div' ); // -> same as above
text.is( 'element', 'div' ); -> false

    Parameters

    type : 'rootElement' | 'view:rootElement'

    Returns

    this is RootEditableElement

  • inherited

    is( type ) → this is RawElement

    See source

    Checks whether this object is of type RawElement.

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

rawElement.is( 'model:element' ); // -> false
rawElement.is( 'documentFragment' ); // -> false

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

    rawElement.is( 'img' ); // -> true if this is an img element
rawElement.is( 'rawElement', 'img' ); // -> same as above
text.is( 'img' ); -> false

    Parameters

    type : 'rawElement' | 'view:rawElement'

    Returns

    this is RawElement

  • inherited

    is( type ) → this is EmptyElement

    See source

    Checks whether this object is of type EmptyElement.

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

emptyElement.is( 'model:element' ); // -> false
emptyElement.is( 'documentFragment' ); // -> false

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

    emptyElement.is( 'element', 'img' ); // -> true if this is a img element
emptyElement.is( 'emptyElement', 'img' ); // -> same as above
text.is( 'element', 'img' ); -> false

    Parameters

    type : 'emptyElement' | 'view:emptyElement'

    Returns

    this is EmptyElement

  • inherited

    is( type ) → this is Position

    See source

    Checks whether this object is of type Position.

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

position.is( 'model:position' ); // -> false
position.is( 'element' ); // -> false
position.is( 'range' ); // -> false

    Parameters

    type : 'position' | 'view:position'

    Returns

    this is Position

  • inherited

    is( type ) → this is Selection | DocumentSelection

    See source

    Checks whether this object is of type Selection or DocumentSelection.

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

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

    Parameters

    type : 'selection' | 'view: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.

    Type parameters

    N : extends string

    Parameters

    type : 'element' | 'view:element'
    name : N

    Returns

    boolean

  • inherited

    is( type, name ) → boolean

    See source

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

    Type parameters

    N : extends string

    Parameters

    type : 'containerElement' | 'view:containerElement'
    name : N

    Returns

    boolean

  • inherited

    is( type, name ) → boolean

    See source

    Checks whether the object is of type EmptyElement has the specified name.

    Type parameters

    N : extends string

    Parameters

    type : 'emptyElement' | 'view:emptyElement'
    name : N

    Returns

    boolean

  • inherited

    is( type, name ) → boolean

    See source

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

    Type parameters

    N : extends string

    Parameters

    type : 'rootElement' | 'view:rootElement'
    name : N

    Returns

    boolean

  • inherited

    is( type, name ) → boolean

    See source

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

    Type parameters

    N : extends string

    Parameters

    type : 'uiElement' | 'view:uiElement'
    name : N

    Returns

    boolean

  • inherited

    is( type, name ) → boolean

    See source

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

    Type parameters

    N : extends string

    Parameters

    type : 'rawElement' | 'view:rawElement'
    name : N

    Returns

    boolean

  • inherited

    is( type, name ) → boolean

    See source

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

    Type parameters

    N : extends string

    Parameters

    type : 'editableElement' | 'view:editableElement'
    name : N

    Returns

    boolean

  • inherited

    is( type, name ) → boolean

    See source

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

    Type parameters

    N : extends string

    Parameters

    type : 'attributeElement' | 'view:attributeElement'
    name : N

    Returns

    boolean

  • inherited

    is( type ) → this is DocumentSelection

    See source

    Checks whether this object is of type DocumentSelection.

    `docSelection.is( 'selection' ); // -> true
docSelection.is( 'documentSelection' ); // -> true
docSelection.is( 'view:selection' ); // -> true
docSelection.is( 'view:documentSelection' ); // -> true

docSelection.is( 'model:documentSelection' ); // -> false
docSelection.is( 'element' ); // -> false
docSelection.is( 'node' ); // -> false

    Parameters

    type : 'documentSelection' | 'view:documentSelection'

    Returns

    this is DocumentSelection

  • inherited

    is( type ) → this is Range

    See source

    Checks whether this object is of type Range.

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

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

    Parameters

    type : 'range' | 'view:range'

    Returns

    this is Range

  • inherited

    is( type ) → this is Text | Node | Element | AttributeElement | ContainerElement | EditableElement | EmptyElement | RawElement | RootEditableElement | UIElement

    See source

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

    This method is useful when processing view 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 model 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:

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

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

    imgElement.is( 'element', 'img' ); // -> true
imgElement.is( 'view:element', 'img' ); // -> same as above, but more precise

    Parameters

    type : 'node' | 'view:node'

    Returns

    this is Text | Node | Element | AttributeElement | ContainerElement | EditableElement | EmptyElement | RawElement | RootEditableElement | UIElement

  • isEqual( otherSelection ) → boolean

    See source

    Checks whether, this selection is equal to given selection. Selections are equal if they have same directions, same number of ranges and all ranges from one selection equal to a range from other selection.

    Parameters

    otherSelection : Selection | DocumentSelection

    Selection to compare with.

    Returns

    boolean

    true if selections are equal, false otherwise.

  • isSimilar( otherSelection ) → boolean

    See source

    Checks whether this selection is similar to given selection. Selections are similar if they have same directions, same number of ranges, and all trimmed ranges from one selection are equal to any trimmed range from other selection.

    Parameters

    otherSelection : Selection | DocumentSelection

    Selection to compare with.

    Returns

    boolean

    true if selections are similar, 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

    _setFocus( itemOrPosition, [ offset ] ) → void

    See source

    Moves focus to the specified location.

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

    Parameters

    itemOrPosition : Position | Item
    [ offset ] : PositionOffset

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

    Returns

    void

    Fires

  • internal

    _setTo( args ) → void

    See source

    Sets this selection's ranges and direction to the specified location based on the given selectable.

    // Sets selection to the given range.
const range = writer.createRange( start, end );
documentSelection._setTo( range );

// Sets selection to given ranges.
const ranges = [ writer.createRange( start1, end2 ), writer.createRange( start2, end2 ) ];
documentSelection._setTo( range );

// Sets selection to the other selection.
const otherSelection = writer.createSelection();
documentSelection._setTo( otherSelection );

// Sets collapsed selection at the given position.
const position = writer.createPositionAt( root, offset );
documentSelection._setTo( position );

// Sets collapsed selection at the position of given item and offset.
documentSelection._setTo( paragraph, offset );

    Creates a range inside an element which starts before the first child of that element and ends after the last child of that element.

    documentSelection._setTo( paragraph, 'in' );

    Creates a range on an item which starts before the item and ends just after the item.

    documentSelection._setTo( paragraph, 'on' );

// Clears selection. Removes all ranges.
documentSelection._setTo( null );

    Selection#_setTo() method allow passing additional options (backward, fake and label) as the last argument.

    // Sets selection as backward.
documentSelection._setTo( range, { backward: true } );

    Fake selection does not render as browser native selection over selected elements and is hidden to the user. This way, no native selection UI artifacts are displayed to the user and selection over elements can be represented in other way, for example by applying proper CSS class.

    Additionally fake's selection label can be provided. It will be used to des cribe fake selection in DOM (and be properly handled by screen readers).

    // Creates fake selection with label.
documentSelection._setTo( range, { fake: true, label: 'foo' } );

    Parameters

    args : tuple

    Returns

    void

    Fires

Events

  • change( eventInfo )

    See source

    Fired whenever selection ranges are changed through Selection API.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.