瀏覽代碼

Docs: SelectionObserver docs.

Piotr Jasiun 9 年之前
父節點
當前提交
8a1b97a47a

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

@@ -114,7 +114,7 @@ export default class MutationObserver extends Observer {
 	/**
 	 * Handles mutations. Deduplicates, mark view elements to sync, fire event and call render.
 	 *
-	 * @protected
+	 * @private
 	 * @method engine.treeView.observer.MutationObserver#_onMutations
 	 * @param {Array.<Object>} domMutations Array of native mutations.
 	 */

+ 68 - 3
packages/ckeditor5-engine/src/treeview/observer/selectionobserver.js

@@ -8,33 +8,86 @@
 import Observer from './observer.js';
 import MutationObserver from './mutationobserver.js';
 
+/**
+ * Selection observer class observes selection changes in the document. If selection change on the document this
+ * observer checks if there are any mutations and if DOM selection is different then the
+ * {@link engine.treeView.TreeView#selection view selection}. Selection observer fires
+ * {@link engine.treeView.TreeView#selectionchange} event only if selection change was the only change in the document
+ * and DOM selection is different then view selection.
+ *
+ * @see  engine.treeView.MutationObserver
+ * @memberOf engine.treeView.observer
+ * @extends engine.treeView.observer.Observer
+ */
 export default class SelectionObserver extends Observer {
 	constructor( treeView ) {
 		super( treeView );
 
+		/**
+		 * Instance of the mutation observer. Selection observer calls
+		 * {@link engine.treeView.observer.MutationObserver#flush} to ensure mutations will be handled before the
+		 * {@link engine.treeView.TreeView#selectionchange} event.
+		 *
+		 * @member {engine.treeView.observer.MutationObserver} engine.treeView.observer.SelectionObserver#mutationObserver
+		 */
 		this.mutationObserver = treeView.getObserver( MutationObserver );
 
+		/**
+		 * Reference to the {@link engine.treeView.TreeView} object.
+		 *
+		 * @readonly
+		 * @member {engine.treeView.TreeView} engine.treeView.observer.SelectionObserver#treeView
+		 */
 		this.treeView = treeView;
 
+		/**
+		 * Reference to the TreeView {@link engine.treeView.Selection} object used to compare new selection with it.
+		 *
+		 * @readonly
+		 * @member {engine.treeView.TreeView} engine.treeView.observer.SelectionObserver#selection
+		 */
 		this.selection = treeView.selection;
 
+		/**
+		 * Reference to the {@link engine.treeView.TreeView#domConverter}.
+		 *
+		 * @member {engine.treeView.DomConverter} engine.treeView.observer.SelectionObserver#domConverter
+		 */
 		this.domConverter = treeView.domConverter;
 
-		this.documents = new WeakSet();
+		/**
+		 * Set of documents which have added "selectionchange" listener to avoid adding listener twice to the same
+		 * document.
+		 *
+		 * @private
+		 * @member {WeakSet.<Document>} engine.treeView.observer.SelectionObserver#_documents
+		 */
+		this._documents = new WeakSet();
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	observe( domElement ) {
 		const domDocument = domElement.ownerDocument;
 
-		if ( this.documents.has( domDocument ) ) {
+		// Add listener once per each document.
+		if ( this._documents.has( domDocument ) ) {
 			return;
 		}
 
 		domDocument.addEventListener( 'selectionchange', () => this._handleSelectionChange( domDocument ) );
 
-		this.documents.add( domDocument );
+		this._documents.add( domDocument );
 	}
 
+	/**
+	 * Selection change listener. {@link engine.treeView.observer.MutationObserver#flush Flush} mutations, check if
+	 * selection changes and fires {@link engine.treeView.TreeView#selectionchange} event.
+	 *
+	 * @private
+	 * @param {Document} domDocument DOM document.
+	 */
 	_handleSelectionChange( domDocument ) {
 		if ( !this.isEnabled ) {
 			return;
@@ -62,3 +115,15 @@ export default class SelectionObserver extends Observer {
 		this.treeView.render();
 	}
 }
+
+/**
+ * Fired when selection changes. This event is fired only when the selection change is the only change in the
+ * document, and old selection is different then new selection.
+ *
+ * @event engine.treeView.TreeView#selection
+ * @param {Object} data
+ * @param {engine.treeView.Selection} data.oldSelection Old View selection which is
+ * {@link engine.treeView.TreeView#selection}.
+ * @param {engine.treeView.Selection} data.newSelection New View selection which is converted DOM selection.
+ * @param {Selection} data.domSelection Native DOM selection.
+ */