Skip to content
This repository has been archived by the owner on Jun 26, 2020. It is now read-only.

Commit

Permalink
Docs fixes.
Browse files Browse the repository at this point in the history
  • Loading branch information
@ma2ciek
ma2ciek committed Feb 28, 2018
1 parent bc3125d commit 084e695
Show file tree
Hide file tree
Showing 2 changed files with 77 additions and 77 deletions.
61 changes: 34 additions & 27 deletions src/model/selection.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*
Expand All @@ -94,7 +101,7 @@ export default class Selection {
this._attrs = new Map();

if ( selectable ) {
this.setTo( selectable, optionsOrPlaceOrOffset, options );
this.setTo( selectable, placeOrOffset, options );
}
}

Expand Down Expand Up @@ -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 ) {
Expand All @@ -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.
Expand Down
93 changes: 43 additions & 50 deletions src/view/selection.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,45 +41,41 @@ 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();
* const selection = new Selection( otherSelection );
*
* // 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.
*
Expand Down Expand Up @@ -112,7 +108,7 @@ export default class Selection {
*/
this._fakeSelectionLabel = '';

this._setTo( selectable, optionsOrPlaceOrOffset, options );
this._setTo( selectable, placeOrOffset, options );
}

/**
Expand Down Expand Up @@ -408,92 +404,89 @@ 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 );
this._setFakeOptions( options );
} 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.
Expand Down

0 comments on commit 084e695

Please sign in to comment.