Class CKEDITOR.dom.selection

Defined in: plugins/selection/plugin.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	CKEDITOR.dom.selection(document) Manipulates the selection in a DOM document.

Method Summary
Method Attributes	Method Name and Description
	createBookmarks(serializable) Creates a bookmark for each range of this selection (from `#getRanges`) by calling the `CKEDITOR.dom.range.prototype.createBookmark` method, with extra care taken to avoid interference among those ranges.
	createBookmarks2(normalized) Creates a bookmark for each range of this selection (from `#getRanges`) by calling the `CKEDITOR.dom.range.prototype.createBookmark2` method, with extra care taken to avoid interference among those ranges.
	getCommonAncestor() Retrieves the common ancestor node of the first range and the last range.
	getNative() Gets the native selection object from the browser.
	getRanges(onlyEditables) Retrieves the `CKEDITOR.dom.range` instances that represent the current selection.
	getSelectedElement() Gets the currently selected element.
	getSelectedText() Retrieves the text contained within the range.
	getStartElement() Gets the DOM element in which the selection starts.
	getType() Gets the type of the current selection.
	lock() Locks the selection made in the editor in order to make it possible to manipulate it without browser interference.
	reset() Clears the selection cache.
	scrollIntoView() Moves the scrollbar to the starting position of the current selection.
	selectBookmarks(bookmarks) Selects the virtual ranges denoted by the bookmarks by calling `#selectRanges`.
	selectElement(element) Makes the current selection of type `CKEDITOR.SELECTION_ELEMENT` by enclosing the specified element.
	selectRanges(ranges) Clears the original selection and adds the specified ranges to the document selection.
	unlock(restore) Unlocks the selection made in the editor and locked with the `#lock` method.

Class Detail

CKEDITOR.dom.selection(document)

Since: 3.0

Manipulates the selection in a DOM document.

var sel = new CKEDITOR.dom.selection( CKEDITOR.document );

Parameters:
{CKEDITOR.dom.document} document: The DOM document that contains the selection.

Method Detail

{Array} createBookmarks(serializable)

Since: 3.0

Creates a bookmark for each range of this selection (from #getRanges) by calling the CKEDITOR.dom.range.prototype.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:
{Undefined} serializable

Returns:: {Array} Array of bookmarks for each range.

{Array} createBookmarks2(normalized)

Since: 3.0

Creates a bookmark for each range of this selection (from #getRanges) by calling the CKEDITOR.dom.range.prototype.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:
{Undefined} normalized

Returns:: {Array} Array of bookmarks for each range.

{CKEDITOR.dom.element} getCommonAncestor()

Since: 3.0

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

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

Returns:: {CKEDITOR.dom.element} The common ancestor of the selection.

{Object} getNative()

Since: 3.0

Gets the native selection object from the browser.

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

Returns:: {Object} The native browser selection object.

{Array} getRanges(onlyEditables)

Since: 3.0

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:
{Boolean} onlyEditables Optional: If set to true, this function retrives editable ranges only.

Returns:: {Array} Range instances that represent the current selection.

{CKEDITOR.dom.element} getSelectedElement()

Since: 3.0

Gets the currently selected element.

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

Returns:: {CKEDITOR.dom.element} The selected element. Null if no selection is available or the selection type is not CKEDITOR.SELECTION_ELEMENT.

{String} getSelectedText()

Since: 3.6.1

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.

{CKEDITOR.dom.element} getStartElement()

Since: 3.0

Gets the DOM element in which the selection starts.

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

Returns:: {CKEDITOR.dom.element} The element at the beginning of the selection.

{Number} getType()

Since: 3.0

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

CKEDITOR.SELECTION_NONE (1): No selection.
CKEDITOR.SELECTION_TEXT (2): A text or a collapsed selection is selected.
CKEDITOR.SELECTION_ELEMENT (3): An element is selected.

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.

{Undefined} lock()

Since: 3.0

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

{Undefined} reset()

Since: 3.0

Clears the selection cache.

editor.getSelection().reset();

{Undefined} scrollIntoView()

Since: 3.0

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

editor.getSelection().scrollIntoView();

{CKEDITOR.dom.selection} selectBookmarks(bookmarks)

Since: 3.0

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

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

Parameters:
{Array} bookmarks: The bookmarks representing ranges to be selected.

Returns:: {CKEDITOR.dom.selection} This selection object, after the ranges were selected.

{Undefined} selectElement(element)

Since: 3.0

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.element} element: The element to enclose in the selection.

{Undefined} selectRanges(ranges)

Since: 3.0

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

var ranges = new CKEDITOR.dom.range( editor.document );
editor.getSelection().selectRanges( [ ranges ] );

Parameters:
{Array} ranges: An array of CKEDITOR.dom.range instances representing ranges to be added to the document.

{Undefined} unlock(restore)

Since: 3.0

Unlocks the selection made in the editor and locked with the #lock method. An unlocked selection is no longer cached and can be changed.

editor.getSelection().unlock();

Parameters:
{Boolean} restore Optional: If set to true, the selection is restored back to the selection saved earlier by using the #lock method.

CKEditor 3 JavaScript API Documentation

Namespaces

Classes

Class CKEDITOR.dom.selection