ModelLiveRange (engine/model)

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

class

ModelLiveRange is a type of Range that updates itself as document 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 whenever you don't need ModelLiveRange anymore.

Filtering

Public
Inherited
Internal
Protected
Private
Deprecated

Properties

readonly inherited
end : ModelPosition

See source
End position.
readonly inherited
isCollapsed : boolean

See source
Describes whether the range is collapsed, that is if start and end positions are equal.
readonly inherited
isFlat : boolean

See source
Describes whether this range is flat, that is if start position and end position are in the same parent.
readonly inherited
root : ModelElement | ModelDocumentFragment

See source
Range root element.
readonly inherited
start : ModelPosition

See source
Start position.

Static properties

internal readonly static
_createFromPositionAndShift : ( position: ModelPosition, shift: number ) => ModelLiveRange
See source

Related:
- ModelRange._createFromPositionAndShift
internal readonly static
_createIn : ( element: ModelElement | ModelDocumentFragment ) => ModelLiveRange
See source

Related:
- ModelRange._createIn
internal readonly static
_createOn : ( element: ModelDocumentFragment | ModelItem ) => ModelLiveRange
See source

Related:
- ModelRange._createOn

Methods

constructor( start, [ end ] )
See source
Creates a live range.

Parameters

start : ModelPosition

[ end ] : null | ModelPosition

Related:
- ModelRange
inherited
Symbol.iterator() → IterableIterator<ModelTreeWalkerValue>

See source
Iterable interface.

Iterates over all items that are in this range and returns them together with additional information like length or positions, grouped as ModelTreeWalkerValue. It iterates over all text contents that are inside the range and all the ModelElements that are entered into when iterating over this range.

This iterator uses ModelTreeWalker with boundaries set to this range and ignoreElementEnd option set to true.

Returns

IterableIterator<ModelTreeWalkerValue>
inherited
clone() → this

See source
Returns a new range that is equal to current range.

Returns

this
inherited
containsItem( item ) → boolean

See source
Checks whether given ModelItem is inside this range.

Parameters

item : ModelItem

Returns

boolean
inherited
containsPosition( position ) → boolean

See source
Checks whether this range contains given position.

Parameters

position : ModelPosition

Position to check.

Returns

boolean

true if given position is contained in this range,false otherwise.
inherited
containsRange( otherRange, loose ) → boolean

See source
Checks whether this range contains given range.

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 boundaries are contained by this range, false otherwise.
inherited
delegate( events ) → EmitterMixinDelegateChain
See source
Delegates selected events to another Emitter. For instance:
```
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 : Array<string>

Event names that will be delegated to another emitter.

Returns

EmitterMixinDelegateChain
detach() → void

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

Returns

void
inherited
fire( eventOrInfo, args ) → GetEventInfo<TEvent>[ 'return' ]

See source
Fires an event, executing all callbacks registered for it.

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

Type parameters

TEvent : extends BaseEvent

The type describing the event. See BaseEvent.

Parameters

eventOrInfo : GetNameOrEventInfo<TEvent>

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<TEvent>[ 'return' ]

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).
inherited
getCommonAncestor() → null | ModelElement | ModelDocumentFragment

See source
Returns an ModelElement or ModelDocumentFragment which is a common ancestor of the range's both ends (in which the entire range is contained).

Returns

null | ModelElement | ModelDocumentFragment
inherited
getContainedElement() → null | ModelElement

See source
Returns an Element 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.

Returns

null | ModelElement

inherited
`getDifference( otherRange ) → Array<ModelRange>`

See source

Computes which part(s) of this range is not a part of given range. Returned array contains zero, one or two ranges.

Examples:

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 ]

Parameters

otherRange : ModelRange: Range to differentiate against.

Returns

Array<ModelRange>: The difference between ranges.

inherited
`getIntersection( otherRange ) → null | ModelRange`

See source

Returns an intersection of this range and given range. Intersection is a common part of both of those ranges. If ranges has no common part, returns null.

Examples:

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 ]

Parameters

otherRange : ModelRange: Range to check for intersection.

Returns

null | ModelRange: A common part of given ranges or null if ranges have no common part.

inherited
getItems( options ) → IterableIterator<ModelItem>

See source
Returns an iterator that iterates over all items that are in this range and returns them.

This method uses ModelTreeWalker with boundaries set to this range and ignoreElementEnd option set to true. However it returns only model items, not ModelTreeWalkerValue.

You may specify additional options for the tree walker. See ModelTreeWalker for a full list of available options.

Parameters

options : ModelTreeWalkerOptions

Object with configuration options. See ModelTreeWalker.

Defaults to {}

Returns

IterableIterator<ModelItem>
inherited
getJoined( otherRange, loose ) → null | ModelRange
See source
Returns a range created by joining this range with the given range. If ranges have no common part, returns null.

Examples:
```
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 ]
```
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 current range.

Defaults to false

Returns

null | ModelRange

A sum of given ranges or null if ranges have no common part.

inherited
`getMinimalFlatRanges() → Array<ModelRange>`

See source

Computes and returns the smallest set of flat 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 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.

Returns

Array<ModelRange>: Array of flat ranges covering this range.

inherited
getPositions( options ) → IterableIterator<ModelPosition>

See source
Returns an iterator that iterates over all positions that are boundaries or contained in this range.

This method uses ModelTreeWalker with boundaries set to this range. However it returns only positions, not ModelTreeWalkerValue.

You may specify additional options for the tree walker. See ModelTreeWalker for a full list of available options.

Parameters

options : ModelTreeWalkerOptions

Object with configuration options. See ModelTreeWalker.

Defaults to {}

Returns

IterableIterator<ModelPosition>
inherited
getTransformedByOperation( operation ) → Array<ModelRange>

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

Parameters

operation : Operation

Operation to transform range by.

Returns

Array<ModelRange>

Range which is the result of transformation.
inherited
getTransformedByOperations( operations ) → Array<ModelRange>
See source
Returns a range that is a result of transforming this range by multiple operations.

Parameters

operations : Iterable<Operation>

Operations to transform the range by.

Returns

Array<ModelRange>

Range which is the result of transformation.

Related:
- ModelRange#getTransformedByOperation
inherited
getWalker( options ) → ModelTreeWalker
See source
Creates a TreeWalker instance with this range as a boundary.

For example, to iterate over all items in the entire document root:
```
// 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 );
}
```
Parameters

options : ModelTreeWalkerOptions

Object with configuration options. See ModelTreeWalker.

Defaults to {}

Returns

ModelTreeWalker
inherited
is( type ) → this is ModelElement | ModelRootElement
See source
Checks whether the object is of type ModelElement or its subclass.
```
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:
```
element.is( 'element', 'imageBlock' ); // -> true if this is an <imageBlock> element
text.is( 'element', 'imageBlock' ); -> false
```
Parameters

type : 'element' | 'model:element'

Returns

this is ModelElement | ModelRootElement
inherited
is( type ) → this is ModelText
See source
Checks whether the object is of type ModelText.
```
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.

Parameters

type : '$text' | 'model:$text'

Returns

this is ModelText

inherited
`is( type ) → this is ModelRootElement`

See source

Checks whether the object is of type ModelRootElement.

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:

rootElement.is( 'rootElement', '$root' ); // -> same as above

Parameters

type : 'rootElement' | 'model:rootElement'

Returns

this is ModelRootElement

inherited
is( type ) → this is ModelRange | ModelLiveRange
See source
Checks whether the object is of type ModelRange or its subclass.
```
range.is( 'range' ); // -> true
range.is( 'model:range' ); // -> true

range.is( 'view:range' ); // -> false
range.is( 'documentSelection' ); // -> false
```
Parameters

type : 'range' | 'model:range'

Returns

this is ModelRange | ModelLiveRange
inherited
is( type ) → this is ModelDocumentFragment
See source
Checks whether the object is of type ModelDocumentFragment.
```
docFrag.is( 'documentFragment' ); // -> true
docFrag.is( 'model:documentFragment' ); // -> true

docFrag.is( 'view:documentFragment' ); // -> false
docFrag.is( 'element' ); // -> false
docFrag.is( 'node' ); // -> false
```
Parameters

type : 'documentFragment' | 'model:documentFragment'

Returns

this is ModelDocumentFragment
inherited
is( type ) → this is ModelLiveRange
See source
Checks whether the object is of type ModelLiveRange.
```
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
```
Parameters

type : 'liveRange' | 'model:liveRange'

Returns

this is ModelLiveRange
inherited
is( type ) → this is ModelLivePosition
See source
Checks whether the object is of type ModelLivePosition.
```
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
```
Parameters

type : 'livePosition' | 'model:livePosition'

Returns

this is ModelLivePosition
inherited
is( type ) → this is ModelPosition | ModelLivePosition
See source
Checks whether the object is of type ModelPosition or its subclass.
```
position.is( 'position' ); // -> true
position.is( 'model:position' ); // -> true

position.is( 'view:position' ); // -> false
position.is( 'documentSelection' ); // -> false
```
Parameters

type : 'position' | 'model:position'

Returns

this is ModelPosition | ModelLivePosition
inherited
is( type ) → this is ModelDocumentSelection
See source
Checks whether the object is of type ModelDocumentSelection.
```
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
```
Parameters

type : 'documentSelection' | 'model:documentSelection'

Returns

this is ModelDocumentSelection
inherited
is( type, name ) → boolean
See source
Checks whether the object is of type ModelRootElement and has the specified name.
```
rootElement.is( 'rootElement', '$root' );
```
Type parameters

N : extends string

Parameters

type : 'rootElement' | 'model:rootElement'

name : N

Returns

boolean
inherited
is( type, name ) → boolean
See source
Checks whether the object is of type ModelElement or its subclass and has the specified name.
```
element.is( 'element', 'imageBlock' ); // -> true if this is an <imageBlock> element
text.is( 'element', 'imageBlock' ); -> false
```
Type parameters

N : extends string

Parameters

type : 'element' | 'model:element'

name : N

Returns

boolean
inherited
is( type ) → this is ModelTextProxy
See source
Checks whether the object is of type ModelTextProxy.
```
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.

Parameters

type : '$textProxy' | 'model:$textProxy'

Returns

this is ModelTextProxy
inherited
is( type ) → this is Marker
See source
Checks whether the object is of type Marker.
```
marker.is( 'marker' ); // -> true
marker.is( 'model:marker' ); // -> true

marker.is( 'view:element' ); // -> false
marker.is( 'documentSelection' ); // -> false
```
Parameters

type : 'marker' | 'model:marker'

Returns

this is Marker
inherited
is( type ) → this is ModelSelection | ModelDocumentSelection
See source
Checks whether the object is of type ModelSelection or ModelDocumentSelection.
```
selection.is( 'selection' ); // -> true
selection.is( 'model:selection' ); // -> true

selection.is( 'view:selection' ); // -> false
selection.is( 'range' ); // -> false
```
Parameters

type : 'selection' | 'model:selection'

Returns

this is ModelSelection | ModelDocumentSelection
inherited
is( type ) → this is ModelNode | ModelText | ModelElement | ModelRootElement
See source
Checks whether the object is of type ModelNode or its subclass.

This method is useful when processing model objects that are of unknown type. For example, a function may return a ModelDocumentFragment or a ModelNode that can be either a text node or an element. This method can be used to check what kind of object is returned.
```
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:
```
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:
```
imageElement.is( 'element', 'imageBlock' ); // -> true
imageElement.is( 'element', 'imageBlock' ); // -> same as above
imageElement.is( 'model:element', 'imageBlock' ); // -> same as above, but more precise
```
Parameters

type : 'node' | 'model:node'

Returns

this is ModelNode | ModelText | ModelElement | ModelRootElement
inherited
isEqual( otherRange ) → boolean

See source
Two ranges are equal if their start and end positions are equal.

Parameters

otherRange : ModelRange

Range to compare with.

Returns

boolean

true if ranges are equal, false otherwise.
inherited
isIntersecting( otherRange ) → boolean

See source
Checks and returns whether this range intersects with given range.

Parameters

otherRange : ModelRange

Range to compare with.

Returns

boolean

true if ranges intersect, false otherwise.
inherited
listenTo( emitter, event, callback, [ options ] ) → void
See source
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.
```
// 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.

Type parameters

TEvent : extends BaseEvent

The type describing the event. See BaseEvent.

Parameters

emitter : Emitter

The object that fires the event.

event : TEvent[ 'name' ]

The name of the event.

callback : GetCallback<TEvent>

The function to be called on event.

[ options ] : GetCallbackOptions<TEvent>

Additional options.

Returns

void
inherited
off( event, callback ) → void

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

Parameters

event : string

The name of the event.

callback : Function

The function to stop being called.

Returns

void
inherited
on( event, callback, [ options ] ) → void

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

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

Type parameters

TEvent : extends BaseEvent

The type descibing the event. See BaseEvent.

Parameters

event : TEvent[ 'name' ]

The name of the event.

callback : GetCallback<TEvent>

The function to be called on event.

[ options ] : GetCallbackOptions<TEvent>

Additional options.

Returns

void
inherited
once( event, callback, [ options ] ) → void

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

Type parameters

TEvent : extends BaseEvent

The type descibing the event. See BaseEvent.

Parameters

event : TEvent[ 'name' ]

The name of the event.

callback : GetCallback<TEvent>

The function to be called on event.

[ options ] : GetCallbackOptions<TEvent>

Additional options.

Returns

void
inherited
stopDelegating( [ event ], [ emitter ] ) → void
See source
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.
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
inherited
stopListening( [ emitter ], [ event ], [ callback ] ) → void
See source
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.
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
inherited
toJSON() → unknown

See source
Converts Range to plain object and returns it.

Returns

unknown

Node converted to plain object.
toRange() → ModelRange

See source
Creates a range instance that is equal to this live range.

Returns

ModelRange
internal inherited
_getTransformedByDeletion( deletePosition, howMany ) → null | ModelRange

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

Parameters

deletePosition : ModelPosition

Position from which nodes are removed.

howMany : number

How many nodes are removed.

Returns

null | ModelRange

Result of the transformation.
internal inherited
_getTransformedByInsertOperation( operation, spread ) → Array<ModelRange>

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

Parameters

operation : InsertOperation

spread : boolean

Defaults to false

Returns

Array<ModelRange>

internal inherited
`_getTransformedByInsertion( insertPosition, howMany, spread ) → Array<ModelRange>`

See source

Returns an array containing one or two ranges that are a result of transforming this range by inserting howMany nodes at insertPosition. Two ranges are returned if the insertion was inside this range and spread is set to true.

Examples:

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 ]

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<ModelRange>: Result of the transformation.

internal inherited
_getTransformedByMergeOperation( operation ) → ModelRange

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

Parameters

operation : MergeOperation

Returns

ModelRange
internal inherited
_getTransformedByMove( sourcePosition, targetPosition, howMany, spread ) → Array<ModelRange>

See source
Returns an array containing ranges that are a result of transforming this range by moving howMany nodes from sourcePosition to targetPosition.

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<ModelRange>

Result of the transformation.
internal inherited
_getTransformedByMoveOperation( operation, spread ) → Array<ModelRange>

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

Parameters

operation : MoveOperation

spread : boolean

Defaults to false

Returns

Array<ModelRange>
internal inherited
_getTransformedBySplitOperation( operation ) → ModelRange

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

Parameters

operation : SplitOperation

Returns

ModelRange

Static methods

inherited static
fromJSON( json, doc ) → ModelRange

See source
Creates a Range instance from given plain object (i.e. parsed JSON string).

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.
static
fromRange( range ) → ModelLiveRange

See source
Creates a ModelLiveRange instance that is equal to the given range.

Parameters

range : ModelRange

Returns

ModelLiveRange
internal inherited static
_createFromRanges( ranges ) → ModelRange
See source
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.
```
Parameters

ranges : Array<ModelRange>

Ranges to combine.

Returns

ModelRange

Combined range.

Events

change( eventInfo, range, data )

See source
Describes change:range or change:content event.

Parameters

eventInfo : EventInfo

An object containing information about the fired event.

range : ModelRange

data : object
change:content( eventInfo, range, data )

See source
Fired when ModelLiveRange instance boundaries have not changed after a change in document but the change took place inside the range, effectively changing its content.

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:range( eventInfo, range, data )

See source
Fired when ModelLiveRange instance boundaries have changed due to changes in the document.

Parameters

eventInfo : EventInfo

An object containing information about the fired event.

range : ModelRange

data : object

Object with additional information about the change.

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

With the release of version 42.0.0, we have rewritten much of our documentation to reflect the new import paths and features. We appreciate your feedback to help us ensure its accuracy and completeness.

ModelLiveRange (engine/model)

Filtering

Properties

readonly inherited end : ModelPositionmodule:engine/model/liverange~ModelLiveRange#end

readonly inherited isCollapsed : booleanmodule:engine/model/liverange~ModelLiveRange#isCollapsed

readonly inherited isFlat : booleanmodule:engine/model/liverange~ModelLiveRange#isFlat

readonly inherited root : ModelElement | ModelDocumentFragmentmodule:engine/model/liverange~ModelLiveRange#root

readonly inherited start : ModelPositionmodule:engine/model/liverange~ModelLiveRange#start

Static properties

internal readonly static _createFromPositionAndShift : ( position: ModelPosition, shift: number ) => ModelLiveRangemodule:engine/model/liverange~ModelLiveRange._createFromPositionAndShift

Related:

internal readonly static _createIn : ( element: ModelElement | ModelDocumentFragment ) => ModelLiveRangemodule:engine/model/liverange~ModelLiveRange._createIn

Related:

internal readonly static _createOn : ( element: ModelDocumentFragment | ModelItem ) => ModelLiveRangemodule:engine/model/liverange~ModelLiveRange._createOn

Related:

Methods

constructor( start, [ end ] )module:engine/model/liverange~ModelLiveRange#constructor

Parameters

Related:

inherited Symbol.iterator() → IterableIterator<ModelTreeWalkerValue>module:engine/model/liverange~ModelLiveRange#Symbol.iterator

Returns

inherited clone() → thismodule:engine/model/liverange~ModelLiveRange#clone

Returns

inherited containsItem( item ) → booleanmodule:engine/model/liverange~ModelLiveRange#containsItem

Parameters

Returns

inherited containsPosition( position ) → booleanmodule:engine/model/liverange~ModelLiveRange#containsPosition

Parameters

Returns

inherited containsRange( otherRange, loose ) → booleanmodule:engine/model/liverange~ModelLiveRange#containsRange

Parameters

Returns

inherited delegate( events ) → EmitterMixinDelegateChainmodule:engine/model/liverange~ModelLiveRange#delegate

Parameters

Returns

detach() → voidmodule:engine/model/liverange~ModelLiveRange#detach

Returns

inherited fire( eventOrInfo, args ) → GetEventInfo<TEvent>[ 'return' ]module:engine/model/liverange~ModelLiveRange#fire

Type parameters

Parameters

Returns

inherited getCommonAncestor() → null | ModelElement | ModelDocumentFragmentmodule:engine/model/liverange~ModelLiveRange#getCommonAncestor

Returns

inherited getContainedElement() → null | ModelElementmodule:engine/model/liverange~ModelLiveRange#getContainedElement

Returns

inherited getDifference( otherRange ) → Array<ModelRange>module:engine/model/liverange~ModelLiveRange#getDifference

Parameters

Returns

inherited getIntersection( otherRange ) → null | ModelRangemodule:engine/model/liverange~ModelLiveRange#getIntersection

Parameters

Returns

inherited getItems( options ) → IterableIterator<ModelItem>module:engine/model/liverange~ModelLiveRange#getItems

Parameters

Returns

inherited getJoined( otherRange, loose ) → null | ModelRangemodule:engine/model/liverange~ModelLiveRange#getJoined

Parameters

Returns

inherited getMinimalFlatRanges() → Array<ModelRange>module:engine/model/liverange~ModelLiveRange#getMinimalFlatRanges

Returns

inherited getPositions( options ) → IterableIterator<ModelPosition>module:engine/model/liverange~ModelLiveRange#getPositions

Parameters

Returns

inherited getTransformedByOperation( operation ) → Array<ModelRange>module:engine/model/liverange~ModelLiveRange#getTransformedByOperation

Parameters

Returns

inherited getTransformedByOperations( operations ) → Array<ModelRange>module:engine/model/liverange~ModelLiveRange#getTransformedByOperations

Parameters

Returns

Related:

inherited getWalker( options ) → ModelTreeWalkermodule:engine/model/liverange~ModelLiveRange#getWalker

Parameters

Returns

inherited is( type ) → this is ModelElement | ModelRootElementmodule:engine/model/liverange~ModelLiveRange#is:ELEMENT

Parameters

Returns

inherited is( type ) → this is ModelTextmodule:engine/model/liverange~ModelLiveRange#is:TEXT

Parameters

Returns

inherited is( type ) → this is ModelRootElementmodule:engine/model/liverange~ModelLiveRange#is:ROOT_ELEMENT

Parameters

readonly inherited
`end : ModelPosition`

readonly inherited
`isCollapsed : boolean`

readonly inherited
`isFlat : boolean`

readonly inherited
`root : ModelElement | ModelDocumentFragment`

readonly inherited
`start : ModelPosition`

internal readonly static
`_createFromPositionAndShift : ( position: ModelPosition, shift: number ) => ModelLiveRange`

internal readonly static
`_createIn : ( element: ModelElement | ModelDocumentFragment ) => ModelLiveRange`

internal readonly static
`_createOn : ( element: ModelDocumentFragment | ModelItem ) => ModelLiveRange`

`constructor( start, [ end ] )`

inherited
`Symbol.iterator() → IterableIterator<ModelTreeWalkerValue>`

inherited
`clone() → this`

inherited
`containsItem( item ) → boolean`

inherited
`containsPosition( position ) → boolean`

inherited
`containsRange( otherRange, loose ) → boolean`

inherited
`delegate( events ) → EmitterMixinDelegateChain`

`detach() → void`

inherited
`fire( eventOrInfo, args ) → GetEventInfo<TEvent>[ 'return' ]`

inherited
`getCommonAncestor() → null | ModelElement | ModelDocumentFragment`

inherited
`getContainedElement() → null | ModelElement`

inherited
`getDifference( otherRange ) → Array<ModelRange>`

inherited
`getIntersection( otherRange ) → null | ModelRange`

inherited
`getItems( options ) → IterableIterator<ModelItem>`

inherited
`getJoined( otherRange, loose ) → null | ModelRange`

inherited
`getMinimalFlatRanges() → Array<ModelRange>`

inherited
`getPositions( options ) → IterableIterator<ModelPosition>`

inherited
`getTransformedByOperation( operation ) → Array<ModelRange>`

inherited
`getTransformedByOperations( operations ) → Array<ModelRange>`

inherited
`getWalker( options ) → ModelTreeWalker`

inherited
`is( type ) → this is ModelElement | ModelRootElement`

inherited
`is( type ) → this is ModelText`

inherited
`is( type ) → this is ModelRootElement`

inherited
`is( type ) → this is ModelRange | ModelLiveRange`

inherited
`is( type ) → this is ModelDocumentFragment`

inherited
`is( type ) → this is ModelLiveRange`

inherited
`is( type ) → this is ModelLivePosition`

inherited
`is( type ) → this is ModelPosition | ModelLivePosition`

inherited
`is( type ) → this is ModelDocumentSelection`

inherited
`is( type, name ) → boolean`

inherited
`is( type, name ) → boolean`

inherited
`is( type ) → this is ModelTextProxy`

inherited
`is( type ) → this is Marker`

inherited
`is( type ) → this is ModelSelection | ModelDocumentSelection`

inherited
`is( type ) → this is ModelNode | ModelText | ModelElement | ModelRootElement`

inherited
`isEqual( otherRange ) → boolean`

inherited
`isIntersecting( otherRange ) → boolean`

inherited
`listenTo( emitter, event, callback, [ options ] ) → void`

inherited
`off( event, callback ) → void`

inherited
`on( event, callback, [ options ] ) → void`

inherited
`once( event, callback, [ options ] ) → void`

inherited
`stopDelegating( [ event ], [ emitter ] ) → void`

inherited
`stopListening( [ emitter ], [ event ], [ callback ] ) → void`

inherited
`toJSON() → unknown`

`toRange() → ModelRange`