CKEditor 4 Documentation

CKEDITOR.dom.selection

Files

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.

Defined By

Properties

CKEDITOR.dom.selection
view source
: CKEDITOR.dom.documentreadonly

Document in which selection is anchored.

Document in which selection is anchored.

CKEDITOR.dom.selection
view source
: Booleanreadonly
Whether selection is a fake selection. ...

Whether selection is a fake selection.

See fake method.

CKEDITOR.dom.selection
view source
: Booleanreadonly
Whether selection is locked (cannot be modified). ...

Whether selection is locked (cannot be modified).

See lock and unlock methods.

CKEDITOR.dom.selection
view source
: Numberreadonly
Selection's revision. ...

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

Available since: 4.3

CKEDITOR.dom.selection
view source
: CKEDITOR.dom.elementreadonly

Selection's root element.

Selection's root element.

Defined By

Methods

CKEDITOR.dom.selection
view source
new( target ) : CKEDITOR.dom.selection
Creates a selection class instance. ...

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

Returns

CKEDITOR.dom.selection
view source
( serializable ) : Array
Creates a bookmark for each range of this selection (from getRanges) by calling the CKEDITOR.dom.range.createBookmark...

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.

CKEDITOR.dom.selection
view source
( normalized ) : Array
Creates a bookmark for each range of this selection (from getRanges) by calling the CKEDITOR.dom.range.createBookmark...

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.

CKEDITOR.dom.selection
view source
( element )
Makes a "fake selection" of an element. ...

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

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

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

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

Returns

CKEDITOR.dom.selection
view source
( ) : Object
Gets the native selection object from the browser. ...

Gets the native selection object from the browser.

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

Returns

  • Object

    The native browser selection object.

CKEDITOR.dom.selection
view source
( [onlyEditables] ) : Array
Retrieves the CKEDITOR.dom.range instances that represent the current selection. ...

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 (optional)

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

Returns

  • Array

    Range instances that represent the current selection.

Gets the currently selected element. ...

Gets the currently selected element.

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

Returns

CKEDITOR.dom.selection
view source
( ) : String
Retrieves the text contained within the range. ...

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

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

Available since: 3.6.1

Returns

  • String

    A string of text within the current selection.

Gets the DOM element in which the selection starts. ...

Gets the DOM element in which the selection starts.

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

Returns

CKEDITOR.dom.selection
view source
( ) : Number
Gets the type of the current selection. ...

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

CKEDITOR.dom.selection
view source
( ) : Boolean
Checks whether selection is placed in hidden element. ...

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
CKEDITOR.dom.selection
view source
( )
Locks the selection made in the editor in order to make it possible to manipulate it without browser interference. ...

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();
CKEDITOR.dom.selection
view source
( )
Remove all the selection ranges from the document. ...

Remove all the selection ranges from the document.

CKEDITOR.dom.selection
view source
( )
Clears the selection cache. ...

Clears the selection cache.

editor.getSelection().reset();
CKEDITOR.dom.selection
view source
( )
Moves the scrollbar to the starting position of the current selection. ...

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

editor.getSelection().scrollIntoView();
CKEDITOR.dom.selection
view source
( bookmarks ) : CKEDITOR.dom.selectionchainable
Selects the virtual ranges denoted by the bookmarks by calling selectRanges. ...

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

CKEDITOR.dom.selection
view source
( element )
Makes the current selection of type CKEDITOR.SELECTION_ELEMENT by enclosing the specified element. ...

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

CKEDITOR.dom.selection
view source
( ranges )
Clears the original selection and adds the specified ranges to the document selection. ...

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.

CKEDITOR.dom.selection
view source
( restore )
...

Parameters

  • restore : Object