# ModelDocumentSelection class `ModelDocumentSelection` is a special selection which is used as the [document's selection](module_engine_model_document-ModelDocument.md#member-selection). There can be only one instance of `ModelDocumentSelection` per document. Document selection can only be changed by using the [`ModelWriter`](module_engine_model_writer-ModelWriter.md) instance inside the [`change()`](module_engine_model_model-Model.md#function-change) block, as it provides a secure way to modify model. `ModelDocumentSelection` is automatically updated upon changes in the [document](module_engine_model_document-ModelDocument.md) to always contain valid ranges. Its attributes are inherited from the text unless set explicitly. Differences between [`ModelSelection`](module_engine_model_selection-ModelSelection.md) and `ModelDocumentSelection` are: * there is always a range in `ModelDocumentSelection` - 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 `ModelDocumentSelection` are updated automatically according to selection ranges. Since `ModelDocumentSelection` uses [live ranges](module_engine_model_liverange-ModelLiveRange.md) and is updated when [document](module_engine_model_document-ModelDocument.md) changes, it cannot be set on [nodes](module_engine_model_node-ModelNode.md) that are inside [document fragment](module_engine_model_documentfragment-ModelDocumentFragment.md). If you need to represent a selection in document fragment, use [Selection class](module_engine_model_selection-ModelSelection.md) instead. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L67) ## Properties ### `anchor: ModelPosition | null` _(readonly)_ Selection anchor. Anchor may be described as a position where the most recent part of the selection starts. Together with [`focus`](#member-focus) they define the direction of selection, which is important when expanding/shrinking selection. Anchor is always [start](module_engine_model_range-ModelRange.md#member-start) or [end](module_engine_model_range-ModelRange.md#member-end) position of the most recently added range. Is set to `null` if there are no ranges in selection. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L106) ### `focus: ModelPosition | null` _(readonly)_ Selection focus. Focus is a position where the selection ends. Is set to `null` if there are no ranges in selection. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L117) ### `hasOwnRange: boolean` _(readonly)_ Describes whether `Documentselection` has own range(s) set, or if it is defaulted to [document's default range](module_engine_model_document-ModelDocument.md#function-_getDefaultRange). [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L132) ### `isBackward: boolean` _(readonly)_ Specifies whether the [`focus`](#member-focus) precedes [`anchor`](#member-anchor). [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L143) ### `isCollapsed: boolean` _(readonly)_ Describes whether the selection is collapsed. Selection is collapsed when there is exactly one range which is collapsed. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L92) ### `isGravityOverridden: boolean` _(readonly)_ Describes whether the gravity is overridden (using [`overrideSelectionGravity`](module_engine_model_writer-ModelWriter.md#function-overrideSelectionGravity)) or not. Note that the gravity remains overridden as long as will not be restored the same number of times as it was overridden. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L152) ### `markers: Collection` _(readonly)_ A collection of selection [markers](module_engine_model_markercollection-Marker.md). Marker is a selection marker when selection range is inside the marker range. **Note**: Only markers from [observed markers groups](#function-observeMarkers) are collected. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L162) ### `rangeCount: number` _(readonly)_ Number of ranges in selection. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L124) ### `_ranges: Array` _(internal)_ Used for the compatibility with the [`isEqual`](module_engine_model_selection-ModelSelection.md#function-isEqual) method. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L171) ### `_selection: LiveSelection` _(private)_ Selection used internally by that class (`ModelDocumentSelection` is a proxy to that selection). [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L71) ## Methods ### `constructor( doc )` Creates an empty live selection for given [`ModelDocument`](module_engine_model_document-ModelDocument.md). [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L78) #### Parameters * `doc: ModelDocument` 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](module_engine_model_position-ModelPosition.md#function-isTouching) the element's start and ends at position touching the element's end. 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`. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L302) #### Parameters * `element: ModelElement` #### Returns * `boolean` ### `delegate( events ) → EmitterMixinDelegateChain` _(inherited)_ Delegates selected events to another [`Emitter`](module_utils_emittermixin-Emitter.md). For instance: ```typescript emitterA.delegate( 'eventX' ).to( emitterB ); emitterA.delegate( 'eventX', 'eventY' ).to( emitterC ); ``` then `eventX` is delegated (fired by) `emitterB` and `emitterC` along with `data`: ```typescript emitterA.fire( 'eventX', data ); ``` and `eventY` is delegated (fired by) `emitterC` along with `data`: ```typescript emitterA.fire( 'eventY', data ); ``` [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L539) #### Parameters * `events: Array` Event names that will be delegated to another emitter. #### Returns * `EmitterMixinDelegateChain` ### `destroy() → void` Unbinds all events previously bound by document selection. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L309) #### Returns * `void` ### `fire( eventOrInfo, args ) → GetEventInfo[ 'return' ]` _(inherited)_ Fires an event, executing all callbacks registered for it. The first parameter passed to callbacks is an [`EventInfo`](module_utils_eventinfo-EventInfo.md) object, followed by the optional `args` provided in the `fire()` method call. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L512) #### Type parameters * `TEvent: extends BaseEvent` The type describing the event. See [`BaseEvent`](module_utils_emittermixin-BaseEvent.md). #### Parameters * `eventOrInfo: GetNameOrEventInfo` The name of the event or `EventInfo` object if event is delegated. * `args: TEvent[ 'args' ]` Additional arguments to be passed to the callbacks. #### Returns * `GetEventInfo[ 'return' ]` By default the method returns `undefined`. However, the return value can be changed by listeners through modification of the [`evt.return`](module_utils_eventinfo-EventInfo.md#member-return)'s property (the event info is the first param of every callback). ### `getAttribute( key ) → unknown` Gets an attribute value for given key or `undefined` if that attribute is not set on the selection. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L336) #### Parameters * `key: string` Key of attribute to look for. #### Returns * `unknown` Attribute value or `undefined`. ### `getAttributeKeys() → IterableIterator` Returns iterable that iterates over this selection's attribute keys. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L316) #### Returns * `IterableIterator` ### `getAttributes() → IterableIterator<[ string, unknown ]>` Returns iterable that iterates over this selection's attributes. 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. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L326) #### Returns * `IterableIterator<[ string, unknown ]>` ### `getFirstPosition() → ModelPosition | null` Returns the first position in the selection. First position is the position that [is before](module_engine_model_position-ModelPosition.md#function-isBefore) any other position in the selection. Returns `null` if there are no ranges in selection. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L189) #### Returns * `ModelPosition | null` ### `getFirstRange() → ModelRange | null` Returns a copy of the first range in the selection. First range is the one which [start](module_engine_model_range-ModelRange.md#member-start) position [is before](module_engine_model_position-ModelPosition.md#function-isBefore) start position of all other ranges (not to confuse with the first range added to the selection). Returns `null` if there are no ranges in selection. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L212) #### Returns * `ModelRange | null` ### `getLastPosition() → ModelPosition | null` Returns the last position in the selection. Last position is the position that [is after](module_engine_model_position-ModelPosition.md#function-isAfter) any other position in the selection. Returns `null` if there are no ranges in selection. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L200) #### Returns * `ModelPosition | null` ### `getLastRange() → ModelRange | null` Returns a copy of the last range in the selection. Last range is the one which [end](module_engine_model_range-ModelRange.md#member-end) position [is after](module_engine_model_position-ModelPosition.md#function-isAfter) end position of all other ranges (not to confuse with the range most recently added to the selection). Returns `null` if there are no ranges in selection. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L224) #### Returns * `ModelRange | null` ### `getRanges() → IterableIterator` Returns an iterable that iterates over copies of selection ranges. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L178) #### Returns * `IterableIterator` ### `getSelectedBlocks() → IterableIterator` Gets elements of type ["block"](module_engine_model_schema-ModelSchema.md#function-isBlock) touched by the selection. 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: `
` is not a block itself): ``` [a
b
c]d ``` In this case the paragraph will also be returned, despite the collapsed selection: ``` []a ``` In such a scenario, however, only blocks A, B & E will be returned as blocks C & D are nested in block B: ``` [ ] ``` If the selection is inside a block all the inner blocks (A & B) are returned: ``` [a b] ``` **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](https://github.com/ckeditor/ckeditor5-engine/issues/984) for more details. ``` [a b ]c // this block will not be returned ``` [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L281) #### Returns * `IterableIterator` ### `getSelectedElement() → ModelElement | null` Returns the selected element. [Element](module_engine_model_element-ModelElement.md) 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](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L290) #### Returns * `ModelElement | null` ### `hasAttribute( key ) → boolean` Checks if the selection has an attribute for given key. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L346) #### Parameters * `key: string` Key of attribute to check. #### Returns * `boolean` `true` if attribute with given key is set on selection, `false` otherwise. ### `is( type ) → this is ModelElement | ModelRootElement` _(inherited)_ Checks whether the object is of type [`ModelElement`](module_engine_model_element-ModelElement.md) or its subclass. ```typescript element.is( 'element' ); // -> true element.is( 'node' ); // -> true element.is( 'model:element' ); // -> true element.is( 'model:node' ); // -> true element.is( 'view:element' ); // -> false element.is( 'documentSelection' ); // -> false ``` Assuming that the object being checked is an element, you can also check its [name](module_engine_model_element-ModelElement.md#member-name): ```typescript element.is( 'element', 'imageBlock' ); // -> true if this is an element text.is( 'element', 'imageBlock' ); -> false ``` [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/typecheckable.ts#L81) #### Parameters * `type: 'element' | 'model:element'` #### Returns * `this is ModelElement | ModelRootElement` ### `is( type ) → this is ModelText` _(inherited)_ Checks whether the object is of type [`ModelText`](module_engine_model_text-ModelText.md). ```typescript text.is( '$text' ); // -> true text.is( 'node' ); // -> true text.is( 'model:$text' ); // -> true text.is( 'model:node' ); // -> true text.is( 'view:$text' ); // -> false text.is( 'documentSelection' ); // -> false ``` **Note:** Until version 20.0.0 this method wasn't accepting `'$text'` type. The legacy `'text'` type is still accepted for backward compatibility. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/typecheckable.ts#L127) #### Parameters * `type: '$text' | 'model:$text'` #### Returns * `this is ModelText` ### `is( type ) → this is ModelRootElement` _(inherited)_ Checks whether the object is of type [`ModelRootElement`](module_engine_model_rootelement-ModelRootElement.md). ```typescript rootElement.is( 'rootElement' ); // -> true rootElement.is( 'element' ); // -> true rootElement.is( 'node' ); // -> true rootElement.is( 'model:rootElement' ); // -> true rootElement.is( 'model:element' ); // -> true rootElement.is( 'model:node' ); // -> true rootElement.is( 'view:element' ); // -> false rootElement.is( 'documentFragment' ); // -> false ``` Assuming that the object being checked is an element, you can also check its [name](module_engine_model_element-ModelElement.md#member-name): ```typescript rootElement.is( 'rootElement', '$root' ); // -> same as above ``` [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/typecheckable.ts#L107) #### Parameters * `type: 'rootElement' | 'model:rootElement'` #### Returns * `this is ModelRootElement` ### `is( type ) → this is ModelLiveRange` _(inherited)_ Checks whether the object is of type [`ModelLiveRange`](module_engine_model_liverange-ModelLiveRange.md). ```typescript liveRange.is( 'range' ); // -> true liveRange.is( 'model:range' ); // -> true liveRange.is( 'liveRange' ); // -> true liveRange.is( 'model:liveRange' ); // -> true liveRange.is( 'view:range' ); // -> false liveRange.is( 'documentSelection' ); // -> false ``` [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/typecheckable.ts#L191) #### Parameters * `type: 'liveRange' | 'model:liveRange'` #### Returns * `this is ModelLiveRange` ### `is( type ) → this is ModelRange | ModelLiveRange` _(inherited)_ Checks whether the object is of type [`ModelRange`](module_engine_model_range-ModelRange.md) or its subclass. ```typescript range.is( 'range' ); // -> true range.is( 'model:range' ); // -> true range.is( 'view:range' ); // -> false range.is( 'documentSelection' ); // -> false ``` [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/typecheckable.ts#L174) #### Parameters * `type: 'range' | 'model:range'` #### Returns * `this is ModelRange | ModelLiveRange` ### `is( type ) → this is ModelLivePosition` _(inherited)_ Checks whether the object is of type [`ModelLivePosition`](module_engine_model_liveposition-ModelLivePosition.md). ```typescript livePosition.is( 'position' ); // -> true livePosition.is( 'model:position' ); // -> true livePosition.is( 'liveposition' ); // -> true livePosition.is( 'model:livePosition' ); // -> true livePosition.is( 'view:position' ); // -> false livePosition.is( 'documentSelection' ); // -> false ``` [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/typecheckable.ts#L159) #### Parameters * `type: 'livePosition' | 'model:livePosition'` #### Returns * `this is ModelLivePosition` ### `is( type ) → this is ModelPosition | ModelLivePosition` _(inherited)_ Checks whether the object is of type [`ModelPosition`](module_engine_model_position-ModelPosition.md) or its subclass. ```typescript position.is( 'position' ); // -> true position.is( 'model:position' ); // -> true position.is( 'view:position' ); // -> false position.is( 'documentSelection' ); // -> false ``` [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/typecheckable.ts#L142) #### Parameters * `type: 'position' | 'model:position'` #### Returns * `this is ModelPosition | ModelLivePosition` ### `is( type ) → this is ModelSelection | ModelDocumentSelection` _(inherited)_ Checks whether the object is of type [`ModelSelection`](module_engine_model_selection-ModelSelection.md) or [`ModelDocumentSelection`](module_engine_model_documentselection-ModelDocumentSelection.md). ```typescript selection.is( 'selection' ); // -> true selection.is( 'model:selection' ); // -> true selection.is( 'view:selection' ); // -> false selection.is( 'range' ); // -> false ``` [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/typecheckable.ts#L223) #### Parameters * `type: 'selection' | 'model:selection'` #### Returns * `this is ModelSelection | ModelDocumentSelection` ### `is( type, name ) → boolean` _(inherited)_ Checks whether the object is of type [`ModelElement`](module_engine_model_element-ModelElement.md) or its subclass and has the specified `name`. ```typescript element.is( 'element', 'imageBlock' ); // -> true if this is an element text.is( 'element', 'imageBlock' ); -> false ``` [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/typecheckable.ts#L286) #### Type parameters * `N: extends string` #### Parameters * `type: 'element' | 'model:element'` * `name: N` #### Returns * `boolean` ### `is( type, name ) → boolean` _(inherited)_ Checks whether the object is of type [`ModelRootElement`](module_engine_model_rootelement-ModelRootElement.md) and has the specified `name`. ```typescript rootElement.is( 'rootElement', '$root' ); ``` [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/typecheckable.ts#L297) #### Type parameters * `N: extends string` #### Parameters * `type: 'rootElement' | 'model:rootElement'` * `name: N` #### Returns * `boolean` ### `is( type ) → this is ModelTextProxy` _(inherited)_ Checks whether the object is of type [`ModelTextProxy`](module_engine_model_textproxy-ModelTextProxy.md). ```typescript textProxy.is( '$textProxy' ); // -> true textProxy.is( 'model:$textProxy' ); // -> true textProxy.is( 'view:$textProxy' ); // -> false textProxy.is( 'range' ); // -> false ``` **Note:** Until version 20.0.0 this method wasn't accepting `'$textProxy'` type. The legacy `'textProxt'` type is still accepted for backward compatibility. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/typecheckable.ts#L274) #### Parameters * `type: '$textProxy' | 'model:$textProxy'` #### Returns * `this is ModelTextProxy` ### `is( type ) → this is Marker` _(inherited)_ Checks whether the object is of type [`Marker`](module_engine_model_markercollection-Marker.md). ```typescript marker.is( 'marker' ); // -> true marker.is( 'model:marker' ); // -> true marker.is( 'view:element' ); // -> false marker.is( 'documentSelection' ); // -> false ``` [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/typecheckable.ts#L256) #### Parameters * `type: 'marker' | 'model:marker'` #### Returns * `this is Marker` ### `is( type ) → this is ModelDocumentSelection` _(inherited)_ Checks whether the object is of type [`ModelDocumentSelection`](module_engine_model_documentselection-ModelDocumentSelection.md). ```typescript 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 ``` [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/typecheckable.ts#L241) #### Parameters * `type: 'documentSelection' | 'model:documentSelection'` #### Returns * `this is ModelDocumentSelection` ### `is( type ) → this is ModelDocumentFragment` _(inherited)_ Checks whether the object is of type [`ModelDocumentFragment`](module_engine_model_documentfragment-ModelDocumentFragment.md). ```typescript docFrag.is( 'documentFragment' ); // -> true docFrag.is( 'model:documentFragment' ); // -> true docFrag.is( 'view:documentFragment' ); // -> false docFrag.is( 'element' ); // -> false docFrag.is( 'node' ); // -> false ``` [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/typecheckable.ts#L207) #### Parameters * `type: 'documentFragment' | 'model:documentFragment'` #### Returns * `this is ModelDocumentFragment` ### `is( type ) → this is ModelNode | ModelText | ModelElement | ModelRootElement` _(inherited)_ Checks whether the object is of type [`ModelNode`](module_engine_model_node-ModelNode.md) or its subclass. This method is useful when processing model objects that are of unknown type. For example, a function may return a [`ModelDocumentFragment`](module_engine_model_documentfragment-ModelDocumentFragment.md) or a [`ModelNode`](module_engine_model_node-ModelNode.md) that can be either a text node or an element. This method can be used to check what kind of object is returned. ```typescript someObject.is( 'element' ); // -> true if this is an element someObject.is( 'node' ); // -> true if this is a node (a text node or an element) someObject.is( 'documentFragment' ); // -> true if this is a document fragment ``` Since this method is also available on a range of view objects, you can prefix the type of the object with `model:` or `view:` to check, for example, if this is the model's or view's element: ```typescript modelElement.is( 'model:element' ); // -> true modelElement.is( 'view:element' ); // -> false ``` By using this method it is also possible to check a name of an element: ```typescript imageElement.is( 'element', 'imageBlock' ); // -> true imageElement.is( 'element', 'imageBlock' ); // -> same as above imageElement.is( 'model:element', 'imageBlock' ); // -> same as above, but more precise ``` [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/typecheckable.ts#L56) #### Parameters * `type: 'node' | 'model:node'` #### Returns * `this is ModelNode | ModelText | ModelElement | ModelRootElement` ### `listenTo( emitter, event, callback, options? ) → void` _(inherited)_ Registers a callback function to be executed when an event is fired in a specific (emitter) object. Events can be grouped in namespaces using `:`. When namespaced event is fired, it additionally fires all callbacks for that namespace. ```typescript // 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](module_utils_eventinfo-EventInfo.md#member-stop) and set the [return value](module_utils_eventinfo-EventInfo.md#member-return) of the [`fire`](#function-fire) method. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L475) #### Type parameters * `TEvent: extends BaseEvent` The type describing the event. See [`BaseEvent`](module_utils_emittermixin-BaseEvent.md). #### Parameters * `emitter: Emitter` The object that fires the event. * `event: TEvent[ 'name' ]` The name of the event. * `callback: GetCallback` The function to be called on event. * `options?: GetCallbackOptions` Additional options. #### Returns * `void` ### `observeMarkers( prefixOrName ) → void` Registers a marker group prefix or a marker name to be collected in the [selection markers collection](#member-markers). See also [`MarkerCollection#getMarkersGroup()`](module_engine_model_markercollection-MarkerCollection.md#function-getMarkersGroup). [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L366) #### Parameters * `prefixOrName: string` The marker group prefix or marker name. #### Returns * `void` ### `off( event, callback ) → void` _(inherited)_ Stops executing the callback on the given event. Shorthand for [`this.stopListening( this, event, callback )`](#function-stopListening:BASE_STOP). [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L444) #### Parameters * `event: string` The name of the event. * `callback: Function` The function to stop being called. #### Returns * `void` ### `on( event, callback, options? ) → void` _(inherited)_ Registers a callback function to be executed when an event is fired. Shorthand for [`this.listenTo( this, event, callback, options )`](#function-listenTo:BASE_EMITTER) (it makes the emitter listen on itself). [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L416) #### Type parameters * `TEvent: extends BaseEvent` The type descibing the event. See [`BaseEvent`](module_utils_emittermixin-BaseEvent.md). #### Parameters * `event: TEvent[ 'name' ]` The name of the event. * `callback: GetCallback` The function to be called on event. * `options?: GetCallbackOptions` Additional options. #### Returns * `void` ### `once( event, callback, options? ) → void` _(inherited)_ Registers a callback function to be executed on the next time the event is fired only. This is similar to calling [`on`](#function-on) followed by [`off`](#function-off) in the callback. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L431) #### Type parameters * `TEvent: extends BaseEvent` The type descibing the event. See [`BaseEvent`](module_utils_emittermixin-BaseEvent.md). #### Parameters * `event: TEvent[ 'name' ]` The name of the event. * `callback: GetCallback` The function to be called on event. * `options?: GetCallbackOptions` Additional options. #### Returns * `void` ### `refresh() → void` Refreshes selection attributes and markers according to the current position in the model. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L353) #### Returns * `void` ### `stopDelegating( event?, emitter? ) → void` _(inherited)_ Stops delegating events. It can be used at different levels: * To stop delegating all events. * To stop delegating a specific event to all emitters. * To stop delegating a specific event to a specific emitter. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L552) #### 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. #### Returns * `void` ### `stopListening( emitter?, event?, callback? ) → void` _(inherited)_ Stops listening for events. It can be used at different levels: * 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. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L497) #### 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`. #### Returns * `void` ### `toJSON() → unknown` Converts `DocumentSelection` to plain object and returns it. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L375) #### Returns * `unknown` `DocumentSelection` converted to plain object. ### `_getStoredAttributes() → Iterable<[ string, unknown ]>` _(internal)_ Returns an iterable that iterates through all selection attributes stored in current selection's parent. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L439) #### Returns * `Iterable<[ string, unknown ]>` ### `_overrideGravity() → string` _(internal)_ Temporarily changes the gravity of the selection from the left to the right. 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. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L457) #### Returns * `string` The unique id which allows restoring the gravity. #### Related: * [ModelWriter#overrideSelectionGravity](module_engine_model_writer-ModelWriter.md#function-overrideSelectionGravity) ### `_removeAttribute( key ) → void` _(internal)_ Removes an attribute with given key from the selection. If the given attribute was set on the selection, fires the [event-change:range](module_engine_model_selection-ModelSelection.md#event-change:range) event with removed attribute key. Should be used only within the [`removeSelectionAttribute`](module_engine_model_writer-ModelWriter.md#function-removeSelectionAttribute) method. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L430) #### Parameters * `key: string` Key of the attribute to remove. #### Returns * `void` #### Related: * [ModelWriter#removeSelectionAttribute](module_engine_model_writer-ModelWriter.md#function-removeSelectionAttribute) ### `_restoreGravity( uid ) → void` _(internal)_ Restores the [overridden gravity](#function-_overrideGravity). Restoring the gravity is only possible using the unique identifier returned by [`_overrideGravity`](#function-_overrideGravity). Note that the gravity remains overridden as long as won't be restored the same number of times it was overridden. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L472) #### Parameters * `uid: string` The unique id returned by [`_overrideGravity`](#function-_overrideGravity). #### Returns * `void` #### Related: * [ModelWriter#restoreSelectionGravity](module_engine_model_writer-ModelWriter.md#function-restoreSelectionGravity) ### `_setAttribute( key, value ) → void` _(internal)_ 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`](module_engine_model_writer-ModelWriter.md#function-setSelectionAttribute:KEY_VALUE) method. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L416) #### Parameters * `key: string` Key of the attribute to set. * `value: unknown` Attribute value. #### Returns * `void` #### Related: * [ModelWriter#setSelectionAttribute](module_engine_model_writer-ModelWriter.md#function-setSelectionAttribute:KEY_VALUE) ### `_setFocus( itemOrPosition, offset? ) → void` _(internal)_ Moves [`focus`](#member-focus) to the specified location. Should be used only within the [`setSelectionFocus`](module_engine_model_writer-ModelWriter.md#function-setSelectionFocus) method. The location can be specified in the same form as [writer.createPositionAt()](module_engine_model_writer-ModelWriter.md#function-createPositionAt) parameters. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L391) #### Parameters * `itemOrPosition: ModelPosition | ModelItem` * `offset?: ModelPositionOffset` Offset or one of the flags. Used only when first parameter is a [model item](module_engine_model_item-ModelItem.md). #### Returns * `void` #### Related: * [ModelWriter#setSelectionFocus](module_engine_model_writer-ModelWriter.md#function-setSelectionFocus) ### `_setTo( args ) → void` _(internal)_ Sets this selection's ranges and direction to the specified location based on the given [selectable](module_engine_model_selection-ModelSelectable.md). Should be used only within the [`setSelection`](module_engine_model_writer-ModelWriter.md#function-setSelection:NODE_OFFSET) method. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L403) #### Parameters * `args: [ selectable: ModelNode, placeOrOffset: ModelPlaceOrOffset, options?: object ] | [ selectable?: ModelPosition | ModelRange | ModelSelection | ModelDocumentSelection | Iterable | null, options?: object ]` #### Returns * `void` #### Related: * [ModelWriter#setSelection](module_engine_model_writer-ModelWriter.md#function-setSelection:NODE_OFFSET) #### Static methods ### `_dropStoreAttributeKeyPrefix( key ) → string` _(internal)_ Drop selection attribute key prefix. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L501) #### Parameters * `key: string` #### Returns * `string` ### `_getStoreAttributeKey( key ) → string` _(internal)_ Generates and returns an attribute key for selection attributes store, basing on original attribute key. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L483) #### Parameters * `key: string` Attribute key to convert. #### Returns * `string` Converted attribute key, applicable for selection store. ### `_isStoreAttributeKey( key ) → boolean` _(internal)_ Checks whether the given attribute key is an attribute stored on an element. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L492) #### Parameters * `key: string` #### Returns * `boolean` ## Events ### `change( eventInfo, directChange = { directChange.attributeKeys?, directChange.directChange, directChange.oldMarkers? } )` Fired when selection range(s), attribute(s) or marker(s) changed. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L577) #### Parameters * `eventInfo: EventInfo` An object containing information about the fired event. * `directChange: object` This is always set to `false` in case of `change:marker` event as there is no possibility to change markers directly through [`ModelDocumentSelection`](module_engine_model_documentselection-ModelDocumentSelection.md) API. See also [event-change:range](#event-change:range) and [event-change:attribute](#event-change:attribute). Properties * `directChange.attributeKeys?: Array` * `directChange.directChange: boolean` * `directChange.oldMarkers?: Array` ### `change:attribute( eventInfo, directChange = { directChange.attributeKeys, directChange.directChange } )` Fired when selection attribute changed. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L546) #### Parameters * `eventInfo: EventInfo` An object containing information about the fired event. * `directChange: object` In case of [`ModelSelection`](module_engine_model_selection-ModelSelection.md) class it is always set to `true` which indicates that the selection change was caused by a direct use of selection's API. The [`ModelDocumentSelection`](module_engine_model_documentselection-ModelDocumentSelection.md), however, may change because its attributes were directly changed through the [writer](module_engine_model_writer-ModelWriter.md) 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. Properties * `directChange.attributeKeys: Array` * `directChange.directChange: boolean` ### `change:marker( eventInfo, directChange = { directChange.directChange, directChange.oldMarkers } )` Fired when selection marker(s) changed. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L558) #### Parameters * `eventInfo: EventInfo` An object containing information about the fired event. * `directChange: object` This is always set to `false` in case of `change:marker` event as there is no possibility to change markers directly through [`ModelDocumentSelection`](module_engine_model_documentselection-ModelDocumentSelection.md) API. See also [event-change:range](#event-change:range) and [event-change:attribute](#event-change:attribute). Properties * `directChange.directChange: boolean` * `directChange.oldMarkers: Array` ### `change:range( eventInfo, directChange = { directChange.directChange } )` Fired when selection range(s) changed. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/documentselection.ts#L531) #### Parameters * `eventInfo: EventInfo` An object containing information about the fired event. * `directChange: object` In case of [`ModelSelection`](module_engine_model_selection-ModelSelection.md) class it is always set to `true` which indicates that the selection change was caused by a direct use of selection's API. The [`ModelDocumentSelection`](module_engine_model_documentselection-ModelDocumentSelection.md), however, may change because its position was directly changed through the [writer](module_engine_model_writer-ModelWriter.md) 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. Properties * `directChange.directChange: boolean` --- Full index of the CKEditor 5 API reference: [llms.txt](llms.txt)