Explorar o código

Changed EmitterMixin._counter, AttributeList constructor. Removed Document._selection (Document.selection still available). Docs typos and examples.

Szymon Cofalik %!s(int64=10) %!d(string=hai) anos
pai
achega
46a37fbdf7

+ 6 - 9
packages/ckeditor5-engine/src/emittermixin.js

@@ -13,14 +13,11 @@
  */
 
 CKEDITOR.define( [ 'eventinfo', 'utils' ], ( EventInfo, utils ) => {
-	const EmitterMixin = {
-		/**
-		 * Saves how many callbacks has been already added. Does not decrement when callback is removed.
-		 * Used internally as a unique id for a callback.
-		 * @private
-		 */
-		_counter: 0,
+	// Saves how many callbacks has been already added. Does not decrement when callback is removed.
+	// Used internally as a unique id for a callback.
+	let eventsCounter = 0;
 
+	const EmitterMixin = {
 		/**
 		 * Registers a callback function to be executed when an event is fired.
 		 *
@@ -44,7 +41,7 @@ CKEDITOR.define( [ 'eventinfo', 'utils' ], ( EventInfo, utils ) => {
 				ctx: ctx || this,
 				priority: priority,
 				// Save counter value as unique id.
-				counter: ++this._counter
+				counter: ++eventsCounter
 			};
 
 			// Add the callback to the list in the right priority position.
@@ -236,7 +233,7 @@ CKEDITOR.define( [ 'eventinfo', 'utils' ], ( EventInfo, utils ) => {
 			args.unshift( eventInfo );
 
 			// Save how many callbacks were added at the moment when the event has been fired.
-			const counter = this._counter;
+			const counter = eventsCounter;
 
 			for ( let i = 0; i < callbacks.length; i++ ) {
 				// Filter out callbacks that have been added after event has been fired.

+ 3 - 2
packages/ckeditor5-engine/src/treemodel/attributelist.js

@@ -24,9 +24,10 @@ CKEDITOR.define( [ 'treemodel/attribute' ], ( Attribute ) => {
 			 * Internal set containing the attributes stored by this list.
 			 *
 			 * @private
-			 * @property {Set.<treeModel.Attribute>}
+			 * @property {Set.<treeModel.Attribute>} _attrs
 			 */
-			this._attrs = new Set( attrs );
+
+			this.setAttrsTo( attrs );
 		}
 
 		/**

+ 1 - 11
packages/ckeditor5-engine/src/treemodel/document.js

@@ -71,7 +71,7 @@ CKEDITOR.define( [
 			 * @readonly
 			 * @property {treeModel.Selection}
 			 */
-			this._selection = new Selection();
+			this.selection = new Selection();
 		}
 
 		/**
@@ -84,16 +84,6 @@ CKEDITOR.define( [
 			return this.getRoot( graveyardSymbol );
 		}
 
-		/**
-		 * Returns current selection done on this document.
-		 *
-		 * @readonly
-		 * @property {treeModel.Selection}
-		 */
-		get selection() {
-			return this._selection;
-		}
-
 		/**
 		 * This is the entry point for all document changes. All changes on the document are done using
 		 * {@link treeModel.operation.Operation operations}. To create operations in the simple way use the

+ 15 - 2
packages/ckeditor5-engine/src/treemodel/liveposition.js

@@ -40,11 +40,24 @@ CKEDITOR.define( [
 			 * Flag representing LivePosition stickiness. LivePosition might be sticking to previous node or next node.
 			 * Whenever some nodes are inserted at the same position as LivePosition, `stickiness` is checked to decide if
 			 * LivePosition should be moved. Similar applies when a range of nodes is moved and one of it's boundary
-			 * position is same as LivePosition. Accepted values are {@link #STICKS_TO_PREVIOUS} and {@link #STICKS_TO_NEXT}.
+			 * position is same as LivePosition.
+			 *
+			 * Examples:
+			 * Insert:
+			 * Position is at | and we insert at the same position, marked as ^:
+			 * | sticks to previous node: `<p>f|^oo</p>` => `<p>f|baroo</p>`
+			 * | sticks to next node: `<p>f^|oo</p>` => `<p>fbar|oo</p>`
+			 *
+			 * Move:
+			 * Position is at | and range [ ] is moved to position ^:
+			 * | sticks to previous node: `<p>f|[oo]</p><p>b^ar</p>` => `<p>f|</p><p>booar</p>`
+			 * | sticks to next node: `<p>f|[oo]</p><p>b^ar</p>` => `<p>f</p><p>b|ooar</p>`
+			 *
+			 * Accepted values are {@link #STICKS_TO_PREVIOUS} and {@link #STICKS_TO_NEXT}.
 			 *
 			 * @type {Number}
 			 */
-			this.stickiness = stickiness ? stickiness : STICKS_TO_NEXT;
+			this.stickiness = stickiness || STICKS_TO_NEXT;
 
 			bindWithDocument.call( this );
 		}

+ 4 - 2
packages/ckeditor5-engine/src/treemodel/liverange.js

@@ -13,6 +13,7 @@ CKEDITOR.define( [
 ], ( Range, LivePosition, EmitterMixin, utils ) => {
 	/**
 	 * LiveRange is a Range in the Tree Model that updates itself as the tree changes. It may be used as a bookmark.
+	 * **Note:** Constructor creates it's own {@link treeModel.LivePosition} instances basing on passed values.
 	 * **Note:** Be very careful when dealing with LiveRange. Each LiveRange instance bind events that might
 	 * have to be unbound. Use {@link #detach} whenever you don't need LiveRange anymore.
 	 *
@@ -102,8 +103,9 @@ CKEDITOR.define( [
 	}
 
 	/**
-	 * LiveRange is partially updated by "automatic" updates of LivePositions that are boundaries of LiveRange.
-	 * However there are cases when the boundaries have to be fixed because they end up in wrong places.
+	 * LiveRange boundaries are instances of {@link treeModel.LivePosition}, so it is updated thanks to them. This method
+	 * additionally fixes the results of updating live positions taking into account that those live positions
+	 * are boundaries of a range. An example case for fixing live positions is end boundary is moved before start boundary.
 	 *
 	 * @private
 	 * @method fixBoundaries

+ 2 - 1
packages/ckeditor5-engine/src/treemodel/range.js

@@ -13,7 +13,8 @@ CKEDITOR.define( [ 'treemodel/position', 'treemodel/positioniterator', 'utils' ]
 	 */
 	class Range {
 		/**
-		 * Creates a range.
+		 * Creates a range spanning from `start` position to `end` position.
+		 * **Note:** Constructor creates it's own {@link treeModel.Position} instances basing on passed values.
 		 *
 		 * @param {treeModel.Position} start Start position.
 		 * @param {treeModel.Position} end End position.

+ 7 - 20
packages/ckeditor5-engine/src/treemodel/selection.js

@@ -120,10 +120,12 @@ CKEDITOR.define( [
 		}
 
 		/**
-		 * Unbinds all events previously bound by this selection, including events bound by created {@link treeModel.LiveRange}s.
+		 * Unbinds all events previously bound by this selection and objects created by this selection.
 		 */
 		detach() {
-			detachRanges.call( this );
+			for ( let i = 0; i < this._ranges.length; i++ ) {
+				this._ranges[ i ].detach();
+			}
 		}
 
 		/**
@@ -168,7 +170,7 @@ CKEDITOR.define( [
 		 * Removes all ranges that were added to the selection. Fires update event.
 		 */
 		removeAllRanges() {
-			detachRanges.call( this );
+			this.detach();
 			this._ranges = [];
 
 			this.fire( 'update' );
@@ -198,7 +200,7 @@ CKEDITOR.define( [
 		 * or backward - from end to start (`true`). Defaults to `false`.
 		 */
 		setRanges( newRanges, isLastBackward ) {
-			detachRanges.call( this );
+			this.detach();
 			this._ranges = [];
 
 			for ( let i = 0; i < newRanges.length; i++ ) {
@@ -210,21 +212,6 @@ CKEDITOR.define( [
 		}
 	}
 
-	/**
-	 * Unbinds all events bound by created {@link treeModel.LiveRange}s.
-	 *
-	 * @private
-	 * @method detachRanges
-	 * @memberOf {treeModel.Selection}
-	 */
-	function detachRanges() {
-		/*jshint validthis: true */
-
-		for ( let i = 0; i < this._ranges.length; i++ ) {
-			this._ranges[ i ].detach();
-		}
-	}
-
 	/**
 	 * Converts given range to {@link treeModel.LiveRange} and adds it to internal ranges array. Throws an error
 	 * if given range is intersecting with any range that is already stored in this selection.
@@ -235,7 +222,7 @@ CKEDITOR.define( [
 	 * @param {treeModel.Range} range Range to add.
 	 */
 	function pushRange( range ) {
-		/*jshint validthis: true */
+		/* jshint validthis: true */
 		for ( let i = 0; i < this._ranges.length ; i++ ) {
 			if ( range.isIntersecting( this._ranges[ i ] ) ) {
 				/**