LivePosition (engine/model)

@ckeditor/ckeditor5-engine/src/model/liveposition

Properties

• readonly inherited

  index : Numbermodule:engine/model/liveposition~LivePosition#index

  See source

  Position offset converted to an index in position's parent node. It is equal to the index of a node after this position. If position is placed in text node, position index is equal to the index of that text node.

• readonly inherited

  isAtEnd : Booleanmodule:engine/model/liveposition~LivePosition#isAtEnd

  See source

  Is true if position is at the end of its parent, false otherwise.

• readonly inherited

  isAtStart : Booleanmodule:engine/model/liveposition~LivePosition#isAtStart

  See source

  Is true if position is at the beginning of its parent, false otherwise.

• readonly inherited

  nodeAfter : Node | nullmodule:engine/model/liveposition~LivePosition#nodeAfter

  See source

  Node directly after this position or null if this position is in text node.

• readonly inherited

  nodeBefore : Node | nullmodule:engine/model/liveposition~LivePosition#nodeBefore

  See source

  Node directly before this position or null if this position is in text node.

• inherited

  offset : Numbermodule:engine/model/liveposition~LivePosition#offset

  See source

  Offset at which this position is located in its parent. It is equal to the last item in position path.

• readonly inherited

  parent : Element | DocumentFragmentmodule:engine/model/liveposition~LivePosition#parent

  See source

  Parent element of this position.

  Keep in mind that parent value is calculated when the property is accessed. If position path leads to a non-existing element, parent property will throw error.

  Also it is a good idea to cache parent property if it is used frequently in an algorithm (i.e. in a long loop).

• readonly inherited

  path : Array.<Number>module:engine/model/liveposition~LivePosition#path

  See source

  Position of the node in the tree. Path contains offsets, not indexes.

  Position can be placed before, after or in a node if that node has offsetSize greater than 1. Items in position path are starting offsets of position ancestors, starting from direct root children, down to the position offset in it's parent.

  ROOT
   |- P            before: [ 0 ]         after: [ 1 ]
   |- UL           before: [ 1 ]         after: [ 2 ]
      |- LI        before: [ 1, 0 ]      after: [ 1, 1 ]
      |  |- foo    before: [ 1, 0, 0 ]   after: [ 1, 0, 3 ]
      |- LI        before: [ 1, 1 ]      after: [ 1, 2 ]
         |- bar    before: [ 1, 1, 0 ]   after: [ 1, 1, 3 ]
  

  foo and bar are representing text nodes. Since text nodes has offset size greater than 1 you can place position offset between their start and end:

  ROOT
   |- P
   |- UL
      |- LI
      |  |- f^o|o  ^ has path: [ 1, 0, 1 ]   | has path: [ 1, 0, 2 ]
      |- LI
         |- b^a|r  ^ has path: [ 1, 1, 1 ]   | has path: [ 1, 1, 2 ]
  

• readonly inherited

  root : Element | DocumentFragmentmodule:engine/model/liveposition~LivePosition#root

  See source

  Root of the position path.

• inherited

  stickiness : PositionStickinessmodule:engine/model/liveposition~LivePosition#stickiness

  See source

  Position stickiness. See PositionStickiness.

• readonly inherited

  textNode : Text | nullmodule:engine/model/liveposition~LivePosition#textNode

  See source

  Returns text node instance in which this position is placed or null if this position is not in a text node.

Methods

• constructor( root, path, [ stickiness ] )module:engine/model/liveposition~LivePosition#constructor

  See source

  Creates a live position.

  Parameters

  root : RootElement

  path : Array.<Number>

  [ stickiness ] : PositionStickiness

  Defaults to toNone

  Related:

  • Position

• inherited

  clone() → Positionmodule:engine/model/liveposition~LivePosition#clone

  See source

  Returns a new position that is equal to current position.

  Returns

  Position

• inherited

  compareWith( otherPosition ) → PositionRelationmodule:engine/model/liveposition~LivePosition#compareWith

  See source

  Checks whether this position is before or after given position.

  This method is safe to use it on non-existing positions (for example during operational transformation).

  Parameters

  otherPosition : Position

  Position to compare with.

  Returns

  PositionRelation

• detach()module:engine/model/liveposition~LivePosition#detach

  See source

  Unbinds all events previously bound by LivePosition. Use it whenever you don't need LivePosition instance anymore (i.e. when leaving scope in which it was declared or before re-assigning variable that was referring to it).

• inherited

  findAncestor( parentName ) → Element | nullmodule:engine/model/liveposition~LivePosition#findAncestor

  See source

  Returns the parent element of the given name. Returns null if the position is not inside the desired parent.

  Parameters

  parentName : String

  The name of the parent element to find.

  Returns

  Element | null

• inherited

  getAncestors() → Array.<Item>module:engine/model/liveposition~LivePosition#getAncestors

  See source

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

  Returns

  Array.<Item>

  Array with ancestors.

• inherited

  getCommonAncestor( position ) → Element | DocumentFragment | nullmodule:engine/model/liveposition~LivePosition#getCommonAncestor

  See source

  Returns an Element or DocumentFragment which is a common ancestor of both positions. The roots of these two positions must be identical.

  Parameters

  position : Position

  The second position.

  Returns

  Element | DocumentFragment | null

• inherited

  getCommonPath( position ) → Array.<Number>module:engine/model/liveposition~LivePosition#getCommonPath

  See source

  Returns the slice of two position paths which is identical. The roots of these two paths must be identical.

  This method is safe to use it on non-existing positions (for example during operational transformation).

  Parameters

  position : Position

  The second position.

  Returns

  Array.<Number>

  The common path.

• inherited

  getLastMatchingPosition( skip, options ) → Positionmodule:engine/model/liveposition~LivePosition#getLastMatchingPosition

  See source

  Gets the farthest position which matches the callback using TreeWalker.

  For example:

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

  Parameters

  skip : function

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

  options : Object

  Object with configuration options. See TreeWalker.

  Returns

  Position

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

• inherited

  getParentPath() → Array.<Number>module:engine/model/liveposition~LivePosition#getParentPath

  See source

  Returns a path to this position's parent. Parent path is equal to position path but without the last item.

  This method is safe to use it on non-existing positions (for example during operational transformation).

  Returns

  Array.<Number>

  Path to the parent.

• inherited

  getShiftedBy( shift ) → Positionmodule:engine/model/liveposition~LivePosition#getShiftedBy

  See source

  Returns a new instance of Position, that has same parent but it's offset is shifted by shift value (can be a negative value).

  This method is safe to use it on non-existing positions (for example during operational transformation).

  Parameters

  shift : Number

  Offset shift. Can be a negative value.

  Returns

  Position

  Shifted position.

• inherited

  getTransformedByOperation( operation ) → Positionmodule:engine/model/liveposition~LivePosition#getTransformedByOperation

  See source

  Returns a copy of this position that is transformed by given operation.

  The new position's parameters are updated accordingly to the effect of the operation.

  For example, if n nodes are inserted before the position, the returned position offset will be increased by n. If the position was in a merged element, it will be accordingly moved to the new element, etc.

  This method is safe to use it on non-existing positions (for example during operational transformation).

  Parameters

  operation : Operation

  Operation to transform by.

  Returns

  Position

  Transformed position.

• inherited

  hasSameParentAs( position ) → Booleanmodule:engine/model/liveposition~LivePosition#hasSameParentAs

  See source

  Checks if two positions are in the same parent.

  This method is safe to use it on non-existing positions (for example during operational transformation).

  Parameters

  position : Position

  Position to compare with.

  Returns

  Boolean

  true if positions have the same parent, false otherwise.

• inherited

  is( type ) → Booleanmodule:engine/model/liveposition~LivePosition#is

  See source

  Checks whether this object is of the given.

  position.is( 'position' ); // -> true
  position.is( 'model:position' ); // -> true
  
  position.is( 'view:position' ); // -> false
  position.is( 'documentSelection' ); // -> false
  

  Check the entire list of model objects which implement the is() method.

  Parameters

  type : String

  Returns

  Boolean

• inherited

  isAfter( otherPosition ) → Booleanmodule:engine/model/liveposition~LivePosition#isAfter

  See source

  Checks whether this position is after given position.

  This method is safe to use it on non-existing positions (for example during operational transformation).

  Parameters

  otherPosition : Position

  Position to compare with.

  Returns

  Boolean

  True if this position is after given position.

  Related:

  • Position#isBefore

• inherited

  isBefore( otherPosition ) → Booleanmodule:engine/model/liveposition~LivePosition#isBefore

  See source

  Checks whether this position is before given position.

  Note: watch out when using negation of the value returned by this method, because the negation will also be true if positions are in different roots and you might not expect this. You should probably use a.isAfter( b ) || a.isEqual( b ) or !a.isBefore( p ) && a.root == b.root in most scenarios. If your condition uses multiple isAfter and isBefore checks, build them so they do not use negated values, i.e.:

  if ( a.isBefore( b ) && c.isAfter( d ) ) {
  	// do A.
  } else {
  	// do B.
  }
  

  or, if you have only one if-branch:

  if ( !( a.isBefore( b ) && c.isAfter( d ) ) {
  	// do B.
  }
  

  rather than:

  if ( !a.isBefore( b ) || && !c.isAfter( d ) ) {
  	// do B.
  } else {
  	// do A.
  }
  

  This method is safe to use it on non-existing positions (for example during operational transformation).

  Parameters

  otherPosition : Position

  Position to compare with.

  Returns

  Boolean

  True if this position is before given position.

• inherited

  isEqual( otherPosition ) → Booleanmodule:engine/model/liveposition~LivePosition#isEqual

  See source

  Checks whether this position is equal to given position.

  This method is safe to use it on non-existing positions (for example during operational transformation).

  Parameters

  otherPosition : Position

  Position to compare with.

  Returns

  Boolean

  True if positions are same.

• inherited

  isTouching( otherPosition ) → Booleanmodule:engine/model/liveposition~LivePosition#isTouching

  See source

  Checks whether this position is touching given position. Positions touch when there are no text nodes or empty nodes in a range between them. Technically, those positions are not equal but in many cases they are very similar or even indistinguishable.

  Parameters

  otherPosition : Position

  Position to compare with.

  Returns

  Boolean

  True if positions touch.

• toPosition() → Positionmodule:engine/model/liveposition~LivePosition#toPosition

  See source

  Creates a position instance, which is equal to this live position.

  Returns

  Position

• protected inherited

  _getCombined( source, target ) → Positionmodule:engine/model/liveposition~LivePosition#_getCombined

  See source

  Returns a new position that is a combination of this position and given positions.

  The combined position is a copy of this position transformed by moving a range starting at source position to the target position. It is expected that this position is inside the moved range.

  Example:

  let original = model.createPositionFromPath( root, [ 2, 3, 1 ] );
  let source = model.createPositionFromPath( root, [ 2, 2 ] );
  let target = model.createPositionFromPath( otherRoot, [ 1, 1, 3 ] );
  original._getCombined( source, target ); // path is [ 1, 1, 4, 1 ], root is `otherRoot`
  

  Explanation:

  We have a position [ 2, 3, 1 ] and move some nodes from [ 2, 2 ] to [ 1, 1, 3 ]. The original position was inside moved nodes and now should point to the new place. The moved nodes will be after positions [ 1, 1, 3 ], [ 1, 1, 4 ], [ 1, 1, 5 ]. Since our position was in the second moved node, the transformed position will be in a sub-tree of a node at [ 1, 1, 4 ]. Looking at original path, we took care of [ 2, 3 ] part of it. Now we have to add the rest of the original path to the transformed path. Finally, the transformed position will point to [ 1, 1, 4, 1 ].

  Parameters

  source : Position

  Beginning of the moved range.

  target : Position

  Position where the range is moved.

  Returns

  Position

  Combined position.

• protected inherited

  _getTransformedByDeletion( deletePosition, howMany ) → Position | nullmodule:engine/model/liveposition~LivePosition#_getTransformedByDeletion

  See source

  Returns a copy of this position that is updated by removing howMany nodes starting from deletePosition. It may happen that this position is in a removed node. If that is the case, null is returned instead.

  Parameters

  deletePosition : Position

  Position before the first removed node.

  howMany : Number

  How many nodes are removed.

  Returns

  Position | null

  Transformed position or null.

• protected inherited

  _getTransformedByInsertOperation( operation ) → Positionmodule:engine/model/liveposition~LivePosition#_getTransformedByInsertOperation

  See source

  Returns a copy of this position transformed by an insert operation.

  Parameters

  operation : InsertOperation

  Returns

  Position

• protected inherited

  _getTransformedByInsertion( insertPosition, howMany ) → Positionmodule:engine/model/liveposition~LivePosition#_getTransformedByInsertion

  See source

  Returns a copy of this position that is updated by inserting howMany nodes at insertPosition.

  Parameters

  insertPosition : Position

  Position where nodes are inserted.

  howMany : Number

  How many nodes are inserted.

  Returns

  Position

  Transformed position.

• protected inherited

  _getTransformedByMergeOperation( operation ) → Positionmodule:engine/model/liveposition~LivePosition#_getTransformedByMergeOperation

  See source

  Returns a copy of this position transformed by merge operation.

  Parameters

  operation : MergeOperation

  Returns

  Position

• protected inherited

  _getTransformedByMove( sourcePosition, targetPosition, howMany ) → Positionmodule:engine/model/liveposition~LivePosition#_getTransformedByMove

  See source

  Returns a copy of this position that is updated by moving howMany nodes from sourcePosition to targetPosition.

  Parameters

  sourcePosition : Position

  Position before the first element to move.

  targetPosition : Position

  Position where moved elements will be inserted.

  howMany : Number

  How many consecutive nodes to move, starting from sourcePosition.

  Returns

  Position

  Transformed position.

• protected inherited

  _getTransformedByMoveOperation( operation ) → Positionmodule:engine/model/liveposition~LivePosition#_getTransformedByMoveOperation

  See source

  Returns a copy of this position transformed by a move operation.

  Parameters

  operation : MoveOperation

  Returns

  Position

• protected inherited

  _getTransformedBySplitOperation( operation ) → Positionmodule:engine/model/liveposition~LivePosition#_getTransformedBySplitOperation

  See source

  Returns a copy of this position transformed by a split operation.

  Parameters

  operation : SplitOperation

  Returns

  Position

Static methods

• inherited static

  fromJSON( json, doc ) → Positionmodule:engine/model/liveposition~LivePosition.fromJSON

  See source

  Creates a Position instance from given plain object (i.e. parsed JSON string).

  Parameters

  json : Object

  Plain object to be converted to Position.

  doc : Document

  Document object that will be position owner.

  Returns

  Position

  Position instance created using given plain object.

• static

  fromPosition( position, [ stickiness ] ) → LivePositionmodule:engine/model/liveposition~LivePosition.fromPosition

  See source

  Creates a LivePosition instance that is equal to position.

  Parameters

  position : Position

  [ stickiness ] : PositionStickiness

  Returns

  LivePosition

• protected static

  _createAfter( node, [ stickiness ] ) → LivePositionmodule:engine/model/liveposition~LivePosition._createAfter

  See source

  Parameters

  node : Node

  [ stickiness ] : PositionStickiness

  Defaults to 'toNone'

  Returns

  LivePosition

  Related:

  • Position._createAfter

• protected static

  _createAt( itemOrPosition, [ offset ], [ stickiness ] ) → LivePositionmodule:engine/model/liveposition~LivePosition._createAt

  See source

  Parameters

  itemOrPosition : Item | Position

  [ offset ] : Number | 'end' | 'before' | 'after'

  [ stickiness ] : PositionStickiness

  Defaults to 'toNone'

  Returns

  LivePosition

  Related:

  • Position._createAt

• protected static

  _createBefore( node, [ stickiness ] ) → LivePositionmodule:engine/model/liveposition~LivePosition._createBefore

  See source

  Parameters

  node : Node

  [ stickiness ] : PositionStickiness

  Defaults to 'toNone'

  Returns

  LivePosition

  Related:

  • Position._createBefore

Events

• change( eventInfo, oldPosition )module:engine/model/liveposition~LivePosition#event:change

  See source

  Fired when LivePosition instance is changed due to changes on Document.

  Parameters

  eventInfo : EventInfo

  An object containing information about the fired event.

  oldPosition : Position

  Position equal to this live position before it got changed.