Position (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
-
editableElement : EditableElement | null
module:engine/view/position~Position#editableElement
EditableElement 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. -
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~Position#constructor
Creates a position.
Parameters
parent : Node | DocumentFragment
Position parent.
offset : Number
Position offset.
-
compareWith( otherPosition ) → PositionRelation
module:engine/view/position~Position#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 : Position
Position to compare with.
Returns
-
getAncestors() → Array
module:engine/view/position~Position#getAncestors
Returns ancestors array of this position, that is this position's parent and it's ancestors.
Returns
Array
Array with ancestors.
-
getCommonAncestor( position ) → Node | DocumentFragment | null
module:engine/view/position~Position#getCommonAncestor
Returns a
Node
orDocumentFragment
which is a common ancestor of both positions.Parameters
position : Position
Returns
Node | DocumentFragment | null
-
getLastMatchingPosition( skip, options ) → Position
module:engine/view/position~Position#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 : function
Callback function. Gets
TreeWalkerValue
and should returntrue
if the value should be skipped orfalse
if not.options : Object
Object with configuration options. See
TreeWalker
.
Returns
Position
The position after the last item which matches the
skip
callback test.
-
getShiftedBy( shift ) → Position
module:engine/view/position~Position#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
Position
Shifted position.
-
getWalker( options = { [options.boundaries], [options.singleCharacters], [options.shallow], [options.ignoreElementEnd] } )
module:engine/view/position~Position#getWalker
Creates a TreeWalker instance with this positions as a start position.
Parameters
options : Object
Object with configuration options. See
TreeWalker
Properties[ options.boundaries ] : Range
Range to define boundaries of the iterator.
[ options.singleCharacters ] : Boolean
-
Defaults to
false
[ options.shallow ] : Boolean
-
Defaults to
false
[ options.ignoreElementEnd ] : Boolean
-
Defaults to
false
-
is( type ) → Boolean
module:engine/view/position~Position#is
Checks whether this object is of the given type.
position.is( 'position' ); // -> true position.is( 'view:position' ); // -> true position.is( 'model:position' ); // -> false position.is( 'element' ); // -> false position.is( 'range' ); // -> false
Check the entire list of view objects which implement the
is()
method.Parameters
type : String
Returns
Boolean
-
isAfter( otherPosition ) → Boolean
module:engine/view/position~Position#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 : Position
Position to compare with.
Returns
Boolean
Returns
true
if this position is after given position.
Related:
-
isBefore( otherPosition ) → Boolean
module:engine/view/position~Position#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 : Position
Position to compare with.
Returns
Boolean
Returns
true
if this position is before given position.
Related:
-
isEqual( otherPosition ) → Boolean
module:engine/view/position~Position#isEqual
Checks whether this position equals given position.
Parameters
otherPosition : Position
Position to compare with.
Returns
Boolean
True if positions are same.
Static methods
-
Creates a new position after given view item.
Parameters
item : Item
View item after which the position should be located.
Returns
-
protected static
_createAt( itemOrPosition, [ offset ] )
module:engine/view/position~Position._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
-
Creates a new position before given view item.
Parameters
item : Item
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.