ViewPosition (engine/view)
@ckeditor/ckeditor5-engine/src/view/position
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
-
readonly
editableElement : null | ViewEditableElement
module:engine/view/position~ViewPosition#editableElement
ViewEditableElement instance that contains this position, or
null
if position is not inside an editable element. -
Is
true
if position is at the end of its parent,false
otherwise. -
Is
true
if position is at the beginning of its parent,false
otherwise. -
Node directly after the position. Equals
null
when there is no node after position or position is located inside text node. -
Node directly before the position. Equals
null
when there is no node before position or position is located inside text node. -
offset : number
module:engine/view/position~ViewPosition#offset
Position offset.
-
Position parent.
-
Position's root, that is the root of the position's parent element.
Methods
-
constructor( parent, offset )
module:engine/view/position~ViewPosition#constructor
Creates a position.
Parameters
parent : ViewNode | ViewDocumentFragment
Position parent.
offset : number
Position offset.
-
clone() → ViewPosition
module:engine/view/position~ViewPosition#clone
-
compareWith( otherPosition ) → ViewPositionRelation
module:engine/view/position~ViewPosition#compareWith
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
-
getAncestors() → Array<ViewNode | ViewDocumentFragment>
module:engine/view/position~ViewPosition#getAncestors
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
module:engine/view/position~ViewPosition#getCommonAncestor
Returns a
ViewNode
orViewDocumentFragment
which is a common ancestor of both positions.Parameters
position : ViewPosition
Returns
null | ViewNode | ViewDocumentFragment
-
getLastMatchingPosition( skip, options ) → ViewPosition
module:engine/view/position~ViewPosition#getLastMatchingPosition
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 returntrue
if the value should be skipped orfalse
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
module:engine/view/position~ViewPosition#getShiftedBy
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
module:engine/view/position~ViewPosition#getWalker
Creates a TreeWalker instance with this positions as a start position.
Parameters
options : ViewTreeWalkerOptions
Object with configuration options. See
ViewTreeWalker
Defaults to
{}
Returns
-
inherited
is( type ) → this is ViewElement | ViewAttributeElement | ViewContainerElement | ViewEditableElement | ViewEmptyElement | ViewRawElement | ViewRootEditableElement | ViewUIElement
module:engine/view/position~ViewPosition#is:ELEMENT
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
-
inherited
is( type ) → this is ViewAttributeElement
module:engine/view/position~ViewPosition#is:ATTRIBUTE_ELEMENT
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
module:engine/view/position~ViewPosition#is:EDITABLE_ELEMENT
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
module:engine/view/position~ViewPosition#is:ROOT_ELEMENT
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
module:engine/view/position~ViewPosition#is:RAW_ELEMENT
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
module:engine/view/position~ViewPosition#is:EMPTY_ELEMENT
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
module:engine/view/position~ViewPosition#is:CONTAINER_ELEMENT
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
-
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
module:engine/view/position~ViewPosition#is:DOCUMENT_FRAGMENT
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
-
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
module:engine/view/position~ViewPosition#is:SELECTION
Checks whether this object is of type
ViewSelection
orViewDocumentSelection
.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
-
Checks whether the object is of type
ViewElement
or its subclass and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'element' | 'view:element'
name : N
Returns
boolean
-
inherited
is( type, name ) → boolean
module:engine/view/position~ViewPosition#is:CONTAINER_ELEMENT_NAME
Checks whether the object is of type
ViewContainerElement
or its subclass and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'containerElement' | 'view:containerElement'
name : N
Returns
boolean
-
Checks whether the object is of type
ViewEmptyElement
has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'emptyElement' | 'view:emptyElement'
name : N
Returns
boolean
-
Checks whether the object is of type
ViewRootEditableElement
and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'rootElement' | 'view:rootElement'
name : N
Returns
boolean
-
Checks whether the object is of type
ViewUIElement
and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'uiElement' | 'view:uiElement'
name : N
Returns
boolean
-
Checks whether the object is of type
ViewRawElement
and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'rawElement' | 'view:rawElement'
name : N
Returns
boolean
-
inherited
is( type, name ) → boolean
module:engine/view/position~ViewPosition#is:EDITABLE_ELEMENT_NAME
Checks whether the object is of type
ViewEditableElement
or its subclass and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'editableElement' | 'view:editableElement'
name : N
Returns
boolean
-
inherited
is( type, name ) → boolean
module:engine/view/position~ViewPosition#is:ATTRIBUTE_ELEMENT_NAME
Checks whether the object is of type
ViewAttributeElement
and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'attributeElement' | 'view:attributeElement'
name : N
Returns
boolean
-
inherited
is( type ) → this is ViewDocumentSelection
module:engine/view/position~ViewPosition#is:DOCUMENT_SELECTION
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
-
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
-
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
module:engine/view/position~ViewPosition#is:NODE
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 aViewNode
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:
orview:
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
-
isAfter( otherPosition ) → boolean
module:engine/view/position~ViewPosition#isAfter
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 returnfalse
.Parameters
otherPosition : ViewPosition
Position to compare with.
Returns
boolean
Returns
true
if this position is after given position.
Related:
-
isBefore( otherPosition ) → boolean
module:engine/view/position~ViewPosition#isBefore
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 returnfalse
.Parameters
otherPosition : ViewPosition
Position to compare with.
Returns
boolean
Returns
true
if this position is before given position.
Related:
-
isEqual( otherPosition ) → boolean
module:engine/view/position~ViewPosition#isEqual
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
module:engine/view/position~ViewPosition._createAfter
Creates a new position after given view item.
Parameters
item : ViewItem
View item after which the position should be located.
Returns
-
internal static
_createAt( itemOrPosition, [ offset ] ) → ViewPosition
module:engine/view/position~ViewPosition._createAt
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
-
internal static
_createBefore( item ) → ViewPosition
module:engine/view/position~ViewPosition._createBefore
Creates a new position before given view item.
Parameters
item : ViewItem
View item before which the position should be located.
Returns
Every day, we work hard to keep our documentation complete. Have you spotted outdated information? Is something missing? Please report it via our issue tracker.
With the release of version 42.0.0, we have rewritten much of our documentation to reflect the new import paths and features. We appreciate your feedback to help us ensure its accuracy and completeness.