liveposition.js 6.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185
  1. /**
  2. * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  4. */
  5. /**
  6. * @module engine/model/liveposition
  7. */
  8. import Position from './position';
  9. import EmitterMixin from '@ckeditor/ckeditor5-utils/src/emittermixin';
  10. import mix from '@ckeditor/ckeditor5-utils/src/mix';
  11. import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
  12. /**
  13. * `LivePosition` is a type of {@link module:engine/model/position~Position Position}
  14. * that updates itself as {@link module:engine/model/document~Document document}
  15. * is changed through operations. It may be used as a bookmark.
  16. *
  17. * **Note:** Contrary to {@link module:engine/model/position~Position}, `LivePosition` works only in roots that are
  18. * {@link module:engine/model/rootelement~RootElement}.
  19. * If {@link module:engine/model/documentfragment~DocumentFragment} is passed, error will be thrown.
  20. *
  21. * **Note:** Be very careful when dealing with `LivePosition`. Each `LivePosition` instance bind events that might
  22. * have to be unbound.
  23. * Use {@link module:engine/model/liveposition~LivePosition#detach} whenever you don't need `LivePosition` anymore.
  24. *
  25. * @extends module:engine/model/position~Position
  26. */
  27. export default class LivePosition extends Position {
  28. /**
  29. * Creates a live position.
  30. *
  31. * @see module:engine/model/position~Position
  32. * @param {module:engine/model/rootelement~RootElement} root
  33. * @param {Array.<Number>} path
  34. * @param {module:engine/model/position~PositionStickiness} [stickiness]
  35. */
  36. constructor( root, path, stickiness = 'toNone' ) {
  37. super( root, path, stickiness );
  38. if ( !this.root.is( 'rootElement' ) ) {
  39. /**
  40. * LivePosition's root has to be an instance of RootElement.
  41. *
  42. * @error liveposition-root-not-rootelement
  43. */
  44. throw new CKEditorError(
  45. 'model-liveposition-root-not-rootelement: LivePosition\'s root has to be an instance of RootElement.',
  46. root
  47. );
  48. }
  49. bindWithDocument.call( this );
  50. }
  51. /**
  52. * Unbinds all events previously bound by `LivePosition`. Use it whenever you don't need `LivePosition` instance
  53. * anymore (i.e. when leaving scope in which it was declared or before re-assigning variable that was
  54. * referring to it).
  55. */
  56. detach() {
  57. this.stopListening();
  58. }
  59. /**
  60. * Checks whether this object is of the given.
  61. *
  62. * livePosition.is( 'position' ); // -> true
  63. * livePosition.is( 'model:position' ); // -> true
  64. * livePosition.is( 'liveposition' ); // -> true
  65. * livePosition.is( 'model:livePosition' ); // -> true
  66. *
  67. * livePosition.is( 'view:position' ); // -> false
  68. * livePosition.is( 'documentSelection' ); // -> false
  69. *
  70. * {@link module:engine/model/node~Node#is Check the entire list of model objects} which implement the `is()` method.
  71. *
  72. * @param {String} type
  73. * @returns {Boolean}
  74. */
  75. is( type ) {
  76. return type === 'livePosition' || type === 'model:livePosition' ||
  77. // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
  78. type == 'position' || type === 'model:position';
  79. }
  80. /**
  81. * Creates a {@link module:engine/model/position~Position position instance}, which is equal to this live position.
  82. *
  83. * @returns {module:engine/model/position~Position}
  84. */
  85. toPosition() {
  86. return new Position( this.root, this.path.slice(), this.stickiness );
  87. }
  88. /**
  89. * Creates a `LivePosition` instance that is equal to position.
  90. *
  91. * @param {module:engine/model/position~Position} position
  92. * @param {module:engine/model/position~PositionStickiness} [stickiness]
  93. * @returns {module:engine/model/position~Position}
  94. */
  95. static fromPosition( position, stickiness ) {
  96. return new this( position.root, position.path.slice(), stickiness ? stickiness : position.stickiness );
  97. }
  98. /**
  99. * @static
  100. * @protected
  101. * @method module:engine/model/liveposition~LivePosition._createAfter
  102. * @see module:engine/model/position~Position._createAfter
  103. * @param {module:engine/model/node~Node} node
  104. * @param {module:engine/model/position~PositionStickiness} [stickiness='toNone']
  105. * @returns {module:engine/model/liveposition~LivePosition}
  106. */
  107. /**
  108. * @static
  109. * @protected
  110. * @method module:engine/model/liveposition~LivePosition._createBefore
  111. * @see module:engine/model/position~Position._createBefore
  112. * @param {module:engine/model/node~Node} node
  113. * @param {module:engine/model/position~PositionStickiness} [stickiness='toNone']
  114. * @returns {module:engine/model/liveposition~LivePosition}
  115. */
  116. /**
  117. * @static
  118. * @protected
  119. * @method module:engine/model/liveposition~LivePosition._createAt
  120. * @see module:engine/model/position~Position._createAt
  121. * @param {module:engine/model/item~Item|module:engine/model/position~Position} itemOrPosition
  122. * @param {Number|'end'|'before'|'after'} [offset]
  123. * @param {module:engine/model/position~PositionStickiness} [stickiness='toNone']
  124. * @returns {module:engine/model/liveposition~LivePosition}
  125. */
  126. /**
  127. * Fired when `LivePosition` instance is changed due to changes on {@link module:engine/model/document~Document}.
  128. *
  129. * @event module:engine/model/liveposition~LivePosition#change
  130. * @param {module:engine/model/position~Position} oldPosition Position equal to this live position before it got changed.
  131. */
  132. }
  133. // Binds this `LivePosition` to the {@link module:engine/model/document~Document document} that owns
  134. // this position's {@link module:engine/model/position~Position#root root}.
  135. //
  136. // @private
  137. function bindWithDocument() {
  138. this.listenTo(
  139. this.root.document.model,
  140. 'applyOperation',
  141. ( event, args ) => {
  142. const operation = args[ 0 ];
  143. if ( !operation.isDocumentOperation ) {
  144. return;
  145. }
  146. transform.call( this, operation );
  147. },
  148. { priority: 'low' }
  149. );
  150. }
  151. // Updates this position accordingly to the updates applied to the model. Bases on change events.
  152. //
  153. // @private
  154. // @param {module:engine/model/operation/operation~Operation} operation Executed operation.
  155. function transform( operation ) {
  156. const result = this.getTransformedByOperation( operation );
  157. if ( !this.isEqual( result ) ) {
  158. const oldPosition = this.toPosition();
  159. this.path = result.path;
  160. this.root = result.root;
  161. this.fire( 'change', oldPosition );
  162. }
  163. }
  164. mix( LivePosition, EmitterMixin );