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

CKEDITOR.dom.selection

class
See source

Manipulates the selection within a DOM element. If the current browser selection spans outside of the element, an empty selection object is returned.

Despite the fact that selection's constructor allows to create selection instances, usually it's better to get selection from the editor instance:

var sel = editor.getSelection();

See CKEDITOR.editor.getSelection.

Filtering

Properties

  • since 4.5.7 readonly

    FILLING_CHAR_SEQUENCE : String

    See source

    The sequence used in a WebKit-based browser to create a Filling Character. By default it is a string of 7 zero-width space characters (U+200B).

  • readonly

    document : document

    See source

    Document in which selection is anchored.

  • readonly

    isFake : Boolean

    See source

    Whether selection is a fake selection.

    See fake method.

  • readonly

    isLocked : Boolean

    See source

    Whether selection is locked (cannot be modified).

    See lock and unlock methods.

  • since 4.3.0 readonly

    rev : Number

    See source

    Selection's revision. This value is incremented every time new selection is created or existing one is modified.

  • readonly

    root : element

    See source

    Selection's root element.

Methods

  • constructor( target ) → selection

    See source

    Creates a selection class instance.

    // Selection scoped in document.
var sel = new CKEDITOR.dom.selection( CKEDITOR.document );

// Selection scoped in element with 'editable' id.
var sel = new CKEDITOR.dom.selection( CKEDITOR.document.getById( 'editable' ) );

// Cloning selection.
var clone = new CKEDITOR.dom.selection( sel );

    Parameters

    target : document | element | selection

    The DOM document/element that the DOM selection is restrained to. Only selection which spans within the target element is considered as valid.

    If CKEDITOR.dom.selection is passed, then its clone will be created.

    Returns

    selection

  • createBookmarks( serializable ) → Array

    See source

    Creates a bookmark for each range of this selection (from getRanges) by calling the CKEDITOR.dom.range.createBookmark method, with extra care taken to avoid interference among those ranges. The arguments received are the same as with the underlying range method.

    var bookmarks = editor.getSelection().createBookmarks();

    Parameters

    serializable : Object

    Returns

    Array

    Array of bookmarks for each range.

  • createBookmarks2( normalized ) → Array

    See source

    Creates a bookmark for each range of this selection (from getRanges) by calling the CKEDITOR.dom.range.createBookmark2 method, with extra care taken to avoid interference among those ranges. The arguments received are the same as with the underlying range method.

    var bookmarks = editor.getSelection().createBookmarks2();

    Parameters

    normalized : Object

    Returns

    Array

    Array of bookmarks for each range.

  • fake( element, [ ariaLabel ] )

    See source

    Makes a "fake selection" of an element.

    A fake selection does not render UI artifacts over the selected element. Additionally, the browser native selection system is not aware of the fake selection. In practice, the native selection is moved to a hidden place where no native selection UI artifacts are displayed to the user.

    Parameters

    element : element

    The element to be "selected".

    [ ariaLabel ] : String

    A string to be used by the screen reader to describe the selection.

  • getCommonAncestor() → element

    See source

    Retrieves the common ancestor node of the first range and the last range.

    var ancestor = editor.getSelection().getCommonAncestor();

    Returns

    element

    The common ancestor of the selection or null if selection is empty.

  • getNative() → Object

    See source

    Gets the native selection object from the browser.

    var selection = editor.getSelection().getNative();

    Returns

    Object

    The native browser selection object or null if this is a fake selection.

  • getRanges( [ onlyEditables ] ) → Array

    See source

    Retrieves the CKEDITOR.dom.range instances that represent the current selection.

    Note: Some browsers return multiple ranges even for a continuous selection. Firefox, for example, returns one range for each table cell when one or more table rows are selected.

    var ranges = selection.getRanges();
alert( ranges.length );

    Parameters

    [ onlyEditables ] : Boolean

    If set to true, this function retrieves editable ranges only.

    Returns

    Array

    Range instances that represent the current selection.

  • getSelectedElement() → element | null

    See source

    Gets the currently selected element.

    var element = editor.getSelection().getSelectedElement();
alert( element.getName() );

    Returns

    element | null

    The selected element. null if no selection is available or the selection type is not CKEDITOR.SELECTION_ELEMENT.

  • since 3.6.1

    getSelectedText() → String

    See source

    Retrieves the text contained within the range. An empty string is returned for non-text selection.

    var text = editor.getSelection().getSelectedText();
alert( text );

    Returns

    String

    A string of text within the current selection.

  • getStartElement() → element

    See source

    Gets the DOM element in which the selection starts.

    var element = editor.getSelection().getStartElement();
alert( element.getName() );

    Returns

    element

    The element at the beginning of the selection.

  • getType() → Number

    See source

    Gets the type of the current selection. The following values are available:

    Example:

    if ( editor.getSelection().getType() == CKEDITOR.SELECTION_TEXT )
    alert( 'A text is selected' );

    Returns

    Number

    One of the following constant values: CKEDITOR.SELECTION_NONE, CKEDITOR.SELECTION_TEXT or CKEDITOR.SELECTION_ELEMENT.

  • since 4.7.3

    isCollapsed() → Boolean

    See source

    Checks if the selection contains only one range which is collapsed.

    if ( editor.getSelection().isCollapsed() ) {
    // Do something when the selection is collapsed.
}

    Returns

    Boolean

  • isHidden() → Boolean

    See source

    Checks whether selection is placed in hidden element.

    This method is to be used to verify whether fake selection (see fake) is still hidden.

    Note: this method should be executed on real selection - e.g.:

    editor.getSelection( true ).isHidden();

    Returns

    Boolean

  • since 4.7.0

    isInTable( [ allowPartialSelection ] ) → Boolean

    See source

    Checks if the selection contains an HTML element inside a table. Returns false for text selection inside a table (e.g. it will return false for text selected in one cell).

    editor.getSelection().isInTable();

    Parameters

    [ allowPartialSelection ] : Boolean

    Whether a partial cell selection should be included. Added in 4.7.2.

    Defaults to false

    Returns

    Boolean

  • lock()

    See source

    Locks the selection made in the editor in order to make it possible to manipulate it without browser interference. A locked selection is cached and remains unchanged until it is released with the unlock method.

    editor.getSelection().lock();

  • since 4.13.0

    optimizeInElementEnds()

    See source

    Performs an optimization on the current selection if necessary.

    The general idea is to shrink the range to text when:

    • The range starts at the end of an element.
    • The range ends at the start of an element.
    • One of the range ends is anchored in a text node and another in an element.

    For example:

     <p>{foo</p>
 <p>]bar</p>

    is optimized too:

     <p>{foo}</p>
 <p>bar</p>

  • removeAllRanges()

    See source

    Remove all the selection ranges from the document.

  • reset()

    See source

    Clears the selection cache.

    editor.getSelection().reset();

  • scrollIntoView()

    See source

    Moves the scrollbar to the starting position of the current selection.

    editor.getSelection().scrollIntoView();

  • chainable

    selectBookmarks( bookmarks ) → selection

    See source

    Selects the virtual ranges denoted by the bookmarks by calling selectRanges.

    var bookmarks = editor.getSelection().createBookmarks();
editor.getSelection().selectBookmarks( bookmarks );

    Parameters

    bookmarks : Array

    The bookmarks representing ranges to be selected.

    Returns

    selection

    This selection object, after the ranges were selected.

  • selectElement( element )

    See source

    Makes the current selection of type CKEDITOR.SELECTION_ELEMENT by enclosing the specified element.

    var element = editor.document.getById( 'sampleElement' );
editor.getSelection().selectElement( element );

    Parameters

    element : element

    The element to enclose in the selection.

  • selectRanges( ranges )

    See source

    Clears the original selection and adds the specified ranges to the document selection.

        // Move selection to the end of the editable element.
var range = editor.createRange();
range.moveToPosition( range.root, CKEDITOR.POSITION_BEFORE_END );
editor.getSelection().selectRanges( [ ranges ] );

    Parameters

    ranges : Array

    An array of CKEDITOR.dom.range instances representing ranges to be added to the document.

  • unlock( restore )

    See source

    Parameters

    restore : Object

Static methods