Class

DocumentSelection (engine/view)

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

class

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

    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

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

  • readonly

    fakeSelectionLabel : string

    Returns fake selection label.

  • readonly

    focus : null | Position

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

  • readonly

    isBackward : boolean

    Specifies whether the focus precedes anchor.

  • readonly

    isCollapsed : boolean

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

  • readonly

    isFake : boolean

    Returns true if selection instance is marked as fake.

  • readonly

    rangeCount : number

    Returns number of ranges in selection.

  • internal readonly

    _ranges : Array<Range>

    Used for the compatibility with the isEqual method.

  • private readonly

    _selection : Selection

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

Methods

  • constructor( [ selectable ], [ options ] )

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

    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

    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' ]

    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

    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

    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

    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

    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>

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

    Returns

    IterableIterator<Range>
  • getSelectedElement() → null | Element

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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 )

    Fired whenever selection ranges are changed through Selection API.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.