8
0
Maciej Bukowski 8 سال پیش
والد
کامیت
936824c7ee
2فایلهای تغییر یافته به همراه77 افزوده شده و 77 حذف شده
  1. 34 27
      packages/ckeditor5-engine/src/model/selection.js
  2. 43 50
      packages/ckeditor5-engine/src/view/selection.js

+ 34 - 27
packages/ckeditor5-engine/src/model/selection.js

@@ -56,19 +56,26 @@ export default class Selection {
 	 *		const position = new Position( root, path );
 	 *		const selection = new Selection( position );
 	 *
-	 * 		// Creates selection at the start position of given element.
+	 * 		// Creates selection inside the node.
+	 *		const paragraph = writer.createElement( 'paragraph' );
+	 *		selection.setTo( paragraph, 'in', { backward } );
+	 *
+	 *		// Creates selection on the node.
+	 *		const paragraph = writer.createElement( 'paragraph' );
+	 *		selection.setTo( paragraph, 'on', { backward } );
+	 *
+	 * 		// Creates selection at the start position of the given element.
 	 *		const paragraph = writer.createElement( 'paragraph' );
 	 *		const selection = new Selection( paragraph, offset );
 	 *
 	 * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection|
 	 * module:engine/model/position~Position|module:engine/model/element~Element|
 	 * Iterable.<module:engine/model/range~Range>|module:engine/model/range~Range|null} selectable
-	 * @param {Object|Number|'before'|'end'|'after'|'on'|'in'} [optionsOrPlaceOrOffset]
-	 * @param {Boolean} [optionsOrPlaceOrOffset.backward]
+	 * @param {Number|'before'|'end'|'after'|'on'|'in'} [placeOrOffset]
 	 * @param {Object} [options]
 	 * @param {Boolean} [options.backward]
 	 */
-	constructor( selectable, optionsOrPlaceOrOffset, options ) {
+	constructor( selectable, placeOrOffset, options ) {
 		/**
 		 * Specifies whether the last added range was added as a backward or forward range.
 		 *
@@ -94,7 +101,7 @@ export default class Selection {
 		this._attrs = new Map();
 
 		if ( selectable ) {
-			this.setTo( selectable, optionsOrPlaceOrOffset, options );
+			this.setTo( selectable, placeOrOffset, options );
 		}
 	}
 
@@ -304,52 +311,51 @@ export default class Selection {
 	 * {@link module:engine/model/element~Element element}, {@link module:engine/model/position~Position position},
 	 * {@link module:engine/model/range~Range range}, an iterable of {@link module:engine/model/range~Range ranges} or null.
 	 *
-	 *		// Sets ranges from the given range.
+	 *		// Sets selection to the given range.
 	 *		const range = new Range( start, end );
 	 *		selection.setTo( range, { backward } );
 	 *
-	 *		// Sets ranges from the iterable of ranges.
+	 *		// Sets selection to given ranges.
 	 * 		const ranges = [ new Range( start1, end2 ), new Range( star2, end2 ) ];
 	 *		selection.setTo( ranges, { backward } );
 	 *
-	 *		// Sets ranges from the other selection.
+	 *		// Sets selection to other selection.
 	 *		// Note: It doesn't copies selection attributes.
 	 *		const otherSelection = new Selection();
 	 *		selection.setTo( otherSelection );
 	 *
-	 * 		// Sets ranges from the given document selection's ranges.
+	 * 		// Sets selection to the document selection.
 	 *		// Note: It doesn't copies selection attributes.
 	 *		const documentSelection = new DocumentSelection( doc );
 	 *		selection.setTo( documentSelection );
 	 *
-	 * 		// Sets range at the given position.
+	 * 		// Sets collapsed selection at the given position.
 	 *		const position = new Position( root, path );
 	 *		selection.setTo( position );
 	 *
-	 * 		// Sets range at the position of given node and offset.
+	 * 		// Sets collapsed selection at the position of given node and offset.
 	 *		const paragraph = writer.createElement( 'paragraph' );
 	 *		selection.setTo( paragraph, offset );
 	 *
-	 *		// Sets range inside the node.
+	 *		// Sets selection inside the node.
 	 *		const paragraph = writer.createElement( 'paragraph' );
-	 *		selection.setTo( paragraph, 'in' );
+	 *		selection.setTo( paragraph, 'in', { backward } );
 	 *
-	 *		// Sets range on the node.
+	 *		// Sets selection on the node.
 	 *		const paragraph = writer.createElement( 'paragraph' );
-	 *		selection.setTo( paragraph, 'on' );
+	 *		selection.setTo( paragraph, 'on', { backward } );
 	 *
-	 * 		// Removes all ranges.
+	 * 		// Clears selection. Removes all ranges.
 	 *		selection.setTo( null );
 	 *
 	 * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection|
 	 * module:engine/model/position~Position|module:engine/model/node~Node|
 	 * Iterable.<module:engine/model/range~Range>|module:engine/model/range~Range|null} selectable
-	 * @param {Object|Number|'before'|'end'|'after'|'on'|'in'} [optionsOrPlaceOrOffset]
-	 * @param {Boolean} [optionsOrPlaceOrOffset.backward]
+	 * @param {Number|'before'|'end'|'after'|'on'|'in'} [placeOrOffset]
 	 * @param {Object} [options]
 	 * @param {Boolean} [options.backward]
 	 */
-	setTo( selectable, optionsOrPlaceOrOffset, options ) {
+	setTo( selectable, placeOrOffset, options ) {
 		if ( selectable === null ) {
 			this._setRanges( [] );
 		} else if ( selectable instanceof Selection ) {
@@ -359,33 +365,34 @@ export default class Selection {
 			// It can't be imported here, because it would lead to circular imports.
 			this._setRanges( selectable.getRanges(), selectable.isBackward );
 		} else if ( selectable instanceof Range ) {
-			this._setRanges( [ selectable ], !!optionsOrPlaceOrOffset && !!optionsOrPlaceOrOffset.backward );
+			this._setRanges( [ selectable ], !!placeOrOffset && !!placeOrOffset.backward );
 		} else if ( selectable instanceof Position ) {
 			this._setRanges( [ new Range( selectable ) ] );
 		} else if ( selectable instanceof Node ) {
 			const backward = !!options && !!options.backward;
 			let range;
 
-			if ( optionsOrPlaceOrOffset == 'in' ) {
+			if ( placeOrOffset == 'in' ) {
 				range = Range.createIn( selectable );
-			} else if ( optionsOrPlaceOrOffset == 'on' ) {
+			} else if ( placeOrOffset == 'on' ) {
 				range = Range.createOn( selectable );
-			} else if ( optionsOrPlaceOrOffset !== undefined ) {
-				range = Range.createCollapsedAt( selectable, optionsOrPlaceOrOffset );
+			} else if ( placeOrOffset !== undefined ) {
+				range = Range.createCollapsedAt( selectable, placeOrOffset );
 			} else {
 				/**
-				 * Required second parameter when setting selection to node.
+				 * selection.setTo requires the second parameter when the first parameter is a node.
 				 *
 				 * @error model-selection-setTo-required-second-parameter
 				 */
 				throw new CKEditorError(
-					'model-selection-setTo-required-second-parameter: Required second parameter when setting selection to node.' );
+					'model-selection-setTo-required-second-parameter: ' +
+					'selection.setTo requires the second parameter when the first parameter is a node.' );
 			}
 
 			this._setRanges( [ range ], backward );
 		} else if ( isIterable( selectable ) ) {
 			// We assume that the selectable is an iterable of ranges.
-			this._setRanges( selectable, optionsOrPlaceOrOffset && !!optionsOrPlaceOrOffset.backward );
+			this._setRanges( selectable, placeOrOffset && !!placeOrOffset.backward );
 		} else {
 			/**
 			 * Cannot set selection to given place.

+ 43 - 50
packages/ckeditor5-engine/src/view/selection.js

@@ -41,11 +41,11 @@ export default class Selection {
 	 *
 	 *		// Creates selection at the given range.
 	 *		const range = new Range( start, end );
-	 *		const selection = new Selection( range, { backward } );
+	 *		const selection = new Selection( range, { backward, fake, label } );
 	 *
 	 *		// Creates selection at the given ranges
 	 * 		const ranges = [ new Range( start1, end2 ), new Range( star2, end2 ) ];
-	 *		const selection = new Selection( ranges, { backward } );
+	 *		const selection = new Selection( ranges, { backward, fake, label } );
 	 *
 	 *		// Creates selection from the other selection.
 	 *		const otherSelection = new Selection();
@@ -53,33 +53,29 @@ export default class Selection {
 	 *
 	 * 		// Creates selection at the given position.
 	 *		const position = new Position( root, path );
-	 *		const selection = new Selection( position );
+	 *		const selection = new Selection( position, { fake, label } );
 	 *
-	 * 		// Sets collapsed range at the position of given item and offset.
+	 * 		// Sets collapsed selection at the position of given item and offset.
 	 *		const paragraph = writer.createElement( 'paragraph' );
-	 *		selection.setTo( paragraph, offset );
+	 *		selection.setTo( paragraph, offset, { fake, label } );
 	 *
-	 *		// Sets range inside the item.
+	 *		// Sets selection inside the item.
 	 *		const paragraph = writer.createElement( 'paragraph' );
-	 *		selection.setTo( paragraph, 'in', { backward } );
+	 *		selection.setTo( paragraph, 'in', { backward, fake, label } );
 	 *
-	 *		// Sets range on the item.
+	 *		// Sets selection on the item.
 	 *		const paragraph = writer.createElement( 'paragraph' );
-	 *		selection.setTo( paragraph, 'on', { backward } );
+	 *		selection.setTo( paragraph, 'on', { backward, fake, label } );
 	 *
 	 * @param {module:engine/view/selection~Selection|module:engine/view/position~Position|
 	 * Iterable.<module:engine/view/range~Range>|module:engine/view/range~Range|module:engine/view/item~Item|null} [selectable=null]
-	 * @param {Object|Number|'before'|'end'|'after'|'on'|'in'} [optionsOrPlaceOrOffset] Offset or place when selectable is an `Item`.
-	 * Options otherwise.
-	 * @param {Boolean} [optionsOrPlaceOrOffset.backward] Sets this selection instance to be backward.
-	 * @param {Boolean} [optionsOrPlaceOrOffset.fake] Sets this selection instance to be marked as `fake`.
-	 * @param {Boolean} [optionsOrPlaceOrOffset.label] Label for the fake selection.
-	 * @param {Object} [options] Options when selectable is an `Item`.
+	 * @param {Number|'before'|'end'|'after'|'on'|'in'} [placeOrOffset] Offset or place when selectable is an `Item`.
+	 * @param {Object} [options]
 	 * @param {Boolean} [options.backward] Sets this selection instance to be backward.
 	 * @param {Boolean} [options.fake] Sets this selection instance to be marked as `fake`.
 	 * @param {String} [options.label] Label for the fake selection.
 	 */
-	constructor( selectable = null, optionsOrPlaceOrOffset, options ) {
+	constructor( selectable = null, placeOrOffset, options ) {
 		/**
 		 * Stores all ranges that are selected.
 		 *
@@ -112,7 +108,7 @@ export default class Selection {
 		 */
 		this._fakeSelectionLabel = '';
 
-		this._setTo( selectable, optionsOrPlaceOrOffset, options );
+		this._setTo( selectable, placeOrOffset, options );
 	}
 
 	/**
@@ -408,83 +404,80 @@ export default class Selection {
 	 * {@link module:engine/view/item~Item item}, {@link module:engine/view/range~Range range},
 	 * an iterable of {@link module:engine/view/range~Range ranges} or null.
 	 *
-	 *		// Sets ranges from the given range.
+	 *		// Sets selection to the given range.
 	 *		const range = new Range( start, end );
-	 *		selection.setTo( range, isBackwardSelection );
+	 *		selection.setTo( range, { backward, fake, label } );
 	 *
-	 *		// Sets ranges from the iterable of ranges.
+	 *		// Sets selection to the ranges.
 	 * 		const ranges = [ new Range( start1, end2 ), new Range( star2, end2 ) ];
-	 *		selection.setTo( range, isBackwardSelection );
+	 *		selection.setTo( range, { backward, fake, label } );
 	 *
-	 *		// Sets ranges from the other selection.
+	 *		// Sets selection to the other selection.
 	 *		const otherSelection = new Selection();
 	 *		selection.setTo( otherSelection );
 	 *
-	 * 		// Sets collapsed range at the given position.
+	 * 		// Sets collapsed selection at the given position.
 	 *		const position = new Position( root, path );
-	 *		selection.setTo( position );
+	 *		selection.setTo( position, { fake, label } );
 	 *
-	 * 		// Sets collapsed range at the position of given item and offset.
+	 * 		// Sets collapsed selection at the position of given item and offset.
 	 *		const paragraph = writer.createElement( 'paragraph' );
-	 *		selection.setTo( paragraph, offset );
+	 *		selection.setTo( paragraph, offset, { fake, label } );
 	 *
-	 *		// Sets range inside the item.
+	 *		// Sets selection inside the item.
 	 *		const paragraph = writer.createElement( 'paragraph' );
-	 *		selection.setTo( paragraph, 'in' );
+	 *		selection.setTo( paragraph, 'in', { backward, fake, label } );
 	 *
-	 *		// Sets range on the item.
+	 *		// Sets selection on the item.
 	 *		const paragraph = writer.createElement( 'paragraph' );
-	 *		selection.setTo( paragraph, 'on' );
+	 *		selection.setTo( paragraph, 'on', { backward, fake, label } );
 	 *
-	 * 		// Removes all ranges.
+	 * 		// Clears selection. Removes all ranges and options
 	 *		selection.setTo( null );
 	 *
 	 * @protected
 	 * @fires change
 	 * @param {module:engine/view/selection~Selection|module:engine/view/position~Position|
 	 * Iterable.<module:engine/view/range~Range>|module:engine/view/range~Range|module:engine/view/item~Item|null} selectable
-	 * @param {Object|Number|'before'|'end'|'after'|'on'|'in'} [optionsOrPlaceOrOffset] Offset or place when selectable is an `Item`.
-	 * Options otherwise.
-	 * @param {Boolean} [optionsOrPlaceOrOffset.backward] Sets this selection instance to be backward.
-	 * @param {Boolean} [optionsOrPlaceOrOffset.fake] Sets this selection instance to be marked as `fake`.
-	 * @param {Boolean} [optionsOrPlaceOrOffset.label] Label for the fake selection.
-	 * @param {Object} [options] Options when selectable is an `Item`.
+	 * @param {Number|'before'|'end'|'after'|'on'|'in'} [placeOrOffset] Offset or place.
+	 * @param {Object} [options]
 	 * @param {Boolean} [options.backward] Sets this selection instance to be backward.
 	 * @param {Boolean} [options.fake] Sets this selection instance to be marked as `fake`.
 	 * @param {String} [options.label] Label for the fake selection.
 	 */
-	_setTo( selectable, optionsOrPlaceOrOffset, options ) {
+	_setTo( selectable, placeOrOffset, options ) {
 		if ( selectable === null ) {
 			this._setRanges( [] );
-			this._setFakeOptions( optionsOrPlaceOrOffset );
+			this._setFakeOptions( placeOrOffset );
 		} else if ( selectable instanceof Selection ) {
 			this._setRanges( selectable.getRanges(), selectable.isBackward );
 			this._setFakeOptions( { fake: selectable.isFake, label: selectable.fakeSelectionLabel } );
 		} else if ( selectable instanceof Range ) {
-			this._setRanges( [ selectable ], optionsOrPlaceOrOffset && optionsOrPlaceOrOffset.backward );
-			this._setFakeOptions( optionsOrPlaceOrOffset );
+			this._setRanges( [ selectable ], placeOrOffset && placeOrOffset.backward );
+			this._setFakeOptions( placeOrOffset );
 		} else if ( selectable instanceof Position ) {
 			this._setRanges( [ new Range( selectable ) ] );
-			this._setFakeOptions( optionsOrPlaceOrOffset );
+			this._setFakeOptions( placeOrOffset );
 		} else if ( selectable instanceof Node ) {
 			const backward = !!options && !!options.backward;
 			let range;
 
-			if ( optionsOrPlaceOrOffset === undefined ) {
+			if ( placeOrOffset === undefined ) {
 				/**
-				 * Required second parameter when setting selection to node.
+				 * selection.setTo requires the second parameter when the first parameter is a node.
 				 *
 				 * @error view-selection-setTo-required-second-parameter
 				 */
 				throw new CKEditorError(
-					'view-selection-setTo-required-second-parameter: Required second parameter when setting selection to node.'
+					'view-selection-setTo-required-second-parameter: ' +
+					'selection.setTo requires the second parameter when the first parameter is a node.'
 				);
-			} else if ( optionsOrPlaceOrOffset == 'in' ) {
+			} else if ( placeOrOffset == 'in' ) {
 				range = Range.createIn( selectable );
-			} else if ( optionsOrPlaceOrOffset == 'on' ) {
+			} else if ( placeOrOffset == 'on' ) {
 				range = Range.createOn( selectable );
 			} else {
-				range = Range.createCollapsedAt( selectable, optionsOrPlaceOrOffset );
+				range = Range.createCollapsedAt( selectable, placeOrOffset );
 			}
 
 			this._setRanges( [ range ], backward );
@@ -492,8 +485,8 @@ export default class Selection {
 		} else if ( isIterable( selectable ) ) {
 			// We assume that the selectable is an iterable of ranges.
 			// Array.from() is used to prevent setting ranges to the old iterable
-			this._setRanges( selectable, optionsOrPlaceOrOffset && optionsOrPlaceOrOffset.backward );
-			this._setFakeOptions( optionsOrPlaceOrOffset );
+			this._setRanges( selectable, placeOrOffset && placeOrOffset.backward );
+			this._setFakeOptions( placeOrOffset );
 		} else {
 			/**
 			 * Cannot set selection to given place.