CKEditor Ecosystem Documentation
Search
Report an issue
Home/CKEditor 5/API
Class

DocumentSelection (engine/view)

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

class

Class representing document selection in tree view. It's instance is stored at selection. It is similar to Selection but it has read-only API and can be modified only by writer obtained from change method.

Selection can consist of ranges. Selection's ranges can be obtained via getRanges, getFirstRange and getLastRange methods, which return copies of ranges stored inside selection. Modifications made on these copies will not change selection's state. Similar situation occurs when getting anchor, focus, first and last positions - all will return copies of requested positions.

Filtering

Properties

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

  • editableElement : EditableElement | null

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

  • fakeSelectionLabel

    Returns fake selection label.

  • focus : Position

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

  • isBackward : Boolean

    Specifies whether the focus precedes anchor.

  • isCollapsed : Boolean

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

  • isFake

    Returns true if selection instance is marked as fake.

  • rangeCount : Number

    Returns number of ranges in selection.

  • _ranges

    protected

    Used for the compatibility with the isEqual method.

  • _selection : Selection

    private

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

Methods

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

    Creates new DocumentSelection instance. 

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

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

// Creates selection at the given ranges
const ranges = [ new Range( start1, end2 ), new Range( star2, end2 ) ];
const selection = new DocumentSelection( ranges );

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

// Creates selection at the given position.
const position = new Position( root, path );
const selection = new DocumentSelection( position );

// 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( 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' } );

    Parameters

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

    Offset or place when selectable is an Item.

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

    Sets this selection instance to be backward.

    [ options.fake ] : Boolean

    Sets this selection instance to be marked as fake.

    [ options.label ] : String

    Label for the fake selection.

  • getFirstPosition() → Position | null

    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

    Position | null

  • getFirstRange() → Range | null

    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

    Range | null

  • getLastPosition() → Position | null

    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

    Position | null

  • getLastRange() → Range | null

    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

    Range | null

  • getRanges() → Iterable.<Range>

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

    Returns

    Iterable.<Range>

  • 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

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

  • _setFocus( itemOrPosition, [ offset ] )

    protected

    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 view item.

    Defaults to 0

    Fires

  • _setTo( selectable, [ placeOrOffset ], [ options ] = { [options.backward], [options.fake], [options.label] } )

    protected

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

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

// Sets selection to given ranges.
const ranges = [ new Range( start1, end2 ), new Range( star2, end2 ) ];
documentSelection._setTo( range );

// Sets selection to the other selection.
const otherSelection = new Selection();
documentSelection._setTo( otherSelection );

// Sets collapsed selection at the given position.
const position = new Position( root, path );
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

    selectable : Selection | Position | Iterable.<Range> | Range | Item | 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.

    [ options.fake ] : Boolean

    Sets this selection instance to be marked as fake.

    [ options.label ] : String

    Label for the fake selection.

    Fires

Events

  • change( eventInfo )

    Fired whenever selection ranges are changed through Selection API.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.