# ModelLiveRange class `ModelLiveRange` is a type of [Range](module_engine_model_range-ModelRange.md) that updates itself as [document](module_engine_model_document-ModelDocument.md) is changed through operations. It may be used as a bookmark. **Note:** Be very careful when dealing with `ModelLiveRange`. Each `ModelLiveRange` instance bind events that might have to be unbound. Use [detach](#function-detach) whenever you don't need `ModelLiveRange` anymore. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/liverange.ts#L34) ## Properties ### `end: ModelPosition` _(readonly)_ End position. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L45) ### `isCollapsed: boolean` _(readonly)_ Describes whether the range is collapsed, that is if [`start`](#member-start) and [`end`](#member-end) positions are equal. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L85) ### `isFlat: boolean` _(readonly)_ Describes whether this range is flat, that is if [`start`](#member-start) position and [`end`](#member-end) position are in the same [`parent`](module_engine_model_position-ModelPosition.md#member-parent). [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L93) ### `root: ModelElement | ModelDocumentFragment` _(readonly)_ Range root element. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L103) ### `start: ModelPosition` _(readonly)_ Start position. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L40) #### Static properties ### `_createFromPositionAndShift: ( position: ModelPosition, shift: number ) => ModelLiveRange` _(internal)_ [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/liverange.ts#L113) #### Related: * ModelRange.\_createFromPositionAndShift ### `_createIn: ( element: ModelElement | ModelDocumentFragment ) => ModelLiveRange` _(internal)_ [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/liverange.ts#L99) #### Related: * ModelRange.\_createIn ### `_createOn: ( element: ModelDocumentFragment | ModelItem ) => ModelLiveRange` _(internal)_ [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/liverange.ts#L106) #### Related: * ModelRange.\_createOn ## Methods ### `constructor( start, end?, model? )` Creates a live range. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/liverange.ts#L40) #### Parameters * `start: ModelPosition` * `end?: ModelPosition | null` * `model?: Model` #### Related: * [ModelRange](module_engine_model_range-ModelRange.md) ### `Symbol.iterator() → IterableIterator` _(inherited)_ Iterable interface. Iterates over all [items](module_engine_model_item-ModelItem.md) that are in this range and returns them together with additional information like length or [positions](module_engine_model_position-ModelPosition.md), grouped as [`ModelTreeWalkerValue`](module_engine_model_treewalker-ModelTreeWalkerValue.md). It iterates over all [text contents](module_engine_model_textproxy-ModelTextProxy.md) that are inside the range and all the [`ModelElement`](module_engine_model_element-ModelElement.md)s that are entered into when iterating over this range. This iterator uses [`ModelTreeWalker`](module_engine_model_treewalker-ModelTreeWalker.md) with `boundaries` set to this range and `ignoreElementEnd` option set to `true`. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L77) #### Returns * `IterableIterator` ### `clone() → this` _(inherited)_ Returns a new range that is equal to current range. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L589) #### Returns * `this` ### `containsItem( item ) → boolean` _(inherited)_ Checks whether given [`ModelItem`](module_engine_model_item-ModelItem.md) is inside this range. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L142) #### Parameters * `item: ModelItem` #### Returns * `boolean` ### `containsPosition( position ) → boolean` _(inherited)_ Checks whether this range contains given [position](module_engine_model_position-ModelPosition.md). [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L114) #### Parameters * `position: ModelPosition` Position to check. #### Returns * `boolean` `true` if given [position](module_engine_model_position-ModelPosition.md) is contained in this range,`false` otherwise. ### `containsRange( otherRange, loose ) → boolean` _(inherited)_ Checks whether this range contains given [range](module_engine_model_range-ModelRange.md). [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L128) #### Parameters * `otherRange: ModelRange` Range to check. * `loose: boolean` Whether the check is loose or strict. If the check is strict (`false`), compared range cannot start or end at the same position as this range boundaries. If the check is loose (`true`), compared range can start, end or even be equal to this range. Note that collapsed ranges are always compared in strict mode. Defaults to `false` #### Returns * `boolean` `true` if given [range](module_engine_model_range-ModelRange.md) boundaries are contained by this range, `false` otherwise. ### `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` ### `detach() → void` Unbinds all events previously bound by `ModelLiveRange`. Use it whenever you don't need `ModelLiveRange` instance anymore (i.e. when leaving scope in which it was declared or before re-assigning variable that was referring to it). [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/liverange.ts#L63) #### 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). ### `getCommonAncestor() → ModelElement | ModelDocumentFragment | null` _(inherited)_ Returns an [`ModelElement`](module_engine_model_element-ModelElement.md) or [`ModelDocumentFragment`](module_engine_model_documentfragment-ModelDocumentFragment.md) which is a common ancestor of the range's both ends (in which the entire range is contained). [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L550) #### Returns * `ModelElement | ModelDocumentFragment | null` ### `getContainedElement() → ModelElement | null` _(inherited)_ Returns an [Element](module_engine_model_element-ModelElement.md) contained by the range. The element will be returned when it is the **only** node within the range and **fully–contained** at the same time. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L559) #### Returns * `ModelElement | null` ### `getDifference( otherRange ) → Array` _(inherited)_ Computes which part(s) of this [range](module_engine_model_range-ModelRange.md) is not a part of given [range](module_engine_model_range-ModelRange.md). Returned array contains zero, one or two [ranges](module_engine_model_range-ModelRange.md). Examples: ```typescript let range = model.createRange( model.createPositionFromPath( root, [ 2, 7 ] ), model.createPositionFromPath( root, [ 4, 0, 1 ] ) ); let otherRange = model.createRange( model.createPositionFromPath( root, [ 1 ] ), model.createPositionFromPath( root, [ 5 ] ) ); let transformed = range.getDifference( otherRange ); // transformed array has no ranges because `otherRange` contains `range` otherRange = model.createRange( model.createPositionFromPath( root, [ 1 ] ), model.createPositionFromPath( root, [ 3 ] ) ); transformed = range.getDifference( otherRange ); // transformed array has one range: from [ 3 ] to [ 4, 0, 1 ] otherRange = model.createRange( model.createPositionFromPath( root, [ 3 ] ), model.createPositionFromPath( root, [ 4 ] ) ); transformed = range.getDifference( otherRange ); // transformed array has two ranges: from [ 2, 7 ] to [ 3 ] and from [ 4 ] to [ 4, 0, 1 ] ``` [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L196) #### Parameters * `otherRange: ModelRange` Range to differentiate against. #### Returns * `Array` The difference between ranges. ### `getIntersection( otherRange ) → ModelRange | null` _(inherited)_ Returns an intersection of this [range](module_engine_model_range-ModelRange.md) and given [range](module_engine_model_range-ModelRange.md). Intersection is a common part of both of those ranges. If ranges has no common part, returns `null`. Examples: ```typescript let range = model.createRange( model.createPositionFromPath( root, [ 2, 7 ] ), model.createPositionFromPath( root, [ 4, 0, 1 ] ) ); let otherRange = model.createRange( model.createPositionFromPath( root, [ 1 ] ), model.createPositionFromPath( root, [ 2 ] ) ); let transformed = range.getIntersection( otherRange ); // null - ranges have no common part otherRange = model.createRange( model.createPositionFromPath( root, [ 3 ] ), model.createPositionFromPath( root, [ 5 ] ) ); transformed = range.getIntersection( otherRange ); // range from [ 3 ] to [ 4, 0, 1 ] ``` [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L243) #### Parameters * `otherRange: ModelRange` Range to check for intersection. #### Returns * `ModelRange | null` A common part of given ranges or `null` if ranges have no common part. ### `getItems( options ) → IterableIterator` _(inherited)_ Returns an iterator that iterates over all [items](module_engine_model_item-ModelItem.md) that are in this range and returns them. This method uses [`ModelTreeWalker`](module_engine_model_treewalker-ModelTreeWalker.md) with `boundaries` set to this range and `ignoreElementEnd` option set to `true`. However it returns only [model items](module_engine_model_item-ModelItem.md), not [`ModelTreeWalkerValue`](module_engine_model_treewalker-ModelTreeWalkerValue.md). You may specify additional options for the tree walker. See [`ModelTreeWalker`](module_engine_model_treewalker-ModelTreeWalker.md) for a full list of available options. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L444) #### Parameters * `options: ModelTreeWalkerOptions` Object with configuration options. See [`ModelTreeWalker`](module_engine_model_treewalker-ModelTreeWalker.md). Defaults to `{}` #### Returns * `IterableIterator` ### `getJoined( otherRange, loose ) → ModelRange | null` _(inherited)_ Returns a range created by joining this [range](module_engine_model_range-ModelRange.md) with the given [range](module_engine_model_range-ModelRange.md). If ranges have no common part, returns `null`. Examples: ```typescript let range = model.createRange( model.createPositionFromPath( root, [ 2, 7 ] ), model.createPositionFromPath( root, [ 4, 0, 1 ] ) ); let otherRange = model.createRange( model.createPositionFromPath( root, [ 1 ] ), model.createPositionFromPath( root, [ 2 ] ) * ); let transformed = range.getJoined( otherRange ); // null - ranges have no common part otherRange = model.createRange( model.createPositionFromPath( root, [ 3 ] ), model.createPositionFromPath( root, [ 5 ] ) ); transformed = range.getJoined( otherRange ); // range from [ 2, 7 ] to [ 5 ] ``` [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L300) #### Parameters * `otherRange: ModelRange` Range to be joined. * `loose: boolean` Whether the intersection check is loose or strict. If the check is strict (`false`), ranges are tested for intersection or whether start/end positions are equal. If the check is loose (`true`), compared range is also checked if it's [touching](module_engine_model_position-ModelPosition.md#function-isTouching) current range. Defaults to `false` #### Returns * `ModelRange | null` A sum of given ranges or `null` if ranges have no common part. ### `getMinimalFlatRanges() → Array` _(inherited)_ Computes and returns the smallest set of [flat](#member-isFlat) ranges, that covers this range in whole. See an example of a model structure (`[` and `]` are range boundaries): ``` root root |- element DIV DIV P2 P3 DIV | |- element H H P1 f o o b a r H P4 | | |- "fir[st" fir[st lorem se]cond ipsum | |- element P1 | | |- "lorem" || |- element P2 || | |- "foo" VV |- element P3 | |- "bar" root |- element DIV DIV [P2 P3] DIV | |- element H H [P1] f o o b a r H P4 | | |- "se]cond" fir[st] lorem [se]cond ipsum | |- element P4 | | |- "ipsum" ``` As it can be seen, letters contained in the range are: `stloremfoobarse`, spread across different parents. We are looking for minimal set of flat ranges that contains the same nodes. Minimal flat ranges for above range `( [ 0, 0, 3 ], [ 3, 0, 2 ] )` will be: ``` ( [ 0, 0, 3 ], [ 0, 0, 5 ] ) = "st" ( [ 0, 1 ], [ 0, 2 ] ) = element P1 ("lorem") ( [ 1 ], [ 3 ] ) = element P2, element P3 ("foobar") ( [ 3, 0, 0 ], [ 3, 0, 2 ] ) = "se" ``` **Note:** if an [element](module_engine_model_element-ModelElement.md) is not wholly contained in this range, it won't be returned in any of the returned flat ranges. See in the example how `H` elements at the beginning and at the end of the range were omitted. Only their parts that were wholly in the range were returned. **Note:** this method is not returning flat ranges that contain no nodes. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L372) #### Returns * `Array` Array of flat ranges covering this range. ### `getPositions( options ) → IterableIterator` _(inherited)_ Returns an iterator that iterates over all [positions](module_engine_model_position-ModelPosition.md) that are boundaries or contained in this range. This method uses [`ModelTreeWalker`](module_engine_model_treewalker-ModelTreeWalker.md) with `boundaries` set to this range. However it returns only [positions](module_engine_model_position-ModelPosition.md), not [`ModelTreeWalkerValue`](module_engine_model_treewalker-ModelTreeWalkerValue.md). You may specify additional options for the tree walker. See [`ModelTreeWalker`](module_engine_model_treewalker-ModelTreeWalker.md) for a full list of available options. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L467) #### Parameters * `options: ModelTreeWalkerOptions` Object with configuration options. See [`ModelTreeWalker`](module_engine_model_treewalker-ModelTreeWalker.md). Defaults to `{}` #### Returns * `IterableIterator` ### `getTransformedByOperation( operation ) → Array` _(inherited)_ Returns a range that is a result of transforming this range by given `operation`. **Note:** transformation may break one range into multiple ranges (for example, when a part of the range is moved to a different part of document tree). For this reason, an array is returned by this method and it may contain one or more `Range` instances. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L489) #### Parameters * `operation: Operation` Operation to transform range by. #### Returns * `Array` Range which is the result of transformation. ### `getTransformedByOperations( operations ) → Array` _(inherited)_ Returns a range that is a result of transforming this range by multiple `operations`. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L515) #### Parameters * `operations: Iterable` Operations to transform the range by. #### Returns * `Array` Range which is the result of transformation. #### Related: * [ModelRange#getTransformedByOperation](module_engine_model_range-ModelRange.md#function-getTransformedByOperation) ### `getWalker( options ) → ModelTreeWalker` _(inherited)_ Creates a [TreeWalker](module_engine_model_treewalker-ModelTreeWalker.md) instance with this range as a boundary. For example, to iterate over all items in the entire document root: ```typescript // Create a range spanning over the entire root content: const range = editor.model.createRangeIn( editor.model.document.getRoot() ); // Iterate over all items in this range: for ( const value of range.getWalker() ) { console.log( value.item ); } ``` [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L425) #### Parameters * `options: ModelTreeWalkerOptions` Object with configuration options. See [`ModelTreeWalker`](module_engine_model_treewalker-ModelTreeWalker.md). Defaults to `{}` #### Returns * `ModelTreeWalker` ### `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 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 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 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 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 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` ### `isEqual( otherRange ) → boolean` _(inherited)_ Two ranges are equal if their [`start`](#member-start) and [`end`](#member-end) positions are equal. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L154) #### Parameters * `otherRange: ModelRange` Range to compare with. #### Returns * `boolean` `true` if ranges are equal, `false` otherwise. ### `isIntersecting( otherRange ) → boolean` _(inherited)_ Checks and returns whether this range intersects with given range. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L164) #### Parameters * `otherRange: ModelRange` Range to compare with. #### Returns * `boolean` `true` if ranges intersect, `false` otherwise. ### `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` ### `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` ### `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` _(inherited)_ Converts `Range` to plain object and returns it. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L579) #### Returns * `unknown` `Range` converted to plain object. ### `toRange() → ModelRange` Creates a [range instance](module_engine_model_range-ModelRange.md) that is equal to this live range. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/liverange.ts#L70) #### Returns * `ModelRange` ### `_getTransformedByDeletion( deletePosition, howMany ) → ModelRange | null` _(internal)_ Returns a copy of this range that is transformed by deletion of `howMany` nodes from `deletePosition`. If the deleted range is intersecting with the transformed range, the transformed range will be shrank. If the deleted range contains transformed range, `null` will be returned. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L897) #### Parameters * `deletePosition: ModelPosition` Position from which nodes are removed. * `howMany: number` How many nodes are removed. #### Returns * `ModelRange | null` Result of the transformation. ### `_getTransformedByDetachOperation( operation ) → Array` _(internal)_ Returns a result of transforming a copy of this range by detach operation. If the range is completely removed, an empty array is returned. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L731) #### Parameters * `operation: DetachOperation` #### Returns * `Array` ### `_getTransformedByInsertOperation( operation, spread ) → Array` _(internal)_ Returns a result of transforming a copy of this range by insert operation. One or more ranges may be returned as a result of this transformation. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L600) #### Parameters * `operation: InsertOperation` * `spread: boolean` Defaults to `false` #### Returns * `Array` ### `_getTransformedByInsertion( insertPosition, howMany, spread ) → Array` _(internal)_ Returns an array containing one or two [ranges](module_engine_model_range-ModelRange.md) that are a result of transforming this [range](module_engine_model_range-ModelRange.md) by inserting `howMany` nodes at `insertPosition`. Two [ranges](module_engine_model_range-ModelRange.md) are returned if the insertion was inside this [range](module_engine_model_range-ModelRange.md) and `spread` is set to `true`. Examples: ```typescript let range = model.createRange( model.createPositionFromPath( root, [ 2, 7 ] ), model.createPositionFromPath( root, [ 4, 0, 1 ] ) ); let transformed = range._getTransformedByInsertion( model.createPositionFromPath( root, [ 1 ] ), 2 ); // transformed array has one range from [ 4, 7 ] to [ 6, 0, 1 ] transformed = range._getTransformedByInsertion( model.createPositionFromPath( root, [ 4, 0, 0 ] ), 4 ); // transformed array has one range from [ 2, 7 ] to [ 4, 0, 5 ] transformed = range._getTransformedByInsertion( model.createPositionFromPath( root, [ 3, 2 ] ), 4 ); // transformed array has one range, which is equal to original range transformed = range._getTransformedByInsertion( model.createPositionFromPath( root, [ 3, 2 ] ), 4, true ); // transformed array has two ranges: from [ 2, 7 ] to [ 3, 2 ] and from [ 3, 6 ] to [ 4, 0, 1 ] ``` [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L770) #### Parameters * `insertPosition: ModelPosition` Position where nodes are inserted. * `howMany: number` How many nodes are inserted. * `spread: boolean` Flag indicating whether this range should be spread if insertion was inside the range. Defaults to `false`. Defaults to `false` #### Returns * `Array` Result of the transformation. ### `_getTransformedByMergeOperation( operation ) → ModelRange` _(internal)_ Returns a result of transforming a copy of this range by merge operation. Always one range is returned. The transformation is done in a way to not break the range. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L651) #### Parameters * `operation: MergeOperation` #### Returns * `ModelRange` ### `_getTransformedByMove( sourcePosition, targetPosition, howMany, spread ) → Array` _(internal)_ Returns an array containing [ranges](module_engine_model_range-ModelRange.md) that are a result of transforming this [range](module_engine_model_range-ModelRange.md) by moving `howMany` nodes from `sourcePosition` to `targetPosition`. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L804) #### Parameters * `sourcePosition: ModelPosition` Position from which nodes are moved. * `targetPosition: ModelPosition` Position to where nodes are moved. * `howMany: number` How many nodes are moved. * `spread: boolean` Whether the range should be spread if the move points inside the range. Defaults to `false` #### Returns * `Array` Result of the transformation. ### `_getTransformedByMoveOperation( operation, spread ) → Array` _(internal)_ Returns a result of transforming a copy of this range by move operation. One or more ranges may be returned as a result of this transformation. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L611) #### Parameters * `operation: MoveOperation` * `spread: boolean` Defaults to `false` #### Returns * `Array` ### `_getTransformedBySplitOperation( operation ) → ModelRange` _(internal)_ Returns a result of transforming a copy of this range by split operation. Always one range is returned. The transformation is done in a way to not break the range. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L626) #### Parameters * `operation: SplitOperation` #### Returns * `ModelRange` #### Static methods ### `fromJSON( json, doc ) → ModelRange` _(inherited)_ Creates a `Range` instance from given plain object (i.e. parsed JSON string). [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L1035) #### Parameters * `json: any` Plain object to be converted to `Range`. * `doc: ModelDocument` Document object that will be range owner. #### Returns * `ModelRange` `Range` instance created using given plain object. ### `fromRange( range ) → ModelLiveRange` _(static)_ Creates a `ModelLiveRange` instance that is equal to the given range. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/liverange.ts#L77) #### Parameters * `range: ModelRange` #### Returns * `ModelLiveRange` ### `_createFromRanges( ranges ) → ModelRange` _(internal)_ Combines all ranges from the passed array into a one range. At least one range has to be passed. Passed ranges must not have common parts. The first range from the array is a reference range. If other ranges start or end on the exactly same position where the reference range, they get combined into one range. ``` [ ][] [ ][ ][ ][ ][] [ ] // Passed ranges, shown sorted [ ] // The result of the function if the first range was a reference range. [ ] // The result of the function if the third-to-seventh range was a reference range. [ ] // The result of the function if the last range was a reference range. ``` [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/range.ts#L969) #### Parameters * `ranges: Array` Ranges to combine. #### Returns * `ModelRange` Combined range. ### `_fromRangeInDocumentFragment( range, model ) → ModelLiveRange` _(internal)_ Creates a `ModelLiveRange` for a range rooted in a [document fragment](module_engine_model_documentfragment-ModelDocumentFragment.md). Document fragment does not belong to a document, so the live range is bound to the provided `model` and keeps itself in sync with every operation applied to that fragment (e.g. while editing clipboard content). [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/liverange.ts#L90) #### Parameters * `range: ModelRange` * `model: Model` #### Returns * `ModelLiveRange` ## Events ### `change( eventInfo, range, data )` Describes `change:range` or `change:content` event. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/liverange.ts#L175) #### Parameters * `eventInfo: EventInfo` An object containing information about the fired event. * `range: ModelRange` * `data: object` ### `change:content( eventInfo, range, data )` Fired when `ModelLiveRange` instance boundaries have not changed after a change in [document](module_engine_model_document-ModelDocument.md) but the change took place inside the range, effectively changing its content. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/liverange.ts#L165) #### Parameters * `eventInfo: EventInfo` An object containing information about the fired event. * `range: ModelRange` Range with start and end position equal to start and end position of change range. * `data: object` Object with additional information about the change. ### `change:drop( eventInfo, range, data )` Fired when `ModelLiveRange` instance was entirely removed from the document fragment. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/liverange.ts#L148) #### Parameters * `eventInfo: EventInfo` An object containing information about the fired event. * `range: ModelRange` Collapsed range with start and end position equal to the source position of the detach operation. * `data: object` Object with additional information about the change. ### `change:range( eventInfo, range, data )` Fired when `ModelLiveRange` instance boundaries have changed due to changes in the [document](module_engine_model_document-ModelDocument.md). [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/liverange.ts#L135) #### Parameters * `eventInfo: EventInfo` An object containing information about the fired event. * `range: ModelRange` * `data: object` Object with additional information about the change. --- Full index of the CKEditor 5 API reference: [llms.txt](llms.txt)