Report an issue
Class

Selection (engine/model)

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

class

Selection is a group of ranges which has a direction specified by anchor and focus. Additionally, Selection may have it's own attributes.

Filtering

Properties

  • anchor : Position | null

    readonly

    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.

  • focus : Position | null

    readonly

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

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

  • isBackward : Boolean

    readonly

    Specifies whether the focus precedes anchor.

  • isCollapsed : Boolean

    readonly

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

  • rangeCount : Number

    readonly

    Returns number of ranges in selection.

  • _attrs : Map.<String, *>

    protected

    List of attributes set on current selection.

  • _ranges : Array.<Range>

    protected

    Stores selection ranges.

  • _lastRangeBackward : Boolean

    private

    Specifies whether the last added range was added as a backward or forward range.

Methods

  • constructor( selectable, [ placeOrOffset ], [ options ] = { [options.backward] } )

    Creates new selection instance on the given selection, position, element, position, range, an iterable of ranges or creates an empty selection if no arguments passed.

    // Creates empty selection without ranges.
    const selection = new Selection();
    
    // Creates selection at the given range.
    const range = new Range( start, end );
    const selection = new Selection( range );
    
    // Creates selection at the given ranges
    const ranges = [ new Range( start1, end2 ), new Range( star2, end2 ) ];
    const selection = new Selection( ranges );
    
    // Creates selection from the other selection.
    // Note: It doesn't copies selection attributes.
    const otherSelection = new Selection();
    const selection = new Selection( otherSelection );
    
    // Creates selection from the given document selection.
    // Note: It doesn't copies selection attributes.
    const documentSelection = new DocumentSelection( doc );
    const selection = new Selection( documentSelection );
    
    // Creates selection at the given position.
    const position = new Position( root, path );
    const selection = new Selection( position );
    
    // Creates selection at the start position of the given element.
    const paragraph = writer.createElement( 'paragraph' );
    const selection = new Selection( 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 Selection( paragraph, 'in' );
    
    // Creates a range on an item which starts before the item and ends
    // just after the item.
    const selection = new Selection( paragraph, 'on' );

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

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

    Parameters

    selectable : Selection | DocumentSelection | Position | Element | Iterable.<Range> | Range | null
    [ placeOrOffset ] : Number | 'before' | 'end' | 'after' | 'on' | 'in'

    Sets place or offset of the selection.

    [ options ] : Object
    Properties
    [ options.backward ] : Boolean

    Sets this selection instance to be backward.

  • containsEntireContent( [ element ] ) → Boolean

    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

    Defaults to this.anchor.root

    Returns

    Boolean
  • getAttribute( key ) → *

    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

    *

    Attribute value or undefined.

  • getAttributeKeys() → Iterable.<String>

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

    Returns

    Iterable.<String>
  • getAttributes() → Iterable.<*>

    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

    Iterable.<*>
  • getFirstPosition() → Position | null

    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

    Position | null
  • getFirstRange() → Range | null

    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

    Range | null
  • getLastPosition() → Position | null

    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

    Position | null
  • getLastRange() → Range | null

    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

    Range | null
  • getRanges() → Iterable.<Range>

    Returns an iterable that iterates over copies of selection ranges.

    Returns

    Iterable.<Range>
  • getSelectedBlocks() → Iterable.<Element>

    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() always returns the deepest block.

    In this case the function will return exactly all 3 paragraphs:

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

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

    <paragraph>[]a</paragraph>

    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

    Iterable.<Element>
  • getSelectedElement() → Element | null

    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

    Element | null
  • hasAttribute( key ) → Boolean

    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.

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

  • removeAttribute( key )

    Removes an attribute with given key from the selection.

    If given attribute was set on the selection, fires the event-change:range event with removed attribute key.

    Parameters

    key : String

    Key of attribute to remove.

    Fires

  • setAttribute( key, value )

    Sets attribute on the selection. If attribute with the same key already is set, it's value is overwritten.

    If the attribute value has changed, fires the event-change:range event with the attribute key.

    Parameters

    key : String

    Key of attribute to set.

    value : *

    Attribute value.

    Fires

  • setFocus( itemOrPosition, [ offset ] )

    Moves focus to the specified location.

    The location can be specified in the same form as createAt parameters.

    Parameters

    itemOrPosition : Item | Position
    [ offset ] : Number | 'end' | 'before' | 'after'

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

    Defaults to 0

    Fires

  • setTo( selectable, [ placeOrOffset ], [ options ] = { [options.backward] } )

    Sets this selection's ranges and direction to the specified location based on the given selection, position, element, position, range, an iterable of ranges or null.

    // Removes all selection's ranges.
    selection.setTo( null );
    
    // Sets selection to the given range.
    const range = new Range( start, end );
    selection.setTo( range );
    
    // Sets selection to given ranges.
    const ranges = [ new Range( start1, end2 ), new Range( star2, end2 ) ];
    selection.setTo( ranges );
    
    // Sets selection to other selection.
    // Note: It doesn't copies selection attributes.
    const otherSelection = new Selection();
    selection.setTo( otherSelection );
    
    // Sets selection to the given document selection.
    // Note: It doesn't copies selection attributes.
    const documentSelection = new DocumentSelection( doc );
    selection.setTo( documentSelection );
    
    // Sets collapsed selection at the given position.
    const position = new Position( root, path );
    selection.setTo( position );
    
    // Sets collapsed selection at the position of the given node and an offset.
    selection.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.

    selection.setTo( paragraph, 'in' );

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

    selection.setTo( paragraph, 'on' );

    Selection#setTo()' method allow passing additional options (backward) as the last argument.

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

    Parameters

    selectable : Selection | DocumentSelection | Position | Node | Iterable.<Range> | Range | null
    [ placeOrOffset ] : Number | 'before' | 'end' | 'after' | 'on' | 'in'

    Sets place or offset of the selection.

    [ options ] : Object
    Properties
    [ options.backward ] : Boolean

    Sets this selection instance to be backward.

  • _checkRange( range )

    protected

    Checks if given range intersects with ranges that are already in the selection. Throws an error if it does.

    Parameters

    range : Range

    Range to check.

  • _popRange()

    protected

    Removes most recently added range from the selection.

  • _pushRange( range )

    protected

    Adds given range to internal ranges array. Throws an error if given range is intersecting with any range that is already stored in this selection.

    Parameters

    range : Range

    Range to add.

  • _removeAllRanges()

    protected

    Deletes ranges from internal range array. Uses _popRange to ensure proper ranges removal.

  • _setRanges( newRanges, [ isLastBackward ] )

    protected

    Replaces all ranges that were added to the selection with given array of ranges. Last range of the array is treated like the last added range and is used to set anchor and focus. Accepts a flag describing in which direction the selection is made.

    Parameters

    newRanges : Iterable.<Range>

    Ranges to set.

    [ isLastBackward ] : Boolean

    Flag describing if last added range was selected forward - from start to end (false) or backward - from end to start (true).

    Defaults to false

    Fires

Events

  • change:attribute( eventInfo, directChange, attributeKeys )

    Fired when selection attribute changed.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    directChange : Boolean

    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.

    attributeKeys : Array.<String>

    Array containing keys of attributes that changed.

  • change:range( eventInfo, directChange )

    Fired when selection range(s) changed.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    directChange : Boolean

    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.