Sign up (with export icon)

ViewRange

Api-class iconclass

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

Methods

  • Chevron-right icon

    constructor( start, end )

    Creates a range spanning from start position to end position.

    Note: Constructor creates it's own ViewPosition instances basing on passed values.

    Parameters

    start : ViewPosition

    Start position.

    end : null | ViewPosition

    End position. If not set, range will be collapsed at the start position.

    Defaults to null

  • Chevron-right icon

    Symbol.iterator() → IterableIterator<ViewTreeWalkerValue>

    Iterable 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 boundaries set to this range and ignoreElementEnd option set to true.

    Returns

    IterableIterator<ViewTreeWalkerValue>
  • Chevron-right icon

  • Chevron-right icon

    containsPosition( position ) → boolean

    Checks whether this range contains given position.

    Parameters

    position : ViewPosition

    Position to check.

    Returns

    boolean

    true if given position is contained in this range, false otherwise.

  • Chevron-right icon

    containsRange( otherRange, loose ) → boolean

    Checks whether this range contains given range.

    Parameters

    otherRange : ViewRange

    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.

  • Chevron-right icon

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

    Returns

    null | ViewNode | ViewDocumentFragment
  • Chevron-right icon

    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 | ViewElement
  • Chevron-right icon

    getDifference( otherRange ) → Array<ViewRange>

    Computes 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 code

    Parameters

    otherRange : ViewRange

    Range to differentiate against.

    Returns

    Array<ViewRange>

    The difference between ranges.

  • Chevron-right icon

    Creates 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 code

    Note that in the sample above:

    Returns

    ViewRange

    Enlarged range.

  • Chevron-right icon

    getIntersection( otherRange ) → null | ViewRange

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

    Parameters

    otherRange : ViewRange

    Range to check for intersection.

    Returns

    null | ViewRange

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

  • Chevron-right icon

    getItems( options ) → IterableIterator<ViewItem>

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

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

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

    Parameters

    options : ViewTreeWalkerOptions

    Object with configuration options. See ViewTreeWalker.

    Defaults to {}

    Returns

    IterableIterator<ViewItem>
  • Chevron-right icon

    getPositions( options ) → IterableIterator<ViewPosition>

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

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

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

    Parameters

    options : ViewTreeWalkerOptions

    Object with configuration options. See ViewTreeWalker.

    Defaults to {}

    Returns

    IterableIterator<ViewPosition>
  • Chevron-right icon

    Creates 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 code

    Note that in the sample above:

    Returns

    ViewRange

    Shrunk range.

  • Chevron-right icon

    getWalker( options ) → ViewTreeWalker

    Creates a TreeWalker instance with this range as a boundary.

    Parameters

    options : ViewTreeWalkerOptions

    Object with configuration options. See ViewTreeWalker.

    Defaults to {}

    Returns

    ViewTreeWalker
  • Checks whether this object is of type ViewElement or 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' ); // -> false
    
    Copy code

    Assuming 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' ); -> false
    
    Copy code

    Parameters

    type : 'element' | 'view:element'

    Returns

    this is ViewElement | ViewAttributeElement | ViewContainerElement | ViewEditableElement | ViewEmptyElement | ViewRawElement | ViewRootEditableElement | ViewUIElement
  • Chevron-right icon

    Checks whether this object is of type ViewContainerElement or 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' ); // -> false
    
    Copy code

    Assuming 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' ); -> false
    
    Copy code

    Parameters

    type : 'containerElement' | 'view:containerElement'

    Returns

    this is ViewContainerElement | ViewEditableElement | ViewRootEditableElement
  • Chevron-right icon

    is( type ) → this is ViewEditableElement | ViewRootEditableElement
    inherited

    Checks whether this object is of type ViewEditableElement or 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' ); // -> false
    
    Copy code

    Assuming 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' ); -> false
    
    Copy code

    Parameters

    type : 'editableElement' | 'view:editableElement'

    Returns

    this is ViewEditableElement | ViewRootEditableElement
  • Chevron-right icon

    is( type ) → this is ViewAttributeElement
    inherited

    Checks 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' ); // -> false
    
    Copy code

    Assuming 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' ); -> false
    
    Copy code

    Parameters

    type : 'attributeElement' | 'view:attributeElement'

    Returns

    this is ViewAttributeElement
  • Chevron-right icon

    is( type ) → this is ViewRootEditableElement
    inherited

    Checks 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' ); // -> false
    
    Copy code

    Assuming 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' ); -> false
    
    Copy code

    Parameters

    type : 'rootElement' | 'view:rootElement'

    Returns

    this is ViewRootEditableElement
  • Chevron-right icon

    is( type ) → this is ViewTextProxy
    inherited

    Checks 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' ); // -> false
    
    Copy code

    Note: 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
  • Chevron-right icon

    is( type ) → this is ViewPosition
    inherited

    Checks 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' ); // -> false
    
    Copy code

    Parameters

    type : 'position' | 'view:position'

    Returns

    this is ViewPosition
  • Chevron-right icon

    is( type ) → this is ViewDocumentFragment
    inherited

    hecks 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' ); // -> false
    
    Copy code

    Parameters

    type : 'documentFragment' | 'view:documentFragment'

    Returns

    this is ViewDocumentFragment
  • Chevron-right icon

    is( type ) → this is ViewText
    inherited

    Checks 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' ); // -> false
    
    Copy code

    Parameters

    type : '$text' | 'view:$text'

    Returns

    this is ViewText
  • Chevron-right icon

    is( type ) → this is ViewUIElement
    inherited

    Checks 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' ); // -> false
    
    Copy code

    Assuming 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' ); -> false
    
    Copy code

    Parameters

    type : 'uiElement' | 'view:uiElement'

    Returns

    this is ViewUIElement
  • Chevron-right icon

    is( type ) → this is ViewRawElement
    inherited

    Checks 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' ); // -> false
    
    Copy code

    Assuming 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' ); -> false
    
    Copy code

    Parameters

    type : 'rawElement' | 'view:rawElement'

    Returns

    this is ViewRawElement
  • Chevron-right icon

    is( type ) → this is ViewEmptyElement
    inherited

    Checks 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' ); // -> false
    
    Copy code

    Assuming 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' ); -> false
    
    Copy code

    Parameters

    type : 'emptyElement' | 'view:emptyElement'

    Returns

    this is ViewEmptyElement
  • Chevron-right icon

    is( type ) → this is ViewRange
    inherited

    Checks 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' ); // -> false
    
    Copy code

    Parameters

    type : 'range' | 'view:range'

    Returns

    this is ViewRange
  • Chevron-right icon

    is( type ) → this is ViewDocumentSelection
    inherited

    Checks 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' ); // -> false
    
    Copy code

    Parameters

    type : 'documentSelection' | 'view:documentSelection'

    Returns

    this is ViewDocumentSelection
  • Chevron-right icon

    is( type, name ) → boolean
    inherited

    Checks whether the object is of type ViewAttributeElement and has the specified name.

    Type parameters

    N : extends string

    Parameters

    type : 'attributeElement' | 'view:attributeElement'
    name : N

    Returns

    boolean
  • Chevron-right icon

    is( type, name ) → boolean
    inherited

    Checks whether the object is of type ViewEditableElement or its subclass and has the specified name.

    Type parameters

    N : extends string

    Parameters

    type : 'editableElement' | 'view:editableElement'
    name : N

    Returns

    boolean
  • Chevron-right icon

    is( type, name ) → boolean
    inherited

    Checks whether the object is of type ViewRawElement and has the specified name.

    Type parameters

    N : extends string

    Parameters

    type : 'rawElement' | 'view:rawElement'
    name : N

    Returns

    boolean
  • Chevron-right icon

    is( type, name ) → boolean
    inherited

    Checks whether the object is of type ViewUIElement and has the specified name.

    Type parameters

    N : extends string

    Parameters

    type : 'uiElement' | 'view:uiElement'
    name : N

    Returns

    boolean
  • Chevron-right icon

    is( type, name ) → boolean
    inherited

    Checks whether the object is of type ViewRootEditableElement and has the specified name.

    Type parameters

    N : extends string

    Parameters

    type : 'rootElement' | 'view:rootElement'
    name : N

    Returns

    boolean
  • Chevron-right icon

    is( type, name ) → boolean
    inherited

    Checks whether the object is of type ViewEmptyElement has the specified name.

    Type parameters

    N : extends string

    Parameters

    type : 'emptyElement' | 'view:emptyElement'
    name : N

    Returns

    boolean
  • Chevron-right icon

    is( type, name ) → boolean
    inherited

    Checks whether the object is of type ViewContainerElement or its subclass and has the specified name.

    Type parameters

    N : extends string

    Parameters

    type : 'containerElement' | 'view:containerElement'
    name : N

    Returns

    boolean
  • Chevron-right icon

    is( type, name ) → boolean
    inherited

    Checks whether the object is of type ViewElement or its subclass and has the specified name.

    Type parameters

    N : extends string

    Parameters

    type : 'element' | 'view:element'
    name : N

    Returns

    boolean
  • Chevron-right icon

    is( type ) → this is ViewSelection | ViewDocumentSelection
    inherited

    Checks whether this object is of type ViewSelection or ViewDocumentSelection.

    selection.is( 'selection' ); // -> true
    selection.is( 'view:selection' ); // -> true
    
    selection.is( 'model:selection' ); // -> false
    selection.is( 'element' ); // -> false
    selection.is( 'range' ); // -> false
    
    Copy code

    Parameters

    type : 'selection' | 'view:selection'

    Returns

    this is ViewSelection | ViewDocumentSelection
  • Checks whether this object is of type ViewNode or its subclass.

    This method is useful when processing view objects that are of unknown type. For example, a function may return a ViewDocumentFragment or a ViewNode 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
    
    Copy code

    Since this method is also available on a range of model 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:

    viewElement.is( 'view:element' ); // -> true
    viewElement.is( 'model:element' ); // -> false
    
    Copy code

    By 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 precise
    
    Copy code

    Parameters

    type : 'node' | 'view:node'

    Returns

    this is ViewText | ViewNode | ViewElement | ViewAttributeElement | ViewContainerElement | ViewEditableElement | ViewEmptyElement | ViewRawElement | ViewRootEditableElement | ViewUIElement
  • Chevron-right icon

    isEqual( otherRange ) → boolean

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

    Parameters

    otherRange : ViewRange

    Range to compare with.

    Returns

    boolean

    true if ranges are equal, false otherwise

  • Chevron-right icon

    isIntersecting( otherRange ) → boolean

    Checks and returns whether this range intersects with the given range.

    Parameters

    otherRange : ViewRange

    Range to compare with.

    Returns

    boolean

    True if ranges intersect.

  • Chevron-right icon

    toJSON() → unknown

    Converts ViewRange instance to plain object and returns it.

    Returns

    unknown

    ViewRange instance converted to plain object.

Static methods