Explorar o código

Fixed docs in view Selection class.

Szymon Kupś %!s(int64=7) %!d(string=hai) anos
pai
achega
28f9b7c82a
Modificáronse 1 ficheiros con 41 adicións e 31 borrados
  1. 41 31
      packages/ckeditor5-engine/src/view/selection.js

+ 41 - 31
packages/ckeditor5-engine/src/view/selection.js

@@ -22,17 +22,16 @@ import DocumentSelection from './documentselection';
  * Class representing selection in tree view.
  * Class representing selection in tree view.
  *
  *
  * Selection can consist of {@link module:engine/view/range~Range ranges} that can be set using
  * Selection can consist of {@link module:engine/view/range~Range ranges} that can be set using
- * {@link module:engine/view/documentselection~DocumentSelection#_setTo} method.
+ * {@link module:engine/view/selection~Selection#setTo setTo} method.
  * That method create copies of provided ranges and store those copies internally. Further modifications to passed
  * That method create copies of provided ranges and store those copies internally. Further modifications to passed
  * ranges will not change selection's state.
  * ranges will not change selection's state.
- * Selection's ranges can be obtained via {@link module:engine/view/documentselection~DocumentSelection#getRanges getRanges},
- * {@link module:engine/view/documentselection~DocumentSelection#getFirstRange getFirstRange}
- * and {@link module:engine/view/documentselection~DocumentSelection#getLastRange getLastRange}
- * methods, which return copies of ranges stored inside selection. Modifications made on these copies will not change
- * selection's state. Similar situation occurs when getting {@link module:engine/view/documentselection~DocumentSelection#anchor anchor},
- * {@link module:engine/view/documentselection~DocumentSelection#focus focus},
- * {@link module:engine/view/documentselection~DocumentSelection#getFirstPosition first} and
- * {@link module:engine/view/documentselection~DocumentSelection#getLastPosition last} positions - all will return
+ * Selection's ranges can be obtained via {@link module:engine/view/selection~Selection#getRanges getRanges},
+ * {@link module:engine/view/selection~Selection#getFirstRange getFirstRange} and
+ * {@link module:engine/view/selection~Selection#getLastRange getLastRange} methods, which return copies of ranges
+ * stored inside selection. Modifications made on these copies will not change selection's state. Similar situation
+ * occurs when getting {@link module:engine/view/selection~Selection#anchor anchor},
+ * {@link module:engine/view/selection~Selection#focus focus}, {@link module:engine/view/selection~Selection#getFirstPosition first}
+ * and {@link module:engine/view/selection~Selection#getLastPosition last} positions - all will return
  * copies of requested positions.
  * copies of requested positions.
  */
  */
 export default class Selection {
 export default class Selection {
@@ -54,6 +53,10 @@ export default class Selection {
 	 *		const otherSelection = new Selection();
 	 *		const otherSelection = new Selection();
 	 *		const selection = new Selection( otherSelection );
 	 *		const selection = new Selection( otherSelection );
 	 *
 	 *
+	 *		// Creates selection from the document selection.
+	 *		const documentSelection = new DocumentSelection();
+	 *		const selection = new Selection( documentSelection );
+	 *
 	 * 		// Creates selection at the given position.
 	 * 		// Creates selection at the given position.
 	 *		const position = new Position( root, path );
 	 *		const position = new Position( root, path );
 	 *		const selection = new Selection( position );
 	 *		const selection = new Selection( position );
@@ -85,8 +88,9 @@ export default class Selection {
 	 *		// Creates fake selection with label.
 	 *		// Creates fake selection with label.
 	 *		const selection = new Selection( range, { fake: true, label: 'foo' } );
 	 *		const selection = new Selection( range, { fake: true, label: 'foo' } );
 	 *
 	 *
-	 * @param {module:engine/view/documentselection~DocumentSelection|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 {module:engine/view/selection~Selection|module:engine/view/documentselection~DocumentSelection|
+	 * 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 {Number|'before'|'end'|'after'|'on'|'in'} [placeOrOffset] Offset or place 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 {Object} [options]
 	 * @param {Boolean} [options.backward] Sets this selection instance to be backward.
 	 * @param {Boolean} [options.backward] Sets this selection instance to be backward.
@@ -132,7 +136,7 @@ export default class Selection {
 	/**
 	/**
 	 * Returns true if selection instance is marked as `fake`.
 	 * Returns true if selection instance is marked as `fake`.
 	 *
 	 *
-	 * @see #_setTo
+	 * @see #setTo
 	 * @returns {Boolean}
 	 * @returns {Boolean}
 	 */
 	 */
 	get isFake() {
 	get isFake() {
@@ -142,7 +146,7 @@ export default class Selection {
 	/**
 	/**
 	 * Returns fake selection label.
 	 * Returns fake selection label.
 	 *
 	 *
-	 * @see #_setTo
+	 * @see #setTo
 	 * @returns {String}
 	 * @returns {String}
 	 */
 	 */
 	get fakeSelectionLabel() {
 	get fakeSelectionLabel() {
@@ -306,7 +310,8 @@ export default class Selection {
 	 * Checks whether, this selection is equal to given selection. Selections are equal if they have same directions,
 	 * Checks whether, this selection is equal to given selection. Selections are equal if they have same directions,
 	 * same number of ranges and all ranges from one selection equal to a range from other selection.
 	 * same number of ranges and all ranges from one selection equal to a range from other selection.
 	 *
 	 *
-	 * @param {module:engine/view/documentselection~DocumentSelection} otherSelection Selection to compare with.
+	 * @param {module:engine/view/selection~Selection|module:engine/view/documentselection~DocumentSelection} otherSelection
+	 * Selection to compare with.
 	 * @returns {Boolean} `true` if selections are equal, `false` otherwise.
 	 * @returns {Boolean} `true` if selections are equal, `false` otherwise.
 	 */
 	 */
 	isEqual( otherSelection ) {
 	isEqual( otherSelection ) {
@@ -351,7 +356,8 @@ export default class Selection {
 	 * number of ranges, and all {@link module:engine/view/range~Range#getTrimmed trimmed} ranges from one selection are
 	 * number of ranges, and all {@link module:engine/view/range~Range#getTrimmed trimmed} ranges from one selection are
 	 * equal to any trimmed range from other selection.
 	 * equal to any trimmed range from other selection.
 	 *
 	 *
-	 * @param {module:engine/view/documentselection~DocumentSelection} otherSelection Selection to compare with.
+	 * @param {module:engine/view/selection~Selection|module:engine/view/documentselection~DocumentSelection} otherSelection
+	 * Selection to compare with.
 	 * @returns {Boolean} `true` if selections are similar, `false` otherwise.
 	 * @returns {Boolean} `true` if selections are similar, `false` otherwise.
 	 */
 	 */
 	isSimilar( otherSelection ) {
 	isSimilar( otherSelection ) {
@@ -418,45 +424,50 @@ export default class Selection {
 
 
 	/**
 	/**
 	 * Sets this selection's ranges and direction to the specified location based on the given
 	 * Sets this selection's ranges and direction to the specified location based on the given
-	 * {@link module:engine/view/documentselection~DocumentSelection selection}, {@link module:engine/view/position~Position position},
+	 * {@link module:engine/view/documentselection~DocumentSelection document selection},
+	 * {@link module:engine/view/selection~Selection selection}, {@link module:engine/view/position~Position position},
 	 * {@link module:engine/view/item~Item item}, {@link module:engine/view/range~Range range},
 	 * {@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.
 	 * an iterable of {@link module:engine/view/range~Range ranges} or null.
 	 *
 	 *
 	 *		// Sets selection to the given range.
 	 *		// Sets selection to the given range.
 	 *		const range = new Range( start, end );
 	 *		const range = new Range( start, end );
-	 *		selection._setTo( range );
+	 *		selection.setTo( range );
 	 *
 	 *
 	 *		// Sets selection to given ranges.
 	 *		// Sets selection to given ranges.
 	 * 		const ranges = [ new Range( start1, end2 ), new Range( star2, end2 ) ];
 	 * 		const ranges = [ new Range( start1, end2 ), new Range( star2, end2 ) ];
-	 *		selection._setTo( range );
+	 *		selection.setTo( range );
 	 *
 	 *
 	 *		// Sets selection to the other selection.
 	 *		// Sets selection to the other selection.
 	 *		const otherSelection = new Selection();
 	 *		const otherSelection = new Selection();
-	 *		selection._setTo( otherSelection );
+	 *		selection.setTo( otherSelection );
+	 *
+	 *	 	// Sets selection to contents of DocumentSelection.
+	 *		const documentSelection = new DocumentSelection();
+	 *		selection.setTo( documentSelection );
 	 *
 	 *
 	 * 		// Sets collapsed selection at the given position.
 	 * 		// Sets collapsed selection at the given position.
 	 *		const position = new Position( root, path );
 	 *		const position = new Position( root, path );
-	 *		selection._setTo( position );
+	 *		selection.setTo( position );
 	 *
 	 *
 	 * 		// Sets collapsed selection at the position of given item and offset.
 	 * 		// Sets collapsed selection at the position of given item and offset.
-	 *		selection._setTo( paragraph, offset );
+	 *		selection.setTo( paragraph, offset );
 	 *
 	 *
 	 * Creates a range inside an {@link module:engine/view/element~Element element} which starts before the first child of
 	 * Creates a range inside an {@link module:engine/view/element~Element element} which starts before the first child of
 	 * that element and ends after the last child of that element.
 	 * that element and ends after the last child of that element.
 	 *
 	 *
-	 *		selection._setTo( paragraph, 'in' );
+	 *		selection.setTo( paragraph, 'in' );
 	 *
 	 *
 	 * Creates a range on an {@link module:engine/view/item~Item item} which starts before the item and ends just after the item.
 	 * Creates a range on an {@link module:engine/view/item~Item item} which starts before the item and ends just after the item.
 	 *
 	 *
-	 *		selection._setTo( paragraph, 'on' );
+	 *		selection.setTo( paragraph, 'on' );
 	 *
 	 *
 	 * 		// Clears selection. Removes all ranges.
 	 * 		// Clears selection. Removes all ranges.
-	 *		selection._setTo( null );
+	 *		selection.setTo( null );
 	 *
 	 *
-	 * `Selection#_setTo()` method allow passing additional options (`backward`, `fake` and `label`) as the last argument.
+	 * `Selection#setTo()` method allow passing additional options (`backward`, `fake` and `label`) as the last argument.
 	 *
 	 *
 	 *		// Sets selection as backward.
 	 *		// Sets selection as backward.
-	 *		selection._setTo( range, { backward: true } );
+	 *		selection.setTo( range, { backward: true } );
 	 *
 	 *
 	 * Fake selection does not render as browser native selection over selected elements and is hidden to the user.
 	 * Fake selection does not render as browser native selection over selected elements and is hidden to the user.
 	 * This way, no native selection UI artifacts are displayed to the user and selection over elements can be
 	 * This way, no native selection UI artifacts are displayed to the user and selection over elements can be
@@ -466,12 +477,12 @@ export default class Selection {
 	 * (and be  properly handled by screen readers).
 	 * (and be  properly handled by screen readers).
 	 *
 	 *
 	 *		// Creates fake selection with label.
 	 *		// Creates fake selection with label.
-	 *		selection._setTo( range, { fake: true, label: 'foo' } );
+	 *		selection.setTo( range, { fake: true, label: 'foo' } );
 	 *
 	 *
-	 * @protected
 	 * @fires change
 	 * @fires change
-	 * @param {module:engine/view/documentselection~DocumentSelection|module:engine/view/position~Position|
-	 * Iterable.<module:engine/view/range~Range>|module:engine/view/range~Range|module:engine/view/item~Item|null} selectable
+	 * @param {module:engine/view/selection~Selection|module:engine/view/documentselection~DocumentSelection|
+	 * module:engine/view/position~Position|Iterable.<module:engine/view/range~Range>|module:engine/view/range~Range|
+	 * module:engine/view/item~Item|null} selectable
 	 * @param {Number|'before'|'end'|'after'|'on'|'in'} [placeOrOffset] Sets place or offset of the selection.
 	 * @param {Number|'before'|'end'|'after'|'on'|'in'} [placeOrOffset] Sets place or offset of the selection.
 	 * @param {Object} [options]
 	 * @param {Object} [options]
 	 * @param {Boolean} [options.backward] Sets this selection instance to be backward.
 	 * @param {Boolean} [options.backward] Sets this selection instance to be backward.
@@ -537,7 +548,6 @@ export default class Selection {
 	 *
 	 *
 	 * The location can be specified in the same form as {@link module:engine/view/position~Position.createAt} parameters.
 	 * The location can be specified in the same form as {@link module:engine/view/position~Position.createAt} parameters.
 	 *
 	 *
-	 * @protected
 	 * @fires change
 	 * @fires change
 	 * @param {module:engine/view/item~Item|module:engine/view/position~Position} itemOrPosition
 	 * @param {module:engine/view/item~Item|module:engine/view/position~Position} itemOrPosition
 	 * @param {Number|'end'|'before'|'after'} [offset=0] Offset or one of the flags. Used only when
 	 * @param {Number|'end'|'before'|'after'} [offset=0] Offset or one of the flags. Used only when