Browse Source

Docs: Reviewed and improved documentation of the FocusCycler class.

Aleksander Nowodzinski 8 years ago
parent
commit
0988ecee75
1 changed files with 28 additions and 21 deletions
  1. 28 21
      packages/ckeditor5-ui/src/focuscycler.js

+ 28 - 21
packages/ckeditor5-ui/src/focuscycler.js

@@ -10,18 +10,24 @@
 import global from '@ckeditor/ckeditor5-utils/src/dom/global';
 
 /**
- * Helps cycling over focusable views in a {@link module:ui/viewcollection~ViewCollection}
- * when the focus is tracked by {@link module:utils/focustracker~FocusTracker} instance.
+ * An utility class that helps cycling over focusable {@link module:ui/view~View views} in a
+ * {@link module:ui/viewcollection~ViewCollection} when the focus is tracked by
+ * {@link module:utils/focustracker~FocusTracker} instance. It helps implementing keyboard
+ * navigation in HTML forms, toolbars, lists and the like.
  *
- * It requires a collection of focusable views and associated focus tracker:
+ * To work properly it requires:
+ * * a collection of focusable (HTML `tabindex` attribute) views that implement the `focus()` method,
+ * * an associated focus tracker to determine which view is focused.
+ *
+ * A simple cycler setup can look like this:
  *
  *		const focusables = new ViewCollection();
  *		const focusTracker = new FocusTracker();
  *
- *		// Add focusables to the focus tracker.
+ *		// Add focusable views to the focus tracker.
  *		focusTracker.add( ... );
  *
- * The cycler can be used manually:
+ * Then, the cycler can be used manually:
  *
  *		const cycler = new FocusCycler( { focusables, focusTracker } );
  *
@@ -31,7 +37,7 @@ import global from '@ckeditor/ckeditor5-utils/src/dom/global';
  *		// Will log next focusable item in #focusables.
  *		console.log( cycler.next );
  *
- * or it can be used as an automated, keystroke–detecting utility:
+ * Alternatively, it can work side by side with the {@link module:utils/keystrokehandler~KeystrokeHandler}:
  *
  *		const keystrokeHandler = new KeystrokeHandler();
  *
@@ -42,7 +48,7 @@ import global from '@ckeditor/ckeditor5-utils/src/dom/global';
  *			focusables, focusTracker, keystrokeHandler,
  *			actions: {
  *				// When arrowup of arrowleft is detected by the #keystrokeHandler
- *				// focusPrevious() will be called by the cycler.
+ *				// focusPrevious() will be called on the cycler.
  *				focusPrevious: [ 'arrowup', 'arrowleft' ],
  *			}
  *		} );
@@ -61,14 +67,14 @@ export default class FocusCycler {
 		Object.assign( this, options );
 
 		/**
-		 * A view collection the cycler operates on.
+		 * A {@link module:ui/view~View view} collection the cycler operates on.
 		 *
 		 * @readonly
 		 * @member {module:utils/collection~Collection} #focusables
 		 */
 
 		/**
-		 * A focus tracker instance that cycler uses to determine focus
+		 * A focus tracker instance that cycler uses to determine the current focus
 		 * state in {@link #focusables}.
 		 *
 		 * @readonly
@@ -76,7 +82,8 @@ export default class FocusCycler {
 		 */
 
 		/**
-		 * Instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}.
+		 * An instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}
+		 * which can respond to certain keystrokes and cycle the focus.
 		 *
 		 * @readonly
 		 * @member {module:utils/keystrokehandler~KeystrokeHandler} #keystrokeHandler
@@ -85,8 +92,8 @@ export default class FocusCycler {
 		/**
 		 * Actions that the cycler can take when a keystroke is pressed. Requires
 		 * `options.keystrokeHandler` to be passed and working. When an action is
-		 * performed, the event the keystroke fired is will be `preventDefault` and
-		 * `stopPropagation` in DOM.
+		 * performed, `preventDefault` and `stopPropagation` will be called on the event
+		 * the keystroke fired in DOM.
 		 *
 		 *		actions: {
 		 *			// Will call #focusPrevious() when arrowleft or arrowup is pressed.
@@ -120,7 +127,7 @@ export default class FocusCycler {
 
 	/**
 	 * Returns the first focusable view in {@link #focusables}.
-	 * `null` if there's none.
+	 * Returns `null` if there is none.
 	 *
 	 * @readonly
 	 * @member {module:ui/view~View|null} #first
@@ -131,7 +138,7 @@ export default class FocusCycler {
 
 	/**
 	 * Returns the last focusable view in {@link #focusables}.
-	 * `null` if there's none.
+	 * Returns `null` if there is none.
 	 *
 	 * @readonly
 	 * @member {module:ui/view~View|null} #last
@@ -142,7 +149,7 @@ export default class FocusCycler {
 
 	/**
 	 * Returns the next focusable view in {@link #focusables} based on {@link #current}.
-	 * `null` if there's none.
+	 * Returns `null` if there is none.
 	 *
 	 * @readonly
 	 * @member {module:ui/view~View|null} #next
@@ -153,7 +160,7 @@ export default class FocusCycler {
 
 	/**
 	 * Returns the previous focusable view in {@link #focusables} based on {@link #current}.
-	 * `null` if there's none.
+	 * Returns `null` if there is none.
 	 *
 	 * @readonly
 	 * @member {module:ui/view~View|null} #previous
@@ -164,7 +171,7 @@ export default class FocusCycler {
 
 	/**
 	 * An index of the view in the {@link #focusables} which is focused according
-	 * to {@link #focusTracker}. `null` when there's no such view.
+	 * to {@link #focusTracker}. `null` when there is no such view.
 	 *
 	 * @readonly
 	 * @member {Number|null} #current
@@ -191,28 +198,28 @@ export default class FocusCycler {
 	}
 
 	/**
-	 * Focuses the {@link #first} item.
+	 * Focuses the {@link #first} item in {@link #focusables}.
 	 */
 	focusFirst() {
 		this._focus( this.first );
 	}
 
 	/**
-	 * Focuses the {@link #last} item.
+	 * Focuses the {@link #last} item in {@link #focusables}.
 	 */
 	focusLast() {
 		this._focus( this.last );
 	}
 
 	/**
-	 * Focuses the {@link #next} item.
+	 * Focuses the {@link #next} item in {@link #focusables}.
 	 */
 	focusNext() {
 		this._focus( this.next );
 	}
 
 	/**
-	 * Focuses the {@link #previous} item.
+	 * Focuses the {@link #previous} item in {@link #focusables}.
 	 */
 	focusPrevious() {
 		this._focus( this.previous );