selection.js 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343
  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 CKEditorError from '../../utils/ckeditorerror.js';
  7. import Range from './range.js';
  8. import Position from './position.js';
  9. import mix from '../../utils/mix.js';
  10. import EmitterMixin from '../../utils/emittermixin.js';
  11. /**
  12. * Class representing selection in tree view.
  13. *
  14. * Selection can consist of {@link engine.treeView.Range ranges} that can be added using
  15. * {@link engine.treeView.Selection#addRange addRange} and {@link engine.treeView.Selection#setRanges setRanges} methods.
  16. * Both methods create copies of provided ranges and store those copies internally. Further modifications to passed
  17. * ranges will not change selection's state.
  18. * Selection's ranges can be obtained via {@link engine.treeView.Selection#getRanges getRanges},
  19. * {@link engine.treeView.Selection#getFirstRange getFirstRange} and {@link engine.treeView.Selection#getLastRange getLastRange}
  20. * methods, which return copies of ranges stored inside selection. Modifications made on these copies will not change
  21. * selection's state. Similar situation occurs when getting {@link engine.treeView.Selection#anchor anchor},
  22. * {@link engine.treeView.Selection#focus focus}, {@link engine.treeView.Selection#getFirstPosition first} and
  23. * {@link engine.treeView.Selection#getLastPosition last} positions - all will return copies of requested positions.
  24. *
  25. * @memberOf engine.treeView
  26. */
  27. export default class Selection {
  28. /**
  29. * Creates new selection instance.
  30. */
  31. constructor() {
  32. /**
  33. * Stores all ranges that are selected.
  34. *
  35. * @protected
  36. * @member {Array.<engine.treeView.Range>} engine.treeView.Selection#_ranges
  37. */
  38. this._ranges = [];
  39. /**
  40. * Specifies whether the last added range was added as a backward or forward range.
  41. *
  42. * @protected
  43. * @member {Boolean} engine.treeView.Selection#_lastRangeBackward
  44. */
  45. this._lastRangeBackward = false;
  46. }
  47. /**
  48. * Selection anchor. Anchor may be described as a position where the selection starts. Together with
  49. * {@link engine.treeView.Selection#focus focus} they define the direction of selection, which is important
  50. * when expanding/shrinking selection. Anchor is always the start or end of the most recent added range.
  51. * It may be a bit unintuitive when there are multiple ranges in selection.
  52. *
  53. * @see engine.treeView.Selection#focus
  54. * @type {engine.treeView.Position}
  55. */
  56. get anchor() {
  57. if ( !this._ranges.length ) {
  58. return null;
  59. }
  60. const range = this._ranges[ this._ranges.length - 1 ];
  61. const anchor = this._lastRangeBackward ? range.end : range.start;
  62. return Position.createFromPosition( anchor );
  63. }
  64. /**
  65. * Selection focus. Focus is a position where the selection ends.
  66. *
  67. * @see engine.treeView.Selection#anchor
  68. * @type {engine.treeView.Position}
  69. */
  70. get focus() {
  71. if ( !this._ranges.length ) {
  72. return null;
  73. }
  74. const range = this._ranges[ this._ranges.length - 1 ];
  75. const focus = this._lastRangeBackward ? range.start : range.end;
  76. return Position.createFromPosition( focus );
  77. }
  78. /**
  79. * Returns whether the selection is collapsed. Selection is collapsed when there is exactly one range which is
  80. * collapsed.
  81. *
  82. * @type {Boolean}
  83. */
  84. get isCollapsed() {
  85. return this.rangeCount === 1 && this._ranges[ 0 ].isCollapsed;
  86. }
  87. /**
  88. * Returns number of ranges in selection.
  89. *
  90. * @type {Number}
  91. */
  92. get rangeCount() {
  93. return this._ranges.length;
  94. }
  95. /**
  96. * Adds a range to the selection. Added range is copied. This means that passed range is not saved in the
  97. * selection instance and you can safely operate on it.
  98. *
  99. * Accepts a flag describing in which way the selection is made - passed range might be selected from
  100. * {@link engine.treeView.Range#start start} to {@link engine.treeView.Range#end end}
  101. * or from {@link engine.treeView.Range#end end} to {@link engine.treeView.Range#start start}.
  102. * The flag is used to set {@link engine.treeView.Selection#anchor anchor} and
  103. * {@link engine.treeView.Selection#focus focus} properties.
  104. *
  105. * Throws {@link utils.CKEditorError CKEditorError} `view-selection-range-intersects` if added range intersects
  106. * with ranges already stored in Selection instance.
  107. *
  108. * @fires engine.treeView.Selection#change
  109. * @param {engine.treeView.Range} range
  110. */
  111. addRange( range, isBackward ) {
  112. this._pushRange( range );
  113. this._lastRangeBackward = !!isBackward;
  114. this.fire( 'change' );
  115. }
  116. /**
  117. * Returns an iterator that contains copies of all ranges added to the selection.
  118. *
  119. * @returns {Iterator.<engine.treeView.Range>}
  120. */
  121. *getRanges() {
  122. for ( let range of this._ranges ) {
  123. yield Range.createFromRange( range );
  124. }
  125. }
  126. /**
  127. * Returns copy of the first range in the selection. First range is the one which
  128. * {@link engine.treeView.Range#start start} position {@link engine.treeView.Position#isBefore is before} start
  129. * position of all other ranges (not to confuse with the first range added to the selection).
  130. * Returns `null` if no ranges are added to selection.
  131. *
  132. * @returns {engine.treeView.Range|null}
  133. */
  134. getFirstRange() {
  135. let first = null;
  136. for ( let range of this._ranges ) {
  137. if ( !first || range.start.isBefore( first.start ) ) {
  138. first = range;
  139. }
  140. }
  141. return first ? Range.createFromRange( first ) : null;
  142. }
  143. /**
  144. * Returns copy of the last range in the selection. Last range is the one which {@link engine.treeView.Range#end end}
  145. * position {@link engine.treeView.Position#isAfter is after} end position of all other ranges (not to confuse
  146. * with the last range added to the selection). Returns `null` if no ranges are added to selection.
  147. *
  148. * @returns {engine.treeView.Range|null}
  149. */
  150. getLastRange() {
  151. let last = null;
  152. for ( let range of this._ranges ) {
  153. if ( !last || range.end.isAfter( last.end ) ) {
  154. last = range;
  155. }
  156. }
  157. return last ? Range.createFromRange( last ) : null;
  158. }
  159. /**
  160. * Returns copy of the first position in the selection. First position is the position that
  161. * {@link engine.treeView.Position#isBefore is before} any other position in the selection ranges.
  162. * Returns `null` if no ranges are added to selection.
  163. *
  164. * @returns {engine.treeView.Position|null}
  165. */
  166. getFirstPosition() {
  167. const firstRange = this.getFirstRange();
  168. return firstRange ? Position.createFromPosition( firstRange.start ) : null;
  169. }
  170. /**
  171. * Returns copy of the last position in the selection. Last position is the position that
  172. * {@link engine.treeView.Position#isAfter is after} any other position in the selection ranges.
  173. * Returns `null` if no ranges are added to selection.
  174. *
  175. * @returns {engine.treeView.Position|null}
  176. */
  177. getLastPosition() {
  178. const lastRange = this.getLastRange();
  179. return lastRange ? Position.createFromPosition( lastRange.end ) : null;
  180. }
  181. /**
  182. * Two selections equal if they have the same ranges and directions.
  183. *
  184. * @param {engine.treeView.Selection} otherSelection Selection to compare with.
  185. * @returns {Boolean} True if selections equal.
  186. */
  187. isEqual( otherSelection ) {
  188. const rangeCount = this.rangeCount;
  189. if ( rangeCount != otherSelection.rangeCount ) {
  190. return false;
  191. }
  192. for ( let i = 0; i < this.rangeCount; i++ ) {
  193. if ( !this._ranges[ i ].isEqual( otherSelection._ranges[ i ] ) ) {
  194. return false;
  195. }
  196. }
  197. return this._lastRangeBackward === otherSelection._lastRangeBackward;
  198. }
  199. /**
  200. * Removes all ranges that were added to the selection.
  201. *
  202. * @fires engine.treeView.Selection#change
  203. */
  204. removeAllRanges() {
  205. if ( this._ranges.length ) {
  206. this._ranges = [];
  207. this.fire( 'change' );
  208. }
  209. }
  210. /**
  211. * Replaces all ranges that were added to the selection with given array of ranges. Last range of the array
  212. * is treated like the last added range and is used to set {@link engine.treeView.Selection#anchor anchor} and
  213. * {@link engine.treeView.Selection#focus focus}. Accepts a flag describing in which way the selection is made
  214. * (see {@link engine.treeView.Selection#addRange addRange}).
  215. *
  216. * @fires engine.treeView.Selection#change
  217. * @param {Array.<engine.treeView.Range>} newRanges Array of ranges to set.
  218. * @param {Boolean} [isLastBackward] Flag describing if last added range was selected forward - from start to end
  219. * (`false`) or backward - from end to start (`true`). Defaults to `false`.
  220. */
  221. setRanges( newRanges, isLastBackward ) {
  222. this._ranges = [];
  223. for ( let range of newRanges ) {
  224. this._pushRange( range );
  225. }
  226. this._lastRangeBackward = !!isLastBackward;
  227. this.fire( 'change' );
  228. }
  229. /**
  230. * Set this selection's ranges and direction to the ranges and direction of the given selection.
  231. *
  232. * @param {engine.treeView.Selection} otherSelection Other selection.
  233. */
  234. setTo( otherSelection ) {
  235. this.removeAllRanges();
  236. for ( let range of otherSelection.getRanges() ) {
  237. this._pushRange( range );
  238. }
  239. this._lastRangeBackward = otherSelection._lastRangeBackward;
  240. }
  241. /**
  242. * Collapses selection to the {@link engine.treeView.Selection#getFirstPosition first position} in stored ranges.
  243. * All ranges will be removed beside one collapsed range. Nothing will be changed if there are no ranges stored
  244. * inside selection.
  245. *
  246. * @fires engine.treeView.Selection#change
  247. */
  248. collapseToStart() {
  249. const startPosition = this.getFirstPosition();
  250. if ( startPosition !== null ) {
  251. this.setRanges( [ new Range( startPosition, startPosition ) ] );
  252. this.fire( 'change' );
  253. }
  254. }
  255. /**
  256. * Collapses selection to the {@link engine.treeView.Selection#getLastPosition last position} in stored ranges.
  257. * All ranges will be removed beside one collapsed range. Nothing will be changed if there are no ranges stored
  258. * inside selection.
  259. *
  260. * @fires engine.treeView.Selection#change
  261. */
  262. collapseToEnd() {
  263. const endPosition = this.getLastPosition();
  264. if ( endPosition !== null ) {
  265. this.setRanges( [ new Range( endPosition, endPosition ) ] );
  266. this.fire( 'change' );
  267. }
  268. }
  269. /**
  270. * Adds range to selection - creates copy of given range so it can be safely used and modified.
  271. *
  272. * Throws {@link utils.CKEditorError CKEditorError} `view-selection-range-intersects` if added range intersects
  273. * with ranges already stored in selection instance.
  274. *
  275. * @private
  276. * @param {engine.treeView.Range} range
  277. */
  278. _pushRange( range ) {
  279. for ( let storedRange of this._ranges ) {
  280. if ( range.isIntersecting( storedRange ) ) {
  281. /**
  282. * Trying to add a range that intersects with another range from selection.
  283. *
  284. * @error view-selection-range-intersects
  285. * @param {engine.treeView.Range} addedRange Range that was added to the selection.
  286. * @param {engine.treeView.Range} intersectingRange Range from selection that intersects with `addedRange`.
  287. */
  288. throw new CKEditorError(
  289. 'view-selection-range-intersects: Trying to add a range that intersects with another range from selection.',
  290. { addedRange: range, intersectingRange: storedRange }
  291. );
  292. }
  293. }
  294. this._ranges.push( Range.createFromRange( range ) );
  295. }
  296. }
  297. mix( Selection, EmitterMixin );
  298. /**
  299. * Fired whenever selection ranges are changed through {@link engine.treeView.Selection Selection API}.
  300. *
  301. * @event engine.treeView.Selection#change
  302. */