liveposition.js 6.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194
  1. /**
  2. * @license Copyright (c) 2003-2016, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md.
  4. */
  5. 'use strict';
  6. import RootElement from './rootelement.js';
  7. import Position from './position.js';
  8. import Range from './range.js';
  9. import EmitterMixin from '../../utils/emittermixin.js';
  10. import mix from '../../utils/mix.js';
  11. import CKEditorError from '../../utils/ckeditorerror.js';
  12. /**
  13. * `LivePosition` is a type of {@link engine.model.Position Position} that updates itself as {@link engine.model.Document document}
  14. * is changed through operations. It may be used as a bookmark.
  15. *
  16. * **Note:** Contrary to {@link engine.model.Position}, `LivePosition` works only in roots that are
  17. * {@link engine.model.RootElement}. If {@link engine.model.DocumentFragment} is passed, error will be thrown.
  18. *
  19. * **Note:** Be very careful when dealing with `LivePosition`. Each `LivePosition` instance bind events that might
  20. * have to be unbound. Use {@link engine.model.LivePosition#detach} whenever you don't need `LivePosition` anymore.
  21. *
  22. * @memberOf engine.model
  23. * @extends engine.model.Position
  24. */
  25. export default class LivePosition extends Position {
  26. /**
  27. * Creates a live position.
  28. *
  29. * @see engine.model.Position
  30. * @param {engine.model.RootElement} root
  31. * @param {Array.<Number>} path
  32. * @param {engine.model.PositionStickiness} [stickiness] Defaults to `'STICKS_TO_NEXT'`.
  33. * See {@link engine.model.LivePosition#stickiness}.
  34. */
  35. constructor( root, path, stickiness ) {
  36. if ( !( root instanceof RootElement ) ) {
  37. /**
  38. * LivePosition root has to be an instance of RootElement.
  39. *
  40. * @error liveposition-root-not-rootelement
  41. */
  42. throw new CKEditorError( 'liveposition-root-not-rootelement: LivePosition root has to be an instance of RootElement.' );
  43. }
  44. super( root, path );
  45. /**
  46. * Flag representing `LivePosition` stickiness. `LivePosition` might be sticking to previous node or next node.
  47. * Whenever some nodes are inserted at the same position as `LivePosition`, `stickiness` is checked to decide if
  48. * LivePosition should be moved. Similar applies when a range of nodes is moved and one of it's boundary
  49. * position is same as `LivePosition`.
  50. *
  51. * Examples:
  52. *
  53. * Insert:
  54. * Position is at | and we insert at the same position, marked as ^:
  55. * - | sticks to previous node: `<p>f|^oo</p>` => `<p>f|baroo</p>`
  56. * - | sticks to next node: `<p>f^|oo</p>` => `<p>fbar|oo</p>`
  57. *
  58. * Move:
  59. * Position is at | and range [ ] is moved to position ^:
  60. * - | sticks to previous node: `<p>f|[oo]</p><p>b^ar</p>` => `<p>f|</p><p>booar</p>`
  61. * - | sticks to next node: `<p>f|[oo]</p><p>b^ar</p>` => `<p>f</p><p>b|ooar</p>`
  62. *
  63. * @member {engine.model.PositionStickiness} engine.model.LivePosition#stickiness
  64. */
  65. this.stickiness = stickiness || 'STICKS_TO_NEXT';
  66. bindWithDocument.call( this );
  67. }
  68. /**
  69. * Unbinds all events previously bound by `LivePosition`. Use it whenever you don't need `LivePosition` instance
  70. * anymore (i.e. when leaving scope in which it was declared or before re-assigning variable that was
  71. * referring to it).
  72. */
  73. detach() {
  74. this.stopListening();
  75. }
  76. /**
  77. * @static
  78. * @method engine.model.LivePosition.createAfter
  79. * @see engine.model.Position.createAfter
  80. * @param {engine.model.Node} node
  81. * @returns {engine.model.LivePosition}
  82. */
  83. /**
  84. * @static
  85. * @method engine.model.LivePosition.createBefore
  86. * @see engine.model.Position.createBefore
  87. * @param {engine.model.Node} node
  88. * @returns {engine.model.LivePosition}
  89. */
  90. /**
  91. * @static
  92. * @method engine.model.LivePosition.createFromParentAndOffset
  93. * @see engine.model.Position.createFromParentAndOffset
  94. * @param {engine.model.Element} parent
  95. * @param {Number} offset
  96. * @returns {engine.model.LivePosition}
  97. */
  98. /**
  99. * @static
  100. * @method engine.model.LivePosition.createFromPosition
  101. * @see engine.model.Position.createFromPosition
  102. * @param {engine.model.Position} position
  103. * @returns {engine.model.LivePosition}
  104. */
  105. }
  106. /**
  107. * Binds this `LivePosition` to the {@link engine.model.Document document} that owns
  108. * this position's {@link engine.model.Position#root root}.
  109. *
  110. * @ignore
  111. * @private
  112. * @method engine.model.LivePosition.bindWithDocument
  113. */
  114. function bindWithDocument() {
  115. /*jshint validthis: true */
  116. this.listenTo(
  117. this.root.document,
  118. 'change',
  119. ( event, type, changes ) => {
  120. transform.call( this, type, changes.range, changes.sourcePosition );
  121. },
  122. this
  123. );
  124. }
  125. /**
  126. * Updates this position accordingly to the updates applied to the model. Bases on change events.
  127. *
  128. * @ignore
  129. * @private
  130. * @method transform
  131. * @param {String} type Type of changes applied to the Tree Model.
  132. * @param {engine.model.Range} range Range containing the result of applied change.
  133. * @param {engine.model.Position} [position] Additional position parameter provided by some change events.
  134. */
  135. function transform( type, range, position ) {
  136. /*jshint validthis: true */
  137. let howMany = range.end.offset - range.start.offset;
  138. let transformed;
  139. switch ( type ) {
  140. case 'insert':
  141. let insertBefore = this.stickiness == 'STICKS_TO_NEXT';
  142. transformed = this._getTransformedByInsertion( range.start, howMany, insertBefore );
  143. break;
  144. case 'move':
  145. case 'remove':
  146. case 'reinsert':
  147. let originalRange = Range.createFromPositionAndShift( position, howMany );
  148. let gotMoved = originalRange.containsPosition( this ) ||
  149. ( originalRange.start.isEqual( this ) && this.stickiness == 'STICKS_TO_NEXT' ) ||
  150. ( originalRange.end.isEqual( this ) && this.stickiness == 'STICKS_TO_PREVIOUS' );
  151. // We can't use ._getTransformedByMove() because we have a different if-condition.
  152. if ( gotMoved ) {
  153. transformed = this._getCombined( position, range.start );
  154. } else {
  155. let insertBefore = this.stickiness == 'STICKS_TO_NEXT';
  156. transformed = this._getTransformedByMove( position, range.start, howMany, insertBefore );
  157. }
  158. break;
  159. default:
  160. return;
  161. }
  162. this.path = transformed.path;
  163. this.root = transformed.root;
  164. }
  165. mix( LivePosition, EmitterMixin );
  166. /**
  167. * Enum representing how position is "sticking" with their neighbour nodes.
  168. * Possible values: `'STICKS_TO_NEXT'`, `'STICKS_TO_PREVIOUS'`.
  169. *
  170. * @typedef {String} engine.model.PositionStickiness
  171. */