ViewRange
Range in the view tree. A range is represented by its start and end positions.
In order to create a new position instance use the createPosition*() factory methods available in:
Properties
end : ViewPositionreadonlymodule:engine/view/range~ViewRange#endEnd position.
isCollapsed : booleanreadonlymodule:engine/view/range~ViewRange#isCollapsedReturns whether the range is collapsed, that is it start and end positions are equal.
isFlat : booleanreadonlymodule:engine/view/range~ViewRange#isFlatroot : ViewNode | ViewDocumentFragmentreadonlymodule:engine/view/range~ViewRange#rootRange root element.
start : ViewPositionreadonlymodule:engine/view/range~ViewRange#startStart position.
Methods
constructor( start, end )module:engine/view/range~ViewRange#constructorCreates a range spanning from
startposition toendposition.Note: Constructor creates it's own
ViewPositioninstances basing on passed values.Parameters
start : ViewPositionStart position.
end : null | ViewPositionEnd position. If not set, range will be collapsed at the
startposition.Defaults to
null
Symbol.iterator() → IterableIterator<ViewTreeWalkerValue>module:engine/view/range~ViewRange#Symbol.iteratorIterable interface.
Iterates over all view items that are in this range and returns them together with additional information like length or positions, grouped as
ViewTreeWalkerValue.This iterator uses TreeWalker with
boundariesset to this range andignoreElementEndoption set totrue.Returns
IterableIterator<ViewTreeWalkerValue>
module:engine/view/range~ViewRange#clonecontainsPosition( position ) → booleanmodule:engine/view/range~ViewRange#containsPositionChecks whether this range contains given position.
Parameters
position : ViewPositionPosition to check.
Returns
booleantrueif given position is contained in this range,falseotherwise.
containsRange( otherRange, loose ) → booleanmodule:engine/view/range~ViewRange#containsRangeChecks whether this range contains given range.
Parameters
otherRange : ViewRangeRange to check.
loose : booleanWhether 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
booleantrueif given range boundaries are contained by this range,falseotherwise.
getCommonAncestor() → null | ViewNode | ViewDocumentFragmentmodule:engine/view/range~ViewRange#getCommonAncestorReturns a
ViewNodeorViewDocumentFragmentwhich is a common ancestor of range's both ends (in which the entire range is contained).Returns
null | ViewNode | ViewDocumentFragment
getContainedElement() → null | ViewElementmodule:engine/view/range~ViewRange#getContainedElementReturns 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 | ViewElement
getDifference( otherRange ) → Array<ViewRange>module:engine/view/range~ViewRange#getDifferenceComputes which part(s) of this range is not a part of given range. Returned array contains zero, one or two ranges.
Examples:
let foo = downcastWriter.createText( 'foo' ); let img = downcastWriter.createContainerElement( 'img' ); let bar = downcastWriter.createText( 'bar' ); let p = downcastWriter.createContainerElement( 'p', null, [ foo, img, bar ] ); let range = view.createRange( view.createPositionAt( foo, 2 ), view.createPositionAt( bar, 1 ); // "o", img, "b" are in range. let otherRange = view.createRange( // "oo", img, "ba" are in range. view.createPositionAt( foo, 1 ), view.createPositionAt( bar, 2 ) ); let transformed = range.getDifference( otherRange ); // transformed array has no ranges because `otherRange` contains `range` otherRange = view.createRange( view.createPositionAt( foo, 1 ), view.createPositionAt( p, 2 ); // "oo", img are in range. transformed = range.getDifference( otherRange ); // transformed array has one range: from ( p, 2 ) to ( bar, 1 ) otherRange = view.createRange( view.createPositionAt( p, 1 ), view.createPositionAt( p, 2 ) ); // img is in range. transformed = range.getDifference( otherRange ); // transformed array has two ranges: from ( foo, 1 ) to ( p, 1 ) and from ( p, 2 ) to ( bar, 1 )Copy codeParameters
otherRange : ViewRangeRange to differentiate against.
Returns
Array<ViewRange>The difference between ranges.
getEnlarged() → ViewRangemodule:engine/view/range~ViewRange#getEnlargedCreates a maximal range that has the same content as this range but is expanded in both ways (at the beginning and at the end).
For example:
<p>Foo</p><p><b>{Bar}</b></p> -> <p>Foo</p>[<p><b>Bar</b>]</p> <p><b>foo</b>{bar}<span></span></p> -> <p><b>foo[</b>bar<span></span>]</p>Copy codeNote that in the sample above:
<p>have type ofViewContainerElement,<b>have type ofViewAttributeElement,<span>have type ofViewUIElement.
Returns
ViewRangeEnlarged range.
getIntersection( otherRange ) → null | ViewRangemodule:engine/view/range~ViewRange#getIntersectionReturns 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 foo = downcastWriter.createText( 'foo' ); let img = downcastWriter.createContainerElement( 'img' ); let bar = downcastWriter.createText( 'bar' ); let p = downcastWriter.createContainerElement( 'p', null, [ foo, img, bar ] ); let range = view.createRange( view.createPositionAt( foo, 2 ), view.createPositionAt( bar, 1 ); // "o", img, "b" are in range. let otherRange = view.createRange( view.createPositionAt( foo, 1 ), view.createPositionAt( p, 2 ); // "oo", img are in range. let transformed = range.getIntersection( otherRange ); // range from ( foo, 1 ) to ( p, 2 ). otherRange = view.createRange( view.createPositionAt( bar, 1 ), view.createPositionAt( bar, 3 ); "ar" is in range. transformed = range.getIntersection( otherRange ); // null - no common part.Copy codeParameters
otherRange : ViewRangeRange to check for intersection.
Returns
null | ViewRangeA common part of given ranges or
nullif ranges have no common part.
module:engine/view/range~ViewRange#getItemsReturns an iterator that iterates over all view items that are in this range and returns them.
This method uses
ViewTreeWalkerwithboundariesset to this range andignoreElementEndoption set totrue. However it returns only items, notViewTreeWalkerValue.You may specify additional options for the tree walker. See
ViewTreeWalkerfor a full list of available options.Parameters
options : ViewTreeWalkerOptionsObject with configuration options. See
ViewTreeWalker.Defaults to
{}
Returns
IterableIterator<ViewItem>
getPositions( options ) → IterableIterator<ViewPosition>module:engine/view/range~ViewRange#getPositionsReturns an iterator that iterates over all positions that are boundaries or contained in this range.
This method uses
ViewTreeWalkerwithboundariesset to this range. However it returns only positions, notViewTreeWalkerValue.You may specify additional options for the tree walker. See
ViewTreeWalkerfor a full list of available options.Parameters
options : ViewTreeWalkerOptionsObject with configuration options. See
ViewTreeWalker.Defaults to
{}
Returns
IterableIterator<ViewPosition>
getTrimmed() → ViewRangemodule:engine/view/range~ViewRange#getTrimmedCreates a minimum range that has the same content as this range but is trimmed in both ways (at the beginning and at the end).
For example:
<p>Foo</p>[<p><b>Bar</b>]</p> -> <p>Foo</p><p><b>{Bar}</b></p> <p><b>foo[</b>bar<span></span>]</p> -> <p><b>foo</b>{bar}<span></span></p>Copy codeNote that in the sample above:
<p>have type ofViewContainerElement,<b>have type ofViewAttributeElement,<span>have type ofViewUIElement.
Returns
ViewRangeShrunk range.
getWalker( options ) → ViewTreeWalkermodule:engine/view/range~ViewRange#getWalkerCreates a TreeWalker instance with this range as a boundary.
Parameters
options : ViewTreeWalkerOptionsObject with configuration options. See
ViewTreeWalker.Defaults to
{}
Returns
is( type ) → this is ViewElement | ViewAttributeElement | ViewContainerElement | ViewEditableElement | ViewEmptyElement | ViewRawElement | ViewRootEditableElement | ViewUIElementinheritedmodule:engine/view/range~ViewRange#is:ELEMENTChecks whether this object is of type
ViewElementor its subclass.element.is( 'element' ); // -> true element.is( 'node' ); // -> true element.is( 'view:element' ); // -> true element.is( 'view:node' ); // -> true element.is( 'model:element' ); // -> false element.is( 'documentSelection' ); // -> falseCopy codeAssuming that the object being checked is an element, you can also check its name:
element.is( 'element', 'img' ); // -> true if this is an <img> element text.is( 'element', 'img' ); -> falseCopy codeParameters
type : 'element' | 'view:element'
Returns
is( type ) → this is ViewContainerElement | ViewEditableElement | ViewRootEditableElementinheritedmodule:engine/view/range~ViewRange#is:CONTAINER_ELEMENTChecks whether this object is of type
ViewContainerElementor its subclass.containerElement.is( 'containerElement' ); // -> true containerElement.is( 'element' ); // -> true containerElement.is( 'node' ); // -> true containerElement.is( 'view:containerElement' ); // -> true containerElement.is( 'view:element' ); // -> true containerElement.is( 'view:node' ); // -> true containerElement.is( 'model:element' ); // -> false containerElement.is( 'documentFragment' ); // -> falseCopy codeAssuming that the object being checked is a container element, you can also check its name:
containerElement.is( 'element', 'div' ); // -> true if this is a div container element containerElement.is( 'contaienrElement', 'div' ); // -> same as above text.is( 'element', 'div' ); -> falseCopy codeParameters
type : 'containerElement' | 'view:containerElement'
Returns
is( type ) → this is ViewEditableElement | ViewRootEditableElementinheritedmodule:engine/view/range~ViewRange#is:EDITABLE_ELEMENTChecks whether this object is of type
ViewEditableElementor its subclass.editableElement.is( 'editableElement' ); // -> true editableElement.is( 'element' ); // -> true editableElement.is( 'node' ); // -> true editableElement.is( 'view:editableElement' ); // -> true editableElement.is( 'view:element' ); // -> true editableElement.is( 'view:node' ); // -> true editableElement.is( 'model:element' ); // -> false editableElement.is( 'documentFragment' ); // -> falseCopy codeAssuming that the object being checked is an editbale element, you can also check its name:
editableElement.is( 'element', 'div' ); // -> true if this is a div element editableElement.is( 'editableElement', 'div' ); // -> same as above text.is( 'element', 'div' ); -> falseCopy codeParameters
type : 'editableElement' | 'view:editableElement'
Returns
this is ViewEditableElement | ViewRootEditableElement
is( type ) → this is ViewAttributeElementinheritedmodule:engine/view/range~ViewRange#is:ATTRIBUTE_ELEMENTChecks whether this object is of type
ViewAttributeElement.attributeElement.is( 'attributeElement' ); // -> true attributeElement.is( 'element' ); // -> true attributeElement.is( 'node' ); // -> true attributeElement.is( 'view:attributeElement' ); // -> true attributeElement.is( 'view:element' ); // -> true attributeElement.is( 'view:node' ); // -> true attributeElement.is( 'model:element' ); // -> false attributeElement.is( 'documentFragment' ); // -> falseCopy codeAssuming that the object being checked is an attribute element, you can also check its name:
attributeElement.is( 'element', 'b' ); // -> true if this is a bold element attributeElement.is( 'attributeElement', 'b' ); // -> same as above text.is( 'element', 'b' ); -> falseCopy codeParameters
type : 'attributeElement' | 'view:attributeElement'
Returns
this is ViewAttributeElement
is( type ) → this is ViewRootEditableElementinheritedmodule:engine/view/range~ViewRange#is:ROOT_ELEMENTChecks whether this object is of type
ViewRootEditableElement.rootEditableElement.is( 'rootElement' ); // -> true rootEditableElement.is( 'editableElement' ); // -> true rootEditableElement.is( 'element' ); // -> true rootEditableElement.is( 'node' ); // -> true rootEditableElement.is( 'view:editableElement' ); // -> true rootEditableElement.is( 'view:element' ); // -> true rootEditableElement.is( 'view:node' ); // -> true rootEditableElement.is( 'model:element' ); // -> false rootEditableElement.is( 'documentFragment' ); // -> falseCopy codeAssuming that the object being checked is a root editable element, you can also check its name:
rootEditableElement.is( 'element', 'div' ); // -> true if this is a div root editable element rootEditableElement.is( 'rootElement', 'div' ); // -> same as above text.is( 'element', 'div' ); -> falseCopy codeParameters
type : 'rootElement' | 'view:rootElement'
Returns
this is ViewRootEditableElement
is( type ) → this is ViewTextProxyinheritedmodule:engine/view/range~ViewRange#is:TEXT_PROXYChecks whether this object is of type
ViewTextProxy.textProxy.is( '$textProxy' ); // -> true textProxy.is( 'view:$textProxy' ); // -> true textProxy.is( 'model:$textProxy' ); // -> false textProxy.is( 'element' ); // -> false textProxy.is( 'range' ); // -> falseCopy codeNote: Until version 20.0.0 this method wasn't accepting
'$textProxy'type. The legacy'textProxy'type is still accepted for backward compatibility.Parameters
type : '$textProxy' | 'view:$textProxy'
Returns
this is ViewTextProxy
is( type ) → this is ViewPositioninheritedmodule:engine/view/range~ViewRange#is:POSITIONChecks whether this object is of type
ViewPosition.position.is( 'position' ); // -> true position.is( 'view:position' ); // -> true position.is( 'model:position' ); // -> false position.is( 'element' ); // -> false position.is( 'range' ); // -> falseCopy codeParameters
type : 'position' | 'view:position'
Returns
this is ViewPosition
is( type ) → this is ViewDocumentFragmentinheritedmodule:engine/view/range~ViewRange#is:DOCUMENT_FRAGMENThecks whether this object is of type
ViewDocumentFragment.docFrag.is( 'documentFragment' ); // -> true docFrag.is( 'view:documentFragment' ); // -> true docFrag.is( 'model:documentFragment' ); // -> false docFrag.is( 'element' ); // -> false docFrag.is( 'node' ); // -> falseCopy codeParameters
type : 'documentFragment' | 'view:documentFragment'
Returns
this is ViewDocumentFragment
module:engine/view/range~ViewRange#is:TEXTChecks whether this object is of type
ViewText.text.is( '$text' ); // -> true text.is( 'node' ); // -> true text.is( 'view:$text' ); // -> true text.is( 'view:node' ); // -> true text.is( 'model:$text' ); // -> false text.is( 'element' ); // -> false text.is( 'range' ); // -> falseCopy codeParameters
type : '$text' | 'view:$text'
Returns
this is ViewText
is( type ) → this is ViewUIElementinheritedmodule:engine/view/range~ViewRange#is:UI_ELEMENTChecks whether this object is of type
ViewUIElement.uiElement.is( 'uiElement' ); // -> true uiElement.is( 'element' ); // -> true uiElement.is( 'node' ); // -> true uiElement.is( 'view:uiElement' ); // -> true uiElement.is( 'view:element' ); // -> true uiElement.is( 'view:node' ); // -> true uiElement.is( 'model:element' ); // -> false uiElement.is( 'documentFragment' ); // -> falseCopy codeAssuming that the object being checked is an ui element, you can also check its name:
uiElement.is( 'element', 'span' ); // -> true if this is a span ui element uiElement.is( 'uiElement', 'span' ); // -> same as above text.is( 'element', 'span' ); -> falseCopy codeParameters
type : 'uiElement' | 'view:uiElement'
Returns
this is ViewUIElement
is( type ) → this is ViewRawElementinheritedmodule:engine/view/range~ViewRange#is:RAW_ELEMENTChecks whether this object is of type
ViewRawElement.rawElement.is( 'rawElement' ); // -> true rawElement.is( 'element' ); // -> true rawElement.is( 'node' ); // -> true rawElement.is( 'view:rawElement' ); // -> true rawElement.is( 'view:element' ); // -> true rawElement.is( 'view:node' ); // -> true rawElement.is( 'model:element' ); // -> false rawElement.is( 'documentFragment' ); // -> falseCopy codeAssuming that the object being checked is a raw element, you can also check its name:
rawElement.is( 'img' ); // -> true if this is an img element rawElement.is( 'rawElement', 'img' ); // -> same as above text.is( 'img' ); -> falseCopy codeParameters
type : 'rawElement' | 'view:rawElement'
Returns
this is ViewRawElement
is( type ) → this is ViewEmptyElementinheritedmodule:engine/view/range~ViewRange#is:EMPTY_ELEMENTChecks whether this object is of type
ViewEmptyElement.emptyElement.is( 'emptyElement' ); // -> true emptyElement.is( 'element' ); // -> true emptyElement.is( 'node' ); // -> true emptyElement.is( 'view:emptyElement' ); // -> true emptyElement.is( 'view:element' ); // -> true emptyElement.is( 'view:node' ); // -> true emptyElement.is( 'model:element' ); // -> false emptyElement.is( 'documentFragment' ); // -> falseCopy codeAssuming that the object being checked is an empty element, you can also check its name:
emptyElement.is( 'element', 'img' ); // -> true if this is a img element emptyElement.is( 'emptyElement', 'img' ); // -> same as above text.is( 'element', 'img' ); -> falseCopy codeParameters
type : 'emptyElement' | 'view:emptyElement'
Returns
this is ViewEmptyElement
module:engine/view/range~ViewRange#is:RANGEChecks whether this object is of type
ViewRange.range.is( 'range' ); // -> true range.is( 'view:range' ); // -> true range.is( 'model:range' ); // -> false range.is( 'element' ); // -> false range.is( 'selection' ); // -> falseCopy codeParameters
type : 'range' | 'view:range'
Returns
this is ViewRange
is( type ) → this is ViewDocumentSelectioninheritedmodule:engine/view/range~ViewRange#is:DOCUMENT_SELECTIONChecks whether this object is of type
ViewDocumentSelection.`docSelection.is( 'selection' ); // -> true docSelection.is( 'documentSelection' ); // -> true docSelection.is( 'view:selection' ); // -> true docSelection.is( 'view:documentSelection' ); // -> true docSelection.is( 'model:documentSelection' ); // -> false docSelection.is( 'element' ); // -> false docSelection.is( 'node' ); // -> falseCopy codeParameters
type : 'documentSelection' | 'view:documentSelection'
Returns
this is ViewDocumentSelection
is( type, name ) → booleaninheritedmodule:engine/view/range~ViewRange#is:ATTRIBUTE_ELEMENT_NAMEChecks whether the object is of type
ViewAttributeElementand has the specifiedname.Type parameters
N : extends string
Parameters
type : 'attributeElement' | 'view:attributeElement'name : N
Returns
boolean
is( type, name ) → booleaninheritedmodule:engine/view/range~ViewRange#is:EDITABLE_ELEMENT_NAMEChecks whether the object is of type
ViewEditableElementor its subclass and has the specifiedname.Type parameters
N : extends string
Parameters
type : 'editableElement' | 'view:editableElement'name : N
Returns
boolean
is( type, name ) → booleaninheritedmodule:engine/view/range~ViewRange#is:RAW_ELEMENT_NAMEChecks whether the object is of type
ViewRawElementand has the specifiedname.Type parameters
N : extends string
Parameters
type : 'rawElement' | 'view:rawElement'name : N
Returns
boolean
is( type, name ) → booleaninheritedmodule:engine/view/range~ViewRange#is:UI_ELEMENT_NAMEChecks whether the object is of type
ViewUIElementand has the specifiedname.Type parameters
N : extends string
Parameters
type : 'uiElement' | 'view:uiElement'name : N
Returns
boolean
is( type, name ) → booleaninheritedmodule:engine/view/range~ViewRange#is:ROOT_ELEMENT_NAMEChecks whether the object is of type
ViewRootEditableElementand has the specifiedname.Type parameters
N : extends string
Parameters
type : 'rootElement' | 'view:rootElement'name : N
Returns
boolean
is( type, name ) → booleaninheritedmodule:engine/view/range~ViewRange#is:EMPTY_ELEMENT_NAMEChecks whether the object is of type
ViewEmptyElementhas the specifiedname.Type parameters
N : extends string
Parameters
type : 'emptyElement' | 'view:emptyElement'name : N
Returns
boolean
is( type, name ) → booleaninheritedmodule:engine/view/range~ViewRange#is:CONTAINER_ELEMENT_NAMEChecks whether the object is of type
ViewContainerElementor its subclass and has the specifiedname.Type parameters
N : extends string
Parameters
type : 'containerElement' | 'view:containerElement'name : N
Returns
boolean
is( type, name ) → booleaninheritedmodule:engine/view/range~ViewRange#is:ELEMENT_NAMEChecks whether the object is of type
ViewElementor its subclass and has the specifiedname.Type parameters
N : extends string
Parameters
type : 'element' | 'view:element'name : N
Returns
boolean
is( type ) → this is ViewSelection | ViewDocumentSelectioninheritedmodule:engine/view/range~ViewRange#is:SELECTIONChecks whether this object is of type
ViewSelectionorViewDocumentSelection.selection.is( 'selection' ); // -> true selection.is( 'view:selection' ); // -> true selection.is( 'model:selection' ); // -> false selection.is( 'element' ); // -> false selection.is( 'range' ); // -> falseCopy codeParameters
type : 'selection' | 'view:selection'
Returns
this is ViewSelection | ViewDocumentSelection
is( type ) → this is ViewText | ViewNode | ViewElement | ViewAttributeElement | ViewContainerElement | ViewEditableElement | ViewEmptyElement | ViewRawElement | ViewRootEditableElement | ViewUIElementinheritedmodule:engine/view/range~ViewRange#is:NODEChecks whether this object is of type
ViewNodeor its subclass.This method is useful when processing view objects that are of unknown type. For example, a function may return a
ViewDocumentFragmentor aViewNodethat 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 fragmentCopy codeSince this method is also available on a range of model objects, you can prefix the type of the object with
model:orview:to check, for example, if this is the model's or view's element:viewElement.is( 'view:element' ); // -> true viewElement.is( 'model:element' ); // -> falseCopy codeBy using this method it is also possible to check a name of an element:
imgElement.is( 'element', 'img' ); // -> true imgElement.is( 'view:element', 'img' ); // -> same as above, but more preciseCopy codeParameters
type : 'node' | 'view:node'
Returns
isEqual( otherRange ) → booleanmodule:engine/view/range~ViewRange#isEqualTwo ranges are equal if their start and end positions are equal.
Parameters
otherRange : ViewRangeRange to compare with.
Returns
booleantrueif ranges are equal,falseotherwise
isIntersecting( otherRange ) → booleanmodule:engine/view/range~ViewRange#isIntersectingChecks and returns whether this range intersects with the given range.
Parameters
otherRange : ViewRangeRange to compare with.
Returns
booleanTrue if ranges intersect.
toJSON() → unknownmodule:engine/view/range~ViewRange#toJSONConverts
ViewRangeinstance to plain object and returns it.Returns
unknownViewRangeinstance converted to plain object.
Static methods
_createFromParentsAndOffsets( startElement, startOffset, endElement, endOffset ) → ViewRangeinternalstaticmodule:engine/view/range~ViewRange._createFromParentsAndOffsetsCreates a range from the given parents and offsets.
Parameters
startElement : ViewElement | ViewDocumentFragmentStart position parent element.
startOffset : numberStart position offset.
endElement : ViewElement | ViewDocumentFragmentEnd position parent element.
endOffset : numberEnd position offset.
Returns
ViewRangeCreated range.
_createFromPositionAndShift( position, shift ) → ViewRangeinternalstaticmodule:engine/view/range~ViewRange._createFromPositionAndShiftCreates a new range, spreading from specified position to a position moved by given
shift. Ifshiftis a negative value, shifted position is treated as the beginning of the range.Parameters
position : ViewPositionBeginning of the range.
shift : numberHow long the range should be.
Returns
module:engine/view/range~ViewRange._createInCreates a range inside an element which starts before the first child of that element and ends after the last child of that element.
Parameters
element : ViewElement | ViewDocumentFragmentElement which is a parent for the range.
Returns
module:engine/view/range~ViewRange._createOn