Class

ViewPosition (engine/view)

@ckeditor/ckeditor5-engine/src/view/position

class

Position in the view tree. Position is represented by its parent node and an offset in this parent.

In order to create a new position instance use the createPosition*() factory methods available in:

Filtering

Properties

Methods

  • constructor( parent, offset )

    Creates a position.

    Parameters

    parent : ViewNode | ViewDocumentFragment

    Position parent.

    offset : number

    Position offset.

  • clone() → ViewPosition

    Clones this position.

    Returns

    ViewPosition
  • compareWith( otherPosition ) → ViewPositionRelation

    Checks whether this position is before, after or in same position that other position. Two positions may be also different when they are located in separate roots.

    Parameters

    otherPosition : ViewPosition

    Position to compare with.

    Returns

    ViewPositionRelation
  • getAncestors() → Array<ViewNode | ViewDocumentFragment>

    Returns ancestors array of this position, that is this position's parent and it's ancestors.

    Returns

    Array<ViewNode | ViewDocumentFragment>

    Array with ancestors.

  • getCommonAncestor( position ) → null | ViewNode | ViewDocumentFragment

    Returns a ViewNode or ViewDocumentFragment which is a common ancestor of both positions.

    Parameters

    position : ViewPosition

    Returns

    null | ViewNode | ViewDocumentFragment
  • getLastMatchingPosition( skip, options ) → ViewPosition

    Gets the farthest position which matches the callback using TreeWalker.

    For example:

    getLastMatchingPosition( value => value.type == 'text' ); // <p>{}foo</p> -> <p>foo[]</p>
    getLastMatchingPosition( value => value.type == 'text', { direction: 'backward' } ); // <p>foo[]</p> -> <p>{}foo</p>
    getLastMatchingPosition( value => false ); // Do not move the position.
    

    Parameters

    skip : ( value: ViewTreeWalkerValue ) => boolean

    Callback function. Gets ViewTreeWalkerValue and should return true if the value should be skipped or false if not.

    options : ViewTreeWalkerOptions

    Object with configuration options. See ViewTreeWalker.

    Defaults to {}

    Returns

    ViewPosition

    The position after the last item which matches the skip callback test.

  • getShiftedBy( shift ) → ViewPosition

    Returns a new instance of Position with offset incremented by shift value.

    Parameters

    shift : number

    How position offset should get changed. Accepts negative values.

    Returns

    ViewPosition

    Shifted position.

  • getWalker( options ) → ViewTreeWalker

    Creates a TreeWalker instance with this positions as a start position.

    Parameters

    options : ViewTreeWalkerOptions

    Object with configuration options. See ViewTreeWalker

    Defaults to {}

    Returns

    ViewTreeWalker
  • inherited

    is( type ) → this is ViewElement | ViewAttributeElement | ViewContainerElement | ViewEditableElement | ViewEmptyElement | ViewRawElement | ViewRootEditableElement | ViewUIElement

    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
    

    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
    

    Parameters

    type : 'element' | 'view:element'

    Returns

    this is ViewElement | ViewAttributeElement | ViewContainerElement | ViewEditableElement | ViewEmptyElement | ViewRawElement | ViewRootEditableElement | ViewUIElement
  • inherited

    is( type ) → this is ViewAttributeElement

    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
    

    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
    

    Parameters

    type : 'attributeElement' | 'view:attributeElement'

    Returns

    this is ViewAttributeElement
  • inherited

    is( type ) → this is ViewEditableElement | ViewRootEditableElement

    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
    

    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
    

    Parameters

    type : 'editableElement' | 'view:editableElement'

    Returns

    this is ViewEditableElement | ViewRootEditableElement
  • inherited

    is( type ) → this is ViewRootEditableElement

    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
    

    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
    

    Parameters

    type : 'rootElement' | 'view:rootElement'

    Returns

    this is ViewRootEditableElement
  • inherited

    is( type ) → this is ViewRawElement

    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
    

    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
    

    Parameters

    type : 'rawElement' | 'view:rawElement'

    Returns

    this is ViewRawElement
  • inherited

    is( type ) → this is ViewEmptyElement

    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
    

    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
    

    Parameters

    type : 'emptyElement' | 'view:emptyElement'

    Returns

    this is ViewEmptyElement
  • inherited

    is( type ) → this is ViewContainerElement | ViewEditableElement | ViewRootEditableElement

    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
    

    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
    

    Parameters

    type : 'containerElement' | 'view:containerElement'

    Returns

    this is ViewContainerElement | ViewEditableElement | ViewRootEditableElement
  • inherited

    is( type ) → this is ViewUIElement

    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
    

    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
    

    Parameters

    type : 'uiElement' | 'view:uiElement'

    Returns

    this is ViewUIElement
  • inherited

    is( type ) → this is ViewDocumentFragment

    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
    

    Parameters

    type : 'documentFragment' | 'view:documentFragment'

    Returns

    this is ViewDocumentFragment
  • inherited

    is( type ) → this is ViewPosition

    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
    

    Parameters

    type : 'position' | 'view:position'

    Returns

    this is ViewPosition
  • inherited

    is( type ) → this is ViewSelection | ViewDocumentSelection

    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
    

    Parameters

    type : 'selection' | 'view:selection'

    Returns

    this is ViewSelection | ViewDocumentSelection
  • inherited

    is( type, name ) → boolean

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

    is( type, name ) → boolean

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

    is( type, name ) → boolean

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

    is( type, name ) → boolean

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

    is( type, name ) → boolean

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

    is( type, name ) → boolean

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

    is( type, name ) → boolean

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

    is( type, name ) → boolean

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

    is( type ) → this is ViewDocumentSelection

    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
    

    Parameters

    type : 'documentSelection' | 'view:documentSelection'

    Returns

    this is ViewDocumentSelection
  • inherited

    is( type ) → this is ViewRange

    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
    

    Parameters

    type : 'range' | 'view:range'

    Returns

    this is ViewRange
  • inherited

    is( type ) → this is ViewTextProxy

    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
    

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

    is( type ) → this is ViewText

    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
    

    Parameters

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

    Returns

    this is ViewText
  • inherited

    is( type ) → this is ViewText | ViewNode | ViewElement | ViewAttributeElement | ViewContainerElement | ViewEditableElement | ViewEmptyElement | ViewRawElement | ViewRootEditableElement | ViewUIElement

    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
    

    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
    

    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
    

    Parameters

    type : 'node' | 'view:node'

    Returns

    this is ViewText | ViewNode | ViewElement | ViewAttributeElement | ViewContainerElement | ViewEditableElement | ViewEmptyElement | ViewRawElement | ViewRootEditableElement | ViewUIElement
  • isAfter( otherPosition ) → boolean

    Checks whether this position is located after given position. When method returns false it does not mean that this position is before give one. Two positions may be located inside separate roots and in that situation this method will still return false.

    Parameters

    otherPosition : ViewPosition

    Position to compare with.

    Returns

    boolean

    Returns true if this position is after given position.

    Related:

  • isBefore( otherPosition ) → boolean

    Checks whether this position is located before given position. When method returns false it does not mean that this position is after give one. Two positions may be located inside separate roots and in that situation this method will still return false.

    Parameters

    otherPosition : ViewPosition

    Position to compare with.

    Returns

    boolean

    Returns true if this position is before given position.

    Related:

  • isEqual( otherPosition ) → boolean

    Checks whether this position equals given position.

    Parameters

    otherPosition : ViewPosition

    Position to compare with.

    Returns

    boolean

    True if positions are same.

Static methods

  • internal static

    _createAfter( item ) → ViewPosition

    Creates a new position after given view item.

    Parameters

    item : ViewItem

    View item after which the position should be located.

    Returns

    ViewPosition
  • internal static

    _createAt( itemOrPosition, [ offset ] ) → ViewPosition

    Creates position at the given location. The location can be specified as:

    • a position,
    • parent element and offset (offset defaults to 0),
    • parent element and 'end' (sets position at the end of that element),
    • view item and 'before' or 'after' (sets position before or after given view item).

    This method is a shortcut to other constructors such as:

    Parameters

    itemOrPosition : ViewPosition | ViewItem
    [ offset ] : ViewPositionOffset

    Offset or one of the flags. Used only when first parameter is a view item.

    Returns

    ViewPosition
  • internal static

    _createBefore( item ) → ViewPosition

    Creates a new position before given view item.

    Parameters

    item : ViewItem

    View item before which the position should be located.

    Returns

    ViewPosition