CKEDITOR.dom.selection

class

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

Public
Inherited
Mixed
Protected
Private
Deprecated

Properties

FILLING_CHAR_SEQUENCE : String

since 4.5.7 readonly

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

See source
document : document

readonly

Document in which selection is anchored.

See source
isFake : Boolean

readonly

Whether selection is a fake selection.

See source

See fake method.
isLocked : Boolean

readonly

Whether selection is locked (cannot be modified).

See source

See lock and unlock methods.
rev : Number

since 4.3.0 readonly

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

See source
root : element

readonly

Selection's root element.

See source

Methods

constructor( target ) → selection
Creates a selection class instance.

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

See source
```
var bookmarks = editor.getSelection().createBookmarks();
```
Parameters

serializable : Object

Returns

Array

Array of bookmarks for each range.
createBookmarks2( normalized ) → Array
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.

See source
```
var bookmarks = editor.getSelection().createBookmarks2();
```
Parameters

normalized : Object

Returns

Array

Array of bookmarks for each range.
fake( element, [ ariaLabel ] )

Makes a "fake selection" of an element.

See source

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
Retrieves the common ancestor node of the first range and the last range.

See source
```
var ancestor = editor.getSelection().getCommonAncestor();
```
Returns

element

The common ancestor of the selection or null if selection is empty.
getNative() → Object
Gets the native selection object from the browser.

See source
```
var selection = editor.getSelection().getNative();
```
Returns

Object

The native browser selection object or null if this is a fake selection.
getRanges( [ onlyEditables ] ) → Array
Retrieves the CKEDITOR.dom.range instances that represent the current selection.

See source
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
Gets the currently selected element.

See source
```
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.
getSelectedText() → String

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

See source
```
var text = editor.getSelection().getSelectedText();
alert( text );
```
Returns

String

A string of text within the current selection.
getStartElement() → element
Gets the DOM element in which the selection starts.

See source
```
var element = editor.getSelection().getStartElement();
alert( element.getName() );
```
Returns

element

The element at the beginning of the selection.
getType() → Number
Gets the type of the current selection. The following values are available:

See source
- 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.
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.
isCollapsed() → Boolean

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

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

Boolean
isHidden() → Boolean
Checks whether selection is placed in hidden element.

See source
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
isInTable( [ allowPartialSelection ] ) → Boolean

since 4.7.0
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).

See source
```
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()
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.

See source
```
editor.getSelection().lock();
```
optimizeInElementEnds()

since 4.13.0
Performs an optimization on the current selection if necessary.

See source
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:
```
 {foo
 ]bar
```
is optimized too:
```
 {foo}
 bar
```
removeAllRanges()

Remove all the selection ranges from the document.

See source
reset()
Clears the selection cache.

See source
```
editor.getSelection().reset();
```
scrollIntoView()
Moves the scrollbar to the starting position of the current selection.

See source
```
editor.getSelection().scrollIntoView();
```
selectBookmarks( bookmarks ) → selection

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

See source
```
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 )
Makes the current selection of type CKEDITOR.SELECTION_ELEMENT by enclosing the specified element.

See source
```
var element = editor.document.getById( 'sampleElement' );
editor.getSelection().selectElement( element );
```
Parameters

element : element

The element to enclose in the selection.
selectRanges( ranges )
Clears the original selection and adds the specified ranges to the document selection.

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

setupEditorOptimization( editor )

since 4.13.0 static

Sets editor listeners up to optimize the selection.

See source

Note: This method is called automatically during the editor initialization and should not be called manually.

CKEDITOR.dom.selection.optimizeInElementEnds

Parameters

editor : editor

CKEDITOR.dom.selection

Filtering

Properties

FILLING_CHAR_SEQUENCE : StringCKEDITOR.dom.selection#FILLING_CHAR_SEQUENCE

document : documentCKEDITOR.dom.selection#document

isFake : BooleanCKEDITOR.dom.selection#isFake

isLocked : BooleanCKEDITOR.dom.selection#isLocked

rev : NumberCKEDITOR.dom.selection#rev

root : elementCKEDITOR.dom.selection#root

Methods

constructor( target ) → selectionCKEDITOR.dom.selection#constructor

Parameters

Returns

createBookmarks( serializable ) → ArrayCKEDITOR.dom.selection#createBookmarks

Parameters

Returns

createBookmarks2( normalized ) → ArrayCKEDITOR.dom.selection#createBookmarks2

Parameters

Returns

fake( element, [ ariaLabel ] )CKEDITOR.dom.selection#fake

Parameters

getCommonAncestor() → elementCKEDITOR.dom.selection#getCommonAncestor

Returns

getNative() → ObjectCKEDITOR.dom.selection#getNative

Returns

getRanges( [ onlyEditables ] ) → ArrayCKEDITOR.dom.selection#getRanges

Parameters

Returns

getSelectedElement() → element | nullCKEDITOR.dom.selection#getSelectedElement

Returns

getSelectedText() → StringCKEDITOR.dom.selection#getSelectedText

Returns

getStartElement() → elementCKEDITOR.dom.selection#getStartElement

Returns

getType() → NumberCKEDITOR.dom.selection#getType

Returns

isCollapsed() → BooleanCKEDITOR.dom.selection#isCollapsed

Returns

isHidden() → BooleanCKEDITOR.dom.selection#isHidden

Returns

isInTable( [ allowPartialSelection ] ) → BooleanCKEDITOR.dom.selection#isInTable

Parameters

Returns

lock()CKEDITOR.dom.selection#lock

optimizeInElementEnds()CKEDITOR.dom.selection#optimizeInElementEnds

removeAllRanges()CKEDITOR.dom.selection#removeAllRanges

reset()CKEDITOR.dom.selection#reset

scrollIntoView()CKEDITOR.dom.selection#scrollIntoView

selectBookmarks( bookmarks ) → selectionCKEDITOR.dom.selection#selectBookmarks

Parameters

Returns

selectElement( element )CKEDITOR.dom.selection#selectElement

Parameters

selectRanges( ranges )CKEDITOR.dom.selection#selectRanges

Parameters

unlock( restore )CKEDITOR.dom.selection#unlock

Parameters

Static methods

setupEditorOptimization( editor )CKEDITOR.dom.selection#setupEditorOptimization

Parameters

`FILLING_CHAR_SEQUENCE : String`

`document : document`

`isFake : Boolean`

`isLocked : Boolean`

`rev : Number`

`root : element`

`constructor( target ) → selection`

`createBookmarks( serializable ) → Array`

`createBookmarks2( normalized ) → Array`

`fake( element, [ ariaLabel ] )`

`getCommonAncestor() → element`

`getNative() → Object`

`getRanges( [ onlyEditables ] ) → Array`

`getSelectedElement() → element | null`

`getSelectedText() → String`

`getStartElement() → element`

`getType() → Number`

`isCollapsed() → Boolean`

`isHidden() → Boolean`

`isInTable( [ allowPartialSelection ] ) → Boolean`

`lock()`

`optimizeInElementEnds()`

`removeAllRanges()`

`reset()`

`scrollIntoView()`

`selectBookmarks( bookmarks ) → selection`

`selectElement( element )`

`selectRanges( ranges )`

`unlock( restore )`

`setupEditorOptimization( editor )`