Parcourir la source

Node class docs.

Piotr Jasiun il y a 10 ans
Parent
commit
388a242963

+ 72 - 0
packages/ckeditor5-engine/src/treeview/node.js

@@ -9,13 +9,45 @@ import CKEditorError from '../ckeditorerror.js';
 import EmitterMixin from '../emittermixin.js';
 import objectUtils from '../lib/lodash/object.js';
 
+/**
+ * Abstract tree view node class.
+ *
+ * @abstract
+ * @class treeView.Node
+ */
 export default class Node {
+	/**
+	 * Creates a tree view node.
+	 *
+	 * This is an abstract class, so this constructor should not be used directly.
+	 *
+	 * @constructor
+	 */
 	constructor() {
+		/**
+		 * Parent element. Null by default. Set by {@link treeView.Element#insertChildren}.
+		 *
+		 * @readonly
+		 * @property {treeView.Element|null} parent
+		 */
 		this.parent = null;
 
+		/**
+		 * {@link treeView.TreeView} reference.
+		 *
+		 * @protected
+		 * @type {treeView.TreeView}
+		 */
 		this._treeView = null;
 	}
 
+	/**
+	 * Index of the node in the parent element or null if the node has no parent.
+	 *
+	 * Throws error if the parent element does not contain this node.
+	 *
+	 * @returns {Number|Null} Index of the node in the parent element or null if the node has not parent.
+	 */
 	getIndex() {
 		let pos;
 
@@ -36,18 +68,35 @@ export default class Node {
 		return pos;
 	}
 
+	/**
+	 * Returns nodes next sibling or `null` if it is the last child.
+	 *
+	 * @returns {treeView.Node|null} Nodes next sibling or `null` if it is the last child.
+	 */
 	getNextSibling() {
 		const index = this.getIndex();
 
 		return ( index !== null && this.parent.getChild( index + 1 ) ) || null;
 	}
 
+	/**
+	 * Returns nodes previous sibling or `null` if it is the first child.
+	 *
+	 * @returns {treeView.Node|null} Nodes previous sibling or `null` if it is the first child.
+	 */
 	getPreviousSibling() {
 		const index = this.getIndex();
 
 		return ( index !== null && this.parent.getChild( index - 1 ) ) || null;
 	}
 
+	/**
+	 * Get {@link treeView.TreeView} reference. If the node has {@link treeView.TreeView}, assign by
+	 * {@link treeView.Node#setTreeView} it will be returned. Otherwise {@link treeView.TreeView} of the parents node
+	 * will be returned. If node has no parent, `null` will be returned.
+	 *
+	 * @returns {treeView.TreeView|Null} Tree view of the node, tree view of the parent or null.
+	 */
 	getTreeView() {
 		if ( this._treeView ) {
 			return this._treeView;
@@ -58,10 +107,22 @@ export default class Node {
 		}
 	}
 
+	/**
+	 * Set the {@link treeView.TreeView} of the node. Note that not all of nodes need to have {@link treeView.TreeView}
+	 * assigned, see {@link treeView.Node#getTreeView}.
+	 *
+	 * @param {treeView.TreeView} treeView Tree view.
+	 */
 	setTreeView( treeView ) {
 		this._treeView = treeView;
 	}
 
+	/**
+	 * Fire {@link treeView.Node#change change event}.
+	 *
+	 * @param {treeView.ChangeType} type Type of the change.
+	 * @param {treeView.Node} node Changed node.
+	 */
 	_fireChange( type, node ) {
 		this.fire( 'change', type, node );
 
@@ -69,6 +130,17 @@ export default class Node {
 			this.parent._fireChange( type, node );
 		}
 	}
+
+	/**
+	 * Fired when node changes. In case of {@link treeView.Text text nodes} in will be change of the text. In case of
+	 * {@link treeView.Element elements} in will be change of child nodes or attributes.
+	 *
+	 * @event change
+	 *
+	 * @param {treeView.ChangeType} Type of the change.
+	 * @param {treeView.Node} Changed node.
+	 */
 }
 
 objectUtils.extend( Node.prototype, EmitterMixin );
+

+ 39 - 39
packages/ckeditor5-engine/src/treeview/observer/mutationobserver.js

@@ -171,45 +171,45 @@ export default class MutationObserver extends Observer {
 
 		this.treeView.render();
 	}
+}
 
-	/**
-	 * Fired when mutation occurred. If tree view is not changed on this event, DOM will be reverter to the state before
-	 * mutation, so all changes which should be applied, should be handled on this event.
-	 *
-	 * @event mutations
-	 * @memberOf treeView.TreeView
-	 *
-	 * @param {Array.<treeView.TreeView.MutatatedText|treeView.TreeView.MutatatedChildren>} viewMutations
-	 * Array of mutations.
-	 * For mutated texts it will be {@link treeView.TreeView.MutatatedText} and for mutated elements it will be
-	 * {@link treeView.TreeView.MutatatedElement}. You can recognize the type based on the `type` property.
-	 */
+/**
+ * Fired when mutation occurred. If tree view is not changed on this event, DOM will be reverter to the state before
+ * mutation, so all changes which should be applied, should be handled on this event.
+ *
+ * @event mutations
+ * @memberOf treeView.TreeView
+ *
+ * @param {Array.<treeView.MutatatedText|treeView.MutatatedChildren>} viewMutations
+ * Array of mutations.
+ * For mutated texts it will be {@link treeView.MutatatedText} and for mutated elements it will be
+ * {@link treeView.MutatatedElement}. You can recognize the type based on the `type` property.
+ */
 
-	/**
-	 * Mutation item for text.
-	 *
-	 * @see treeView.TreeView#mutations
-	 * @see treeView.TreeView.MutatatedChildren
-	 *
-	 * @typedef {Object} treeView.TreeView.MutatatedText
-	 *
-	 * @property {String} type For text mutations it is always 'text'.
-	 * @property {treeView.Text} node Mutated text node.
-	 * @property {String} oldText Old text.
-	 * @property {String} newText New text.
-	 */
+/**
+ * Mutation item for text.
+ *
+ * @see treeView.TreeView#mutations
+ * @see treeView.MutatatedChildren
+ *
+ * @typedef {Object} treeView.MutatatedText
+ *
+ * @property {String} type For text mutations it is always 'text'.
+ * @property {treeView.Text} node Mutated text node.
+ * @property {String} oldText Old text.
+ * @property {String} newText New text.
+ */
 
-	/**
-	 * Mutation item for child nodes.
-	 *
-	 * @see treeView.TreeView#mutations
-	 * @see treeView.TreeView.MutatatedText
-	 *
-	 * @typedef {Object} treeView.TreeView.MutatatedChildren
-	 *
-	 * @property {String} type For child nodes mutations it is always 'children'.
-	 * @property {treeView.Element} node Parent of the mutated children.
-	 * @property {Array.<treeView.Node>} oldChildren Old child nodes.
-	 * @property {Array.<treeView.Node>} newChildren New child nodes.
-	 */
-}
+/**
+ * Mutation item for child nodes.
+ *
+ * @see treeView.TreeView#mutations
+ * @see treeView.MutatatedText
+ *
+ * @typedef {Object} treeView.MutatatedChildren
+ *
+ * @property {String} type For child nodes mutations it is always 'children'.
+ * @property {treeView.Element} node Parent of the mutated children.
+ * @property {Array.<treeView.Node>} oldChildren Old child nodes.
+ * @property {Array.<treeView.Node>} newChildren New child nodes.
+ */

+ 11 - 0
packages/ckeditor5-engine/src/treeview/treeview.js

@@ -56,3 +56,14 @@ export default class TreeView {
 }
 
 objectUtils.extend( TreeView.prototype, EmitterMixin );
+
+/**
+ * Enum representing type of the change.
+ * Possible values:
+ *
+ *	* `CHILDREN` - for child list changes,
+ *	* `ATTRIBUTES` - for element attributes changes,
+ *	* `TEXT` - for text nodes changes.
+ *
+ * @typedef {String} treeView.ChangeType
+ */