liverange.js 6.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190
  1. /**
  2. * @license Copyright (c) 2003-2018, 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 boundaries have changed due to changes in the
  71. * {@link module:engine/model/document~Document document}.
  72. *
  73. * @event change:range
  74. * @param {module:engine/model/range~Range} oldRange Range with start and end position equal to start and end position of this live
  75. * range before it got changed.
  76. * @param {Object} data Object with additional information about the change. Those parameters are passed from
  77. * {@link module:engine/model/document~Document#event:change document change event}.
  78. * @param {String} data.type Change type.
  79. * @param {module:engine/model/position~Position|null} deletionPosition Source position for move, remove and reinsert change types.
  80. */
  81. /**
  82. * Fired when `LiveRange` instance boundaries have not changed after a change in {@link module:engine/model/document~Document document}
  83. * but the change took place inside the range, effectively changing its content.
  84. *
  85. * @event change:content
  86. * @param {module:engine/model/range~Range} range Range with start and end position equal to start and end position of
  87. * change range.
  88. * @param {Object} data Object with additional information about the change. Those parameters are passed from
  89. * {@link module:engine/model/document~Document#event:change document change event}.
  90. * @param {String} data.type Change type.
  91. * @param {module:engine/model/batch~Batch} data.batch Batch which changed the live range.
  92. * @param {module:engine/model/range~Range} data.range Range containing the result of applied change.
  93. * @param {module:engine/model/position~Position} data.sourcePosition Source position for move, remove and reinsert change types.
  94. */
  95. }
  96. /**
  97. * Binds this `LiveRange` to the {@link module:engine/model/document~Document document}
  98. * that owns this range's {@link module:engine/model/range~Range#root root}.
  99. *
  100. * @ignore
  101. * @private
  102. * @method module:engine/model/liverange~LiveRange#bindWithDocument
  103. */
  104. function bindWithDocument() {
  105. this.listenTo(
  106. this.root.document.model,
  107. 'applyOperation',
  108. ( event, args ) => {
  109. const operation = args[ 0 ];
  110. if ( !operation.isDocumentOperation ) {
  111. return;
  112. }
  113. transform.call( this, operation );
  114. },
  115. { priority: 'low' }
  116. );
  117. }
  118. /**
  119. * Updates this range accordingly to the updates applied to the model. Bases on change events.
  120. *
  121. * @ignore
  122. * @private
  123. * @method transform
  124. * @param {module:engine/model/operation/operation~Operation} operation Executed operation.
  125. */
  126. function transform( operation ) {
  127. const ranges = this.getTransformedByOperation( operation );
  128. const result = Range.createFromRanges( ranges );
  129. const boundariesChanged = !result.isEqual( this );
  130. const contentChanged = doesOperationChangeRangeContent( this, operation );
  131. let deletionPosition = null;
  132. if ( boundariesChanged ) {
  133. if ( result.root.rootName == '$graveyard' ) {
  134. if ( operation.type == 'remove' ) {
  135. deletionPosition = operation.sourcePosition;
  136. } else {
  137. // Merge operation.
  138. deletionPosition = operation.deletionPosition;
  139. }
  140. }
  141. // If range boundaries have changed, fire `change:range` event.
  142. const oldRange = Range.createFromRange( this );
  143. this.start = result.start;
  144. this.end = result.end;
  145. this.fire( 'change:range', oldRange, { deletionPosition } );
  146. } else if ( contentChanged ) {
  147. // If range boundaries have not changed, but there was change inside the range, fire `change:content` event.
  148. this.fire( 'change:content', Range.createFromRange( this ), { deletionPosition } );
  149. }
  150. }
  151. function doesOperationChangeRangeContent( range, operation ) {
  152. switch ( operation.type ) {
  153. case 'insert':
  154. case 'split':
  155. case 'wrap':
  156. case 'unwrap':
  157. return range.containsPosition( operation.position );
  158. case 'move':
  159. case 'remove':
  160. case 'reinsert':
  161. case 'merge':
  162. return range.containsPosition( operation.sourcePosition ) ||
  163. range.start.isEqual( operation.sourcePosition ) ||
  164. range.containsPosition( operation.targetPosition );
  165. }
  166. return false;
  167. }
  168. mix( LiveRange, EmitterMixin );