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

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

    See source

    Related:

  • editableElement : EditableElement | null

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

    See source

  • fakeSelectionLabel

    Returns fake selection label.

    See source

    Related:

  • focus : Position

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

    See source

    Related:

  • isBackward : Boolean

    Specifies whether the focus precedes anchor.

    See source

  • isCollapsed : Boolean

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

    See source

  • isFake

    Returns true if selection instance is marked as fake.

    See source

    Related:

  • rangeCount : Number

    Returns number of ranges in selection.

    See source

  • _ranges

    protected

    Used for the compatibility with the isEqual method.

    See source

  • _selection : Selection

    private

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

    See source

Methods

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

    Creates new DocumentSelection instance.

    See source
    // 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 );

// 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 ] : Selectable
    [ 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.

    See source

    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.

    See source

    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.

    See source

    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.

    See source

    Returns

    Range | null

  • getRanges() → Iterable.<Range>

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

    See source

    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.

    See source

    Returns

    Element | null

  • is( type ) → Boolean

    Checks whether this object is of the given type.

    See source
    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

    Check the entire list of view objects which implement the is() method.

    Parameters

    type : String

    Returns

    Boolean

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

    See source

    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.

    See source

    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.

    See source

    The location can be specified in the same form as view.createPositionAt() 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.

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

    See source
    // 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

    selectable : Selectable
    [ 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.

    See source

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.