DocumentSelection (engine/model)

@ckeditor/ckeditor5-engine/src/model/documentselection

class

DocumentSelection is a special selection which is used as the document's selection. There can be only one instance of DocumentSelection per document.

Document selection can only be changed by using the Writer instance inside the change() block, as it provides a secure way to modify model.

DocumentSelection is automatically updated upon changes in the document to always contain valid ranges. Its attributes are inherited from the text unless set explicitly.

Differences between Selection and DocumentSelection are:

there is always a range in DocumentSelection - even if no ranges were added there is a "default range" present in the selection,
ranges added to this selection updates automatically when the document changes,
attributes of DocumentSelection are updated automatically according to selection ranges.

Since DocumentSelection uses live ranges and is updated when document changes, it cannot be set on nodes that are inside document fragment. If you need to represent a selection in document fragment, use Selection class instead.

Filtering

Public
Inherited
Mixed
Protected
Private
Deprecated

Properties

anchor : Position | null

readonly
Selection anchor. Anchor may be described as a position where the most recent part of the selection starts. Together with focus they define the direction of selection, which is important when expanding/shrinking selection. Anchor is always start or end position of the most recently added range.

See source
Is set to null if there are no ranges in selection.

Related:
- DocumentSelection#focus
focus : Position | null

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

See source
Is set to null if there are no ranges in selection.

Related:
- DocumentSelection#anchor
hasOwnRange : Boolean

readonly

Describes whether Documentselection has own range(s) set, or if it is defaulted to document's default range.

See source
isBackward : Boolean

readonly

Specifies whether the focus precedes anchor.

See source
isCollapsed : Boolean

readonly

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

See source
isGravityOverridden

readonly

Describes whether the gravity is overridden (using overrideSelectionGravity) or not.

See source

Note that the gravity remains overridden as long as will not be restored the same number of times as it was overridden.
markers : Collection

readonly

A collection of selection markers. Marker is a selection marker when selection range is inside the marker range.

See source

Note: Only markers from observed markers groups are collected.
rangeCount : Number

readonly

Returns number of ranges in selection.

See source
_ranges

protected

Used for the compatibility with the isEqual method.

See source
_selection

protected

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

See source

Methods

constructor( doc )

Creates an empty live selection for given Document.

See source

Parameters

doc : Document

Document which owns this selection.
containsEntireContent( [ element ] ) → Boolean

Checks whether the selection contains the entire content of the given element. This means that selection must start at a position touching the element's start and ends at position touching the element's end.

See source

By default, this method will check whether the entire content of the selection's current root is selected. Useful to check if e.g. the user has just pressed Ctrl + A.

Parameters

[ element ] : Element

Defaults to this.anchor.root

Returns

Boolean
delegate( events ) → EmitterMixinDelegateChain

mixed
Delegates selected events to another Emitter. For instance:

See source
```
emitterA.delegate( 'eventX' ).to( emitterB );
emitterA.delegate( 'eventX', 'eventY' ).to( emitterC );
```
then eventX is delegated (fired by) emitterB and emitterC along with data:
```
emitterA.fire( 'eventX', data );
```
and eventY is delegated (fired by) emitterC along with data:
```
emitterA.fire( 'eventY', data );
```
Parameters

events : String

Event names that will be delegated to another emitter.

Returns

EmitterMixinDelegateChain
destroy()

Unbinds all events previously bound by document selection.

See source
fire( eventOrInfo, [ args ] ) → *

mixed

Fires an event, executing all callbacks registered for it.

See source

The first parameter passed to callbacks is an EventInfo object, followed by the optional args provided in the fire() method call.

Parameters

eventOrInfo : String | EventInfo

The name of the event or EventInfo object if event is delegated.

[ args ] : *

Additional arguments to be passed to the callbacks.

Returns

*

By default the method returns undefined. However, the return value can be changed by listeners through modification of the evt.return's property (the event info is the first param of every callback).
getAttribute( key ) → *

Gets an attribute value for given key or undefined if that attribute is not set on the selection.

See source

Parameters

key : String

Key of attribute to look for.

Returns

*

Attribute value or undefined.
getAttributeKeys() → Iterable.<String>

Returns iterable that iterates over this selection's attribute keys.

See source

Returns

Iterable.<String>
getAttributes() → Iterable.<*>

Returns iterable that iterates over this selection's attributes.

See source

Attributes are returned as arrays containing two items. First one is attribute key and second is attribute value. This format is accepted by native Map object and also can be passed in Node constructor.

Returns

Iterable.<*>
getFirstPosition() → Position | null

Returns the first position in the selection. First position is the position that is before any other position in the selection.

See source

Returns null if there are no ranges in selection.

Returns

Position | null
getFirstRange() → Range | null

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

See source

Returns null if there are no ranges in selection.

Returns

Range | null
getLastPosition() → Position | null

Returns the last position in the selection. Last position is the position that is after any other position in the selection.

See source

Returns null if there are no ranges in selection.

Returns

Position | null
getLastRange() → Range | null

Returns a 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 range most recently added to the selection).

See source

Returns null if there are no ranges in selection.

Returns

Range | null
getRanges() → Iterable.<Range>

Returns an iterable that iterates over copies of selection ranges.

See source

Returns

Iterable.<Range>
getSelectedBlocks() → Iterable.<Element>
Gets elements of type "block" touched by the selection.

See source
This method's result can be used for example to apply block styling to all blocks covered by this selection.

Note: getSelectedBlocks() returns blocks that are nested in other non-block elements but will not return blocks nested in other blocks.

In this case the function will return exactly all 3 paragraphs (note: <blockQuote> is not a block itself):
```
<paragraph>[a</paragraph>
<blockQuote>
	<paragraph>b</paragraph>
</blockQuote>
<paragraph>c]d</paragraph>
```
In this case the paragraph will also be returned, despite the collapsed selection:
```
<paragraph>[]a</paragraph>
```
In such a scenario, however, only blocks A, B & E will be returned as blocks C & D are nested in block B:
```
[<blockA></blockA>
<blockB>
	<blockC></blockC>
	<blockD></blockD>
</blockB>
<blockE></blockE>]
```
If the selection is inside a block all the inner blocks (A & B) are returned:
```
<block>
	<blockA>[a</blockA>
	<blockB>b]</blockB>
</block>
```
Special case: If a selection ends at the beginning of a block, that block is not returned as from user perspective this block wasn't selected. See #984 for more details.
```
<paragraph>[a</paragraph>
<paragraph>b</paragraph>
<paragraph>]c</paragraph> // this block will not be returned
```
Returns

Iterable.<Element>
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
hasAttribute( key ) → Boolean

Checks if the selection has an attribute for given key.

See source

Parameters

key : String

Key of attribute to check.

Returns

Boolean

true if attribute with given key is set on selection, false otherwise.

`is( type ) → Boolean`

Checks whether this object is of the given type.

See source

selection.is( 'selection' ); // -> true
selection.is( 'documentSelection' ); // -> true
selection.is( 'model:selection' ); // -> true
selection.is( 'model:documentSelection' ); // -> true

selection.is( 'view:selection' ); // -> false
selection.is( 'element' ); // -> false
selection.is( 'node' ); // -> false

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

Parameters

type : String

Returns

Boolean

listenTo( emitter, event, callback, [ options ] = { [options.priority] } )

mixed
Registers a callback function to be executed when an event is fired in a specific (emitter) object.

See source
Events can be grouped in namespaces using :. When namespaced event is fired, it additionally fires all callbacks for that namespace.
```
// myEmitter.on( ... ) is a shorthand for myEmitter.listenTo( myEmitter, ... ).
myEmitter.on( 'myGroup', genericCallback );
myEmitter.on( 'myGroup:myEvent', specificCallback );

// genericCallback is fired.
myEmitter.fire( 'myGroup' );
// both genericCallback and specificCallback are fired.
myEmitter.fire( 'myGroup:myEvent' );
// genericCallback is fired even though there are no callbacks for "foo".
myEmitter.fire( 'myGroup:foo' );
```
An event callback can stop the event and set the return value of the fire method.

Parameters

emitter : Emitter

The object that fires the event.

event : String

The name of the event.

callback : function

The function to be called on event.

[ options ] : Object

Additional options.

Properties

[ options.priority ] : PriorityString | Number

The priority of this event callback. The higher the priority value the sooner the callback will be fired. Events having the same priority are called in the order they were added.

Defaults to 'normal'

Defaults to {}
observeMarkers( prefixOrName )

Registers a marker group prefix or a marker name to be collected in the selection markers collection.

See source

See also MarkerCollection#getMarkersGroup().

Parameters

prefixOrName : String

The marker group prefix or marker name.
off( event, callback )

mixed

Stops executing the callback on the given event. Shorthand for this.stopListening( this, event, callback ).

See source

Parameters

event : String

The name of the event.

callback : function

The function to stop being called.
on( event, callback, [ options ] = { [options.priority] } )

mixed

Registers a callback function to be executed when an event is fired.

See source

Shorthand for this.listenTo( this, event, callback, options ) (it makes the emitter listen on itself).

Parameters

event : String

The name of the event.

callback : function

The function to be called on event.

[ options ] : Object

Additional options.

Properties

[ options.priority ] : PriorityString | Number

The priority of this event callback. The higher the priority value the sooner the callback will be fired. Events having the same priority are called in the order they were added.

Defaults to 'normal'

Defaults to {}
once( event, callback, [ options ] = { [options.priority] } )

mixed

Registers a callback function to be executed on the next time the event is fired only. This is similar to calling on followed by off in the callback.

See source

Parameters

event : String

The name of the event.

callback : function

The function to be called on event.

[ options ] : Object

Additional options.

Properties

[ options.priority ] : PriorityString | Number

The priority of this event callback. The higher the priority value the sooner the callback will be fired. Events having the same priority are called in the order they were added.

Defaults to 'normal'

Defaults to {}
refresh()

Refreshes selection attributes and markers according to the current position in the model.

See source
stopDelegating( [ event ], [ emitter ] )

mixed
Stops delegating events. It can be used at different levels:

See source
- To stop delegating all events.
- To stop delegating a specific event to all emitters.
- To stop delegating a specific event to a specific emitter.
Parameters

[ event ] : String

The name of the event to stop delegating. If omitted, stops it all delegations.

[ emitter ] : Emitter

(requires event) The object to stop delegating a particular event to. If omitted, stops delegation of event to all emitters.
stopListening( [ emitter ], [ event ], [ callback ] )

mixed
Stops listening for events. It can be used at different levels:

See source
- To stop listening to a specific callback.
- To stop listening to a specific event.
- To stop listening to all events fired by a specific object.
- To stop listening to all events fired by all objects.
Parameters

[ emitter ] : Emitter

The object to stop listening to. If omitted, stops it for all objects.

[ event ] : String

(Requires the emitter) The name of the event to stop listening to. If omitted, stops it for all events from emitter.

[ callback ] : function

(Requires the event) The function to be removed from the call list for the given event.
_addEventListener( event, callback, [ options ] = { [options.priority] } )

protected mixed

Adds callback to emitter for given event.

See source

Parameters

event : String

The name of the event.

callback : function

The function to be called on event.

[ options ] : Object

Additional options.

Properties

[ options.priority ] : PriorityString | Number

The priority of this event callback. The higher the priority value the sooner the callback will be fired. Events having the same priority are called in the order they were added.

Defaults to 'normal'

Defaults to {}
_getStoredAttributes() → Iterable.<*>

protected

Returns an iterable that iterates through all selection attributes stored in current selection's parent.

See source

Returns

Iterable.<*>
_overrideGravity() → String

protected
Temporarily changes the gravity of the selection from the left to the right.

See source
The gravity defines from which direction the selection inherits its attributes. If it's the default left gravity, the selection (after being moved by the the user) inherits attributes from its left hand side. This method allows to temporarily override this behavior by forcing the gravity to the right.

It returns an unique identifier which is required to restore the gravity. It guarantees the symmetry of the process.

Returns

String

The unique id which allows restoring the gravity.

Related:
- Writer#overrideSelectionGravity
_removeAttribute( key )

protected
Removes an attribute with given key from the selection. If the given attribute was set on the selection, fires the event-change:range event with removed attribute key. Should be used only within the removeSelectionAttribute method.

See source
Parameters

key : String

Key of the attribute to remove.

Related:
- Writer#removeSelectionAttribute
_removeEventListener( event, callback )

protected mixed

Removes callback from emitter for given event.

See source

Parameters

event : String

The name of the event.

callback : function

The function to stop being called.
_restoreGravity( uid )

protected
Restores the overridden gravity.

See source
Restoring the gravity is only possible using the unique identifier returned by _overrideGravity. Note that the gravity remains overridden as long as won't be restored the same number of times it was overridden.

Parameters

uid : String

The unique id returned by _overrideGravity.

Related:
- Writer#restoreSelectionGravity
_setAttribute( key, value )

protected
Sets attribute on the selection. If attribute with the same key already is set, it's value is overwritten. Should be used only within the setSelectionAttribute method.

See source
Parameters

key : String

Key of the attribute to set.

value : *

Attribute value.

Related:
- Writer#setSelectionAttribute
_setFocus( itemOrPosition, [ offset ] )

protected
Moves focus to the specified location. Should be used only within the setSelectionFocus method.

See source
The location can be specified in the same form as writer.createPositionAt() parameters.

Parameters

itemOrPosition : Item | Position

[ offset ] : Number | 'end' | 'before' | 'after'

Offset or one of the flags. Used only when first parameter is a model item.

Related:
- Writer#setSelectionFocus
_setTo( selectable, [ placeOrOffset ], [ options ] = { [options.backward] } )

protected
Sets this selection's ranges and direction to the specified location based on the given selectable. Should be used only within the setSelection method.

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

Related:
- Writer#setSelection

Static methods

_getStoreAttributeKey( key ) → String

protected static

Generates and returns an attribute key for selection attributes store, basing on original attribute key.

See source

Parameters

key : String

Attribute key to convert.

Returns

String

Converted attribute key, applicable for selection store.
_isStoreAttributeKey( key ) → Boolean

protected static

Checks whether the given attribute key is an attribute stored on an element.

See source

Parameters

key : String

Returns

Boolean

Events

change:attribute( eventInfo, directChange, attributeKeys )

Fired when selection attribute changed.

See source

Parameters

eventInfo : EventInfo

An object containing information about the fired event.

directChange : Boolean

In case of Selection class it is always set to true which indicates that the selection change was caused by a direct use of selection's API. The DocumentSelection, however, may change because its attributes were directly changed through the writer or because its position was changed in the model and its attributes were refreshed (which means an indirect change). The indirect change does not occur in case of normal (detached) selections because they are "static" (as "not live") which mean that they are not updated once the document changes.

attributeKeys : Array.<String>

Array containing keys of attributes that changed.
change:marker( eventInfo, directChange, oldMarkers )

Fired when selection marker(s) changed.

See source

Parameters

eventInfo : EventInfo

An object containing information about the fired event.

directChange : Boolean

This is always set to false in case of change:marker event as there is no possibility to change markers directly through DocumentSelection API. See also event-change:range and event-change:attribute.

oldMarkers : Array.<Marker>

Markers in which the selection was before the change.
change:range( eventInfo, directChange )

Fired when selection range(s) changed.

See source

Parameters

eventInfo : EventInfo

An object containing information about the fired event.

directChange : Boolean

In case of Selection class it is always set to true which indicates that the selection change was caused by a direct use of selection's API. The DocumentSelection, however, may change because its position was directly changed through the writer or because its position was changed because the structure of the model has been changed (which means an indirect change). The indirect change does not occur in case of normal (detached) selections because they are "static" (as "not live") which mean that they are not updated once the document changes.

Every day, we work hard to keep our documentation complete. Have you spotted an outdated information? Is something missing? Please report it via our issue tracker.

DocumentSelection (engine/model)

Filtering

Properties

anchor : Position | nullmodule:engine/model/documentselection~DocumentSelection#anchor

Related:

focus : Position | nullmodule:engine/model/documentselection~DocumentSelection#focus

Related:

hasOwnRange : Booleanmodule:engine/model/documentselection~DocumentSelection#hasOwnRange

isBackward : Booleanmodule:engine/model/documentselection~DocumentSelection#isBackward

isCollapsed : Booleanmodule:engine/model/documentselection~DocumentSelection#isCollapsed

isGravityOverriddenmodule:engine/model/documentselection~DocumentSelection#isGravityOverridden

markers : Collectionmodule:engine/model/documentselection~DocumentSelection#markers

rangeCount : Numbermodule:engine/model/documentselection~DocumentSelection#rangeCount

_rangesmodule:engine/model/documentselection~DocumentSelection#_ranges

_selectionmodule:engine/model/documentselection~DocumentSelection#_selection

Methods

constructor( doc )module:engine/model/documentselection~DocumentSelection#constructor

Parameters

containsEntireContent( [ element ] ) → Booleanmodule:engine/model/documentselection~DocumentSelection#containsEntireContent

Parameters

Returns

delegate( events ) → EmitterMixinDelegateChainmodule:engine/model/documentselection~DocumentSelection#delegate

Parameters

Returns

destroy()module:engine/model/documentselection~DocumentSelection#destroy

fire( eventOrInfo, [ args ] ) → *module:engine/model/documentselection~DocumentSelection#fire

Parameters

Returns

getAttribute( key ) → *module:engine/model/documentselection~DocumentSelection#getAttribute

Parameters

Returns

getAttributeKeys() → Iterable.<String>module:engine/model/documentselection~DocumentSelection#getAttributeKeys

Returns

getAttributes() → Iterable.<*>module:engine/model/documentselection~DocumentSelection#getAttributes

Returns

getFirstPosition() → Position | nullmodule:engine/model/documentselection~DocumentSelection#getFirstPosition

Returns

getFirstRange() → Range | nullmodule:engine/model/documentselection~DocumentSelection#getFirstRange

Returns

getLastPosition() → Position | nullmodule:engine/model/documentselection~DocumentSelection#getLastPosition

Returns

getLastRange() → Range | nullmodule:engine/model/documentselection~DocumentSelection#getLastRange

Returns

getRanges() → Iterable.<Range>module:engine/model/documentselection~DocumentSelection#getRanges

Returns

getSelectedBlocks() → Iterable.<Element>module:engine/model/documentselection~DocumentSelection#getSelectedBlocks

Returns

getSelectedElement() → Element | nullmodule:engine/model/documentselection~DocumentSelection#getSelectedElement

Returns

hasAttribute( key ) → Booleanmodule:engine/model/documentselection~DocumentSelection#hasAttribute

Parameters

Returns

is( type ) → Booleanmodule:engine/model/documentselection~DocumentSelection#is

Parameters

Returns

listenTo( emitter, event, callback, [ options ] = { [options.priority] } )module:engine/model/documentselection~DocumentSelection#listenTo

Parameters

observeMarkers( prefixOrName )module:engine/model/documentselection~DocumentSelection#observeMarkers

Parameters

off( event, callback )module:engine/model/documentselection~DocumentSelection#off

Parameters

on( event, callback, [ options ] = { [options.priority] } )module:engine/model/documentselection~DocumentSelection#on

Parameters

once( event, callback, [ options ] = { [options.priority] } )module:engine/model/documentselection~DocumentSelection#once

Parameters

refresh()module:engine/model/documentselection~DocumentSelection#refresh

stopDelegating( [ event ], [ emitter ] )module:engine/model/documentselection~DocumentSelection#stopDelegating

Parameters

stopListening( [ emitter ], [ event ], [ callback ] )module:engine/model/documentselection~DocumentSelection#stopListening

Parameters

_addEventListener( event, callback, [ options ] = { [options.priority] } )module:engine/model/documentselection~DocumentSelection#_addEventListener

Parameters

_getStoredAttributes() → Iterable.<*>module:engine/model/documentselection~DocumentSelection#_getStoredAttributes

Returns

_overrideGravity() → Stringmodule:engine/model/documentselection~DocumentSelection#_overrideGravity

Returns

Related:

_removeAttribute( key )module:engine/model/documentselection~DocumentSelection#_removeAttribute

Parameters

Related:

`anchor : Position | null`

`focus : Position | null`

`hasOwnRange : Boolean`

`isBackward : Boolean`

`isCollapsed : Boolean`

`isGravityOverridden`

`markers : Collection`

`rangeCount : Number`

`_ranges`

`_selection`

`constructor( doc )`

`containsEntireContent( [ element ] ) → Boolean`

`delegate( events ) → EmitterMixinDelegateChain`

`destroy()`

`fire( eventOrInfo, [ args ] ) → *`

`getAttribute( key ) → *`

`getAttributeKeys() → Iterable.<String>`

`getAttributes() → Iterable.<*>`

`getFirstPosition() → Position | null`

`getFirstRange() → Range | null`

`getLastPosition() → Position | null`

`getLastRange() → Range | null`

`getRanges() → Iterable.<Range>`

`getSelectedBlocks() → Iterable.<Element>`

`getSelectedElement() → Element | null`

`hasAttribute( key ) → Boolean`

`is( type ) → Boolean`

`listenTo( emitter, event, callback, [ options ] = { [options.priority] } )`

`observeMarkers( prefixOrName )`

`off( event, callback )`

`on( event, callback, [ options ] = { [options.priority] } )`

`once( event, callback, [ options ] = { [options.priority] } )`

`refresh()`

`stopDelegating( [ event ], [ emitter ] )`

`stopListening( [ emitter ], [ event ], [ callback ] )`

`_addEventListener( event, callback, [ options ] = { [options.priority] } )`

`_getStoredAttributes() → Iterable.<*>`

`_overrideGravity() → String`

`_removeAttribute( key )`

`_removeEventListener( event, callback )`

`_restoreGravity( uid )`

`_setAttribute( key, value )`

`_setFocus( itemOrPosition, [ offset ] )`

`_setTo( selectable, [ placeOrOffset ], [ options ] = { [options.backward] } )`

`_getStoreAttributeKey( key ) → String`

`_isStoreAttributeKey( key ) → Boolean`

`change:attribute( eventInfo, directChange, attributeKeys )`

`change:marker( eventInfo, directChange, oldMarkers )`

`change:range( eventInfo, directChange )`