CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Class

LiveRange (engine/model)

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

class
See source

LiveRange 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 LiveRange. Each LiveRange instance bind events that might have to be unbound. Use detach whenever you don't need LiveRange anymore.

Filtering

Properties

Static properties

Methods

  • constructor( start, [ end ] )

    See source

    Creates a live range.

    Parameters

    start : Position
    [ end ] : null | Position

    Related:

  • inherited

    Symbol.iterator() → IterableIterator<TreeWalkerValue>

    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 TreeWalkerValue. It iterates over all text contents that are inside the range and all the Elements that are entered into when iterating over this range.

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

    Returns

    IterableIterator<TreeWalkerValue>

  • inherited

    clone() → LiveRange

    See source

    Returns a new range that is equal to current range.

    Returns

    LiveRange

  • inherited

    containsItem( item ) → boolean

    See source

    Checks whether given Item is inside this range.

    Parameters

    item : Item

    Returns

    boolean

  • inherited

    containsPosition( position ) → boolean

    See source

    Checks whether this range contains given position.

    Parameters

    position : Position

    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 : Range

    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 LiveRange. Use it whenever you don't need LiveRange 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 | Element | DocumentFragment

    See source

    Returns an Element or DocumentFragment which is a common ancestor of the range's both ends (in which the entire range is contained).

    Returns

    null | Element | DocumentFragment

  • inherited

    getContainedElement() → null | Element

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

  • inherited

    getDifference( otherRange ) → Array<Range>

    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 : Range

    Range to differentiate against.

    Returns

    Array<Range>

    The difference between ranges.

  • inherited

    getIntersection( otherRange ) → null | Range

    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 : Range

    Range to check for intersection.

    Returns

    null | Range

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

  • inherited

    getItems( options ) → IterableIterator<Item>

    See source

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

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

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

    Parameters

    options : TreeWalkerOptions

    Object with configuration options. See TreeWalker.

    Defaults to {}

    Returns

    IterableIterator<Item>

  • inherited

    getJoined( otherRange, loose ) → null | Range

    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 : Range

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

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

  • inherited

    getMinimalFlatRanges() → Array<Range>

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

    Array of flat ranges covering this range.

  • inherited

    getPositions( options ) → IterableIterator<Position>

    See source

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

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

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

    Parameters

    options : TreeWalkerOptions

    Object with configuration options. See TreeWalker.

    Defaults to {}

    Returns

    IterableIterator<Position>

  • inherited

    getTransformedByOperation( operation ) → Array<Range>

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

    Range which is the result of transformation.

  • inherited

    getTransformedByOperations( operations ) → Array<Range>

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

    Range which is the result of transformation.

    Related:

    • Range#getTransformedByOperation

  • inherited

    getWalker( options ) → TreeWalker

    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 : TreeWalkerOptions

    Object with configuration options. See TreeWalker.

    Defaults to {}

    Returns

    TreeWalker

  • inherited

    is( type ) → this is Element | RootElement

    See source

    Checks whether the object is of type Element 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 Element | RootElement

  • inherited

    is( type ) → this is Text

    See source

    Checks whether the object is of type Text.

    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 Text

  • inherited

    is( type ) → this is RootElement

    See source

    Checks whether the object is of type RootElement.

    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 RootElement

  • inherited

    is( type ) → this is LivePosition

    See source

    Checks whether the object is of type LivePosition.

    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 LivePosition

  • inherited

    is( type ) → this is DocumentFragment

    See source

    Checks whether the object is of type DocumentFragment.

    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 DocumentFragment

  • inherited

    is( type ) → this is LiveRange

    See source

    Checks whether the object is of type LiveRange.

    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 LiveRange

  • inherited

    is( type ) → this is Range | LiveRange

    See source

    Checks whether the object is of type Range 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 Range | LiveRange

  • inherited

    is( type ) → this is Position | LivePosition

    See source

    Checks whether the object is of type Position 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 Position | LivePosition

  • inherited

    is( type ) → this is Selection | DocumentSelection

    See source

    Checks whether the object is of type Selection or DocumentSelection.

    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 Selection | DocumentSelection

  • inherited

    is( type, name ) → boolean

    See source

    Checks whether the object is of type Element 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, name ) → boolean

    See source

    Checks whether the object is of type RootElement 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 ) → this is TextProxy

    See source

    Checks whether the object is of type TextProxy.

    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 TextProxy

  • 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 DocumentSelection

    See source

    Checks whether the object is of type DocumentSelection.

    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 DocumentSelection

  • inherited

    is( type ) → this is Node | Text | Element | RootElement

    See source

    Checks whether the object is of type Node or its subclass.

    This method is useful when processing model objects that are of unknown type. For example, a function may return a DocumentFragment or a Node 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 Node | Text | Element | RootElement

  • inherited

    isEqual( otherRange ) → boolean

    See source

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

    Parameters

    otherRange : Range

    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 : Range

    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() → Range

    See source

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

    Returns

    Range

  • internal inherited

    _getTransformedByDeletion( deletePosition, howMany ) → null | Range

    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 : Position
    howMany : number

    How many nodes are removed.

    Returns

    null | Range

    Result of the transformation.

  • internal inherited

    _getTransformedByInsertOperation( operation, spread ) → Array<Range>

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

  • internal inherited

    _getTransformedByInsertion( insertPosition, howMany, spread ) → Array<Range>

    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 : Position

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

    Result of the transformation.

  • internal inherited

    _getTransformedByMergeOperation( operation ) → Range

    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

    Range

  • internal inherited

    _getTransformedByMove( sourcePosition, targetPosition, howMany, spread ) → Array<Range>

    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 : Position

    Position from which nodes are moved.

    targetPosition : Position

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

    Result of the transformation.

  • internal inherited

    _getTransformedByMoveOperation( operation, spread ) → Array<Range>

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

  • internal inherited

    _getTransformedBySplitOperation( operation ) → Range

    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

    Range

Static methods

  • inherited static

    fromJSON( json, doc ) → Range

    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 : Document

    Document object that will be range owner.

    Returns

    Range

    Range instance created using given plain object.

  • static

    fromRange( range ) → LiveRange

    See source

    Creates a LiveRange instance that is equal to the given range.

    Parameters

    range : Range

    Returns

    LiveRange

  • internal inherited static

    _createFromRanges( ranges ) → Range

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

    Ranges to combine.

    Returns

    Range

    Combined range.

Events

  • change:content( eventInfo, range, data )

    See source

    Fired when LiveRange 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 : Range

    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 LiveRange instance boundaries have changed due to changes in the document.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    range : Range
    data : object

    Object with additional information about the change.