liverange.js 6.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171
  1. /**
  2. * @license Copyright (c) 2003-2017, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md.
  4. */
  5. /**
  6. * @module engine/model/liverange
  7. */
  8. import Range from './range';
  9. import EmitterMixin from '@ckeditor/ckeditor5-utils/src/emittermixin';
  10. import mix from '@ckeditor/ckeditor5-utils/src/mix';
  11. /**
  12. * `LiveRange` is a type of {@link module:engine/model/range~Range Range}
  13. * that updates itself as {@link module:engine/model/document~Document document}
  14. * is changed through operations. It may be used as a bookmark.
  15. *
  16. * **Note:** Be very careful when dealing with `LiveRange`. Each `LiveRange` instance bind events that might
  17. * have to be unbound. Use {@link module:engine/model/liverange~LiveRange#detach detach} whenever you don't need `LiveRange` anymore.
  18. */
  19. export default class LiveRange extends Range {
  20. /**
  21. * Creates a live range.
  22. *
  23. * @see module:engine/model/range~Range
  24. */
  25. constructor( start, end ) {
  26. super( start, end );
  27. bindWithDocument.call( this );
  28. }
  29. /**
  30. * Unbinds all events previously bound by `LiveRange`. Use it whenever you don't need `LiveRange` instance
  31. * anymore (i.e. when leaving scope in which it was declared or before re-assigning variable that was
  32. * referring to it).
  33. */
  34. detach() {
  35. this.stopListening();
  36. }
  37. /**
  38. * @see module:engine/model/range~Range.createIn
  39. * @static
  40. * @method module:engine/model/liverange~LiveRange.createIn
  41. * @param {module:engine/model/element~Element} element
  42. * @returns {module:engine/model/liverange~LiveRange}
  43. */
  44. /**
  45. * @see module:engine/model/range~Range.createFromPositionAndShift
  46. * @static
  47. * @method module:engine/model/liverange~LiveRange.createFromPositionAndShift
  48. * @param {module:engine/model/position~Position} position
  49. * @param {Number} shift
  50. * @returns {module:engine/model/liverange~LiveRange}
  51. */
  52. /**
  53. * @see module:engine/model/range~Range.createFromParentsAndOffsets
  54. * @static
  55. * @method module:engine/model/liverange~LiveRange.createFromParentsAndOffsets
  56. * @param {module:engine/model/element~Element} startElement
  57. * @param {Number} startOffset
  58. * @param {module:engine/model/element~Element} endElement
  59. * @param {Number} endOffset
  60. * @returns {module:engine/model/liverange~LiveRange}
  61. */
  62. /**
  63. * @see module:engine/model/range~Range.createFromRange
  64. * @static
  65. * @method module:engine/model/liverange~LiveRange.createFromRange
  66. * @param {module:engine/model/range~Range} range
  67. * @returns {module:engine/model/liverange~LiveRange}
  68. */
  69. /**
  70. * Fired when `LiveRange` instance is changed due to changes in the {@link module:engine/model/document~Document document}.
  71. *
  72. * @event change
  73. * @param {module:engine/model/range~Range} oldRange Range with start and end position equal to start and end position of this live
  74. * range before it got changed.
  75. * @param {Object} data Object with additional information about the change. Those parameters are passed from
  76. * {@link module:engine/model/document~Document#event:change document change event}.
  77. * @param {String} data.type Change type.
  78. * @param {module:engine/model/batch~Batch} data.batch Batch which changed the live range.
  79. * @param {module:engine/model/range~Range} data.range Range containing the result of applied change.
  80. * @param {module:engine/model/position~Position} data.sourcePosition Source position for move, remove and reinsert change types.
  81. */
  82. }
  83. /**
  84. * Binds this `LiveRange` to the {@link module:engine/model/document~Document document}
  85. * that owns this range's {@link module:engine/model/range~Range#root root}.
  86. *
  87. * @ignore
  88. * @private
  89. * @method module:engine/model/liverange~LiveRange#bindWithDocument
  90. */
  91. function bindWithDocument() {
  92. // Operation types that a range can be transformed by.
  93. const supportedTypes = new Set( [ 'insert', 'move', 'remove', 'reinsert' ] );
  94. this.listenTo(
  95. this.root.document,
  96. 'change',
  97. ( event, type, changes, batch, deltaType ) => {
  98. if ( supportedTypes.has( type ) ) {
  99. transform.call( this, type, deltaType, batch, changes.range, changes.sourcePosition );
  100. }
  101. },
  102. { priority: 'high' }
  103. );
  104. }
  105. /**
  106. * Updates this range accordingly to the updates applied to the model. Bases on change events.
  107. *
  108. * @ignore
  109. * @private
  110. * @method transform
  111. * @param {String} [changeType] Type of change applied to the model document.
  112. * @param {String} [deltaType] Type of delta which introduced the change.
  113. * @param {module:engine/model/batch~Batch} batch Batch which changes the live range.
  114. * @param {module:engine/model/range~Range} targetRange Range containing the result of applied change.
  115. * @param {module:engine/model/position~Position} [sourcePosition] Source position for move, remove and reinsert change types.
  116. */
  117. function transform( changeType, deltaType, batch, targetRange, sourcePosition ) {
  118. const howMany = targetRange.end.offset - targetRange.start.offset;
  119. let targetPosition = targetRange.start;
  120. if ( changeType == 'move' || changeType == 'remove' || changeType == 'reinsert' ) {
  121. // Range._getTransformedByDocumentChange is expecting `targetPosition` to be "before" move
  122. // (before transformation). `targetRange.start` is already after the move happened.
  123. // We have to revert `targetPosition` to the state before the move.
  124. targetPosition = targetPosition._getTransformedByInsertion( sourcePosition, howMany );
  125. }
  126. const result = this._getTransformedByDocumentChange( changeType, deltaType, targetPosition, howMany, sourcePosition );
  127. // Decide whether moved part should be included in the range.
  128. //
  129. // First, this concerns only `move` change, because insert change includes inserted part always (changeType == 'move').
  130. // Second, this is a case only if moved range was intersecting with this range and was inserted into this range (result.length == 3).
  131. if ( ( changeType == 'move' || changeType == 'remove' || changeType == 'reinsert' ) && result.length == 3 ) {
  132. // `result[ 2 ]` is a "common part" of this range and moved range. We substitute that common part with the whole
  133. // `targetRange` because we want to include whole `targetRange` in this range.
  134. result[ 2 ] = targetRange;
  135. }
  136. const updated = Range.createFromRanges( result );
  137. // If anything changed, update the range and fire an event.
  138. if ( !updated.isEqual( this ) ) {
  139. const oldRange = Range.createFromRange( this );
  140. this.start = updated.start;
  141. this.end = updated.end;
  142. this.fire( 'change', oldRange, {
  143. type: changeType,
  144. batch,
  145. range: targetRange,
  146. sourcePosition
  147. } );
  148. }
  149. }
  150. mix( LiveRange, EmitterMixin );