Przeglądaj źródła

Docs: Introduce `ButtonInterface` and `DropdownButtonInterface`.

Maciej Gołaszewski 7 lat temu
rodzic
commit
0fea8ab3b4

+ 140 - 0
packages/ckeditor5-ui/src/button/buttoninterface.jsdoc

@@ -0,0 +1,140 @@
+/**
+ * @license Copyright (c) 2003-2018, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/**
+ * @module ui/button/buttoninterface
+ */
+
+/**
+ * The button interface.
+ *
+ * @interface module:ui/button/buttoninterface~ButtonInterface
+ */
+
+/**
+ * The button view class.
+ *
+ *		const view = new ButtonView();
+ *
+ *		view.set( {
+ *			label: 'A button',
+ *			keystroke: 'Ctrl+B',
+ *			tooltip: true,
+ *			withText: true
+ *		} );
+ *
+ *		view.render();
+ *
+ *		document.body.append( view.element );
+ *
+ * @extends module:ui/view~View
+ */
+
+/**
+ * The label of the button view visible to the user when {@link #withText} is `true`.
+ * It can also be used to create a {@link #tooltip}.
+ *
+ * @observable
+ * @member {String} #label
+ */
+
+/**
+ * (Optional) The keystroke associated with the button, i.e. <kbd>CTRL+B</kbd>,
+ * in the string format compatible with {@link module:utils/keyboard}.
+ *
+ * @observable
+ * @member {Boolean} #keystroke
+ */
+
+/**
+ * (Optional) Tooltip of the button, i.e. displayed when hovering the button with the mouse cursor.
+ *
+ * * If defined as a `Boolean` (e.g. `true`), then combination of `label` and `keystroke` will be set as a tooltip.
+ * * If defined as a `String`, tooltip will equal the exact text of that `String`.
+ * * If defined as a `Function`, `label` and `keystroke` will be passed to that function, which is to return
+ * a string with the tooltip text.
+ *
+ *		const view = new ButtonView( locale );
+ *		view.tooltip = ( label, keystroke ) => `A tooltip for ${ label } and ${ keystroke }.`
+ *
+ * @observable
+ * @default false
+ * @member {Boolean|String|Function} #tooltip
+ */
+
+/**
+ * (Optional) The position of the tooltip. See {@link module:ui/tooltip/tooltipview~TooltipView#position}
+ * to learn more about the available position values.
+ *
+ * **Note:** It makes sense only when the {@link #tooltip `tooltip` attribute} is defined.
+ *
+ * @observable
+ * @default 's'
+ * @member {'s'|'n'} #position
+ */
+
+/**
+ * The HTML type of the button. Default `button`.
+ *
+ * @observable
+ * @member {'button'|'submit'|'reset'|'menu'} #type
+ */
+
+/**
+ * Controls whether the button view is "on". It makes sense when a feature it represents
+ * is currently active, e.g. a bold button is "on" when the selection is in the bold text.
+ *
+ * To disable the button, use {@link #isEnabled} instead.
+ *
+ * @observable
+ * @member {Boolean} #isOn
+ */
+
+/**
+ * Controls whether the button view is enabled, i.e. it can be clicked and execute an action.
+ *
+ * To change the "on" state of the button, use {@link #isOn} instead.
+ *
+ * @observable
+ * @member {Boolean} #isEnabled
+ */
+
+/**
+ * Controls whether the button view is visible. Visible by default, buttons are hidden
+ * using a CSS class.
+ *
+ * @observable
+ * @member {Boolean} #isVisible
+ */
+
+/**
+ * (Optional) Controls whether the label of the button is hidden (e.g. an icon–only button).
+ *
+ * @observable
+ * @member {Boolean} #withText
+ */
+
+/**
+ * (Optional) An XML {@link module:ui/icon/iconview~IconView#content content} of the icon.
+ * When defined, an `iconView` should be added to the button.
+ *
+ * @observable
+ * @member {String} #icon
+ */
+
+/**
+ * (Optional) Controls the `tabindex` HTML attribute of the button. By default, the button is focusable
+ * but does not included in the <kbd>Tab</kbd> order.
+ *
+ * @observable
+ * @default -1
+ * @member {String} #tabindex
+ */
+/**
+ * Fired when the button view is clicked. It won't be fired when the button {@link #isEnabled}
+ * is `false`.
+ *
+ * @event execute
+ */

+ 1 - 0
packages/ckeditor5-ui/src/button/buttonview.js

@@ -32,6 +32,7 @@ import '../../theme/components/button/button.css';
  *		document.body.append( view.element );
  *
  * @extends module:ui/view~View
+ * @implements module:ui/button/buttoninterface~ButtonInterface
  */
 export default class ButtonView extends View {
 	/**

+ 12 - 6
packages/ckeditor5-ui/src/dropdown/button/dropdownbuttonview.js

@@ -15,7 +15,7 @@ import IconView from '../../icon/iconview';
 /**
  * The default dropdown button view class.
  *
- *		const view = new SplitButtonView();
+ *		const view = new DropdownButtonView();
  *
  *		view.set( {
  *			label: 'A button',
@@ -28,6 +28,7 @@ import IconView from '../../icon/iconview';
  *		document.body.append( view.element );
  *
  * @extends module:ui/view~View
+ * @implements module:ui/dropdown/dropdownbuttoninterface~DropdownButtonInterface
  */
 export default class DropdownButtonView extends ButtonView {
 	/**
@@ -37,15 +38,21 @@ export default class DropdownButtonView extends ButtonView {
 		super( locale );
 
 		/**
-		 * A secondary button of split button that opens dropdown.
+		 * An icon that displays arrow to indicate a dropdown button.
 		 *
 		 * @readonly
-		 * @member {module:ui/button/buttonview~ButtonView}
+		 * @member {module:ui/dropdown/button/dropdownbuttonview~DropdownButtonView}
 		 */
 		this.arrowView = this._createArrowView();
 
 		// Dropdown expects "select" event on button view upon which the dropdown will open.
 		this.delegate( 'execute' ).to( this, 'select' );
+
+		/**
+		 * Fired when the view is clicked. It won't be fired when the button {@link #isEnabled} is `false`.
+		 *
+		 * @event select
+		 */
 	}
 
 	/**
@@ -58,11 +65,10 @@ export default class DropdownButtonView extends ButtonView {
 	}
 
 	/**
-	 * Creates a {@link module:ui/button/buttonview~ButtonView} instance as {@link #arrowView} and binds it with main split button
-	 * attributes.
+	 * Creates a {@link module:ui/icon/iconview~IconView} instance as {@link #arrowView}.
 	 *
 	 * @private
-	 * @returns {module:ui/button/buttonview~ButtonView}
+	 * @returns {module:ui/icon/iconview~IconView}
 	 */
 	_createArrowView() {
 		const arrowView = new IconView();

+ 4 - 3
packages/ckeditor5-ui/src/dropdown/button/splitbuttonview.js

@@ -33,6 +33,7 @@ import '../../../theme/components/button/splitbutton.css';
  *		document.body.append( view.element );
  *
  * @extends module:ui/view~View
+ * @implements module:ui/dropdown/dropdownbuttoninterface~DropdownButtonInterface
  */
 export default class SplitButtonView extends View {
 	/**
@@ -60,7 +61,7 @@ export default class SplitButtonView extends View {
 		this.set( 'label' );
 
 		/**
-		 * (Optional) The keystroke associated with the button, i.e. <kbd>CTRL+B</kbd>,
+		 * (Optional) The keystroke associated with the button, i.e. <kbd>Ctrl</kbd>+<kbd>B</kbd>,
 		 * in the string format compatible with {@link module:utils/keyboard}.
 		 *
 		 * @observable
@@ -143,8 +144,8 @@ export default class SplitButtonView extends View {
 		 * Instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}. It manages
 		 * keystrokes of the split button:
 		 *
-		 * * <kbd>▶</kbd> moves focus to select view when action view is focused,
-		 * * <kbd>◀</kbd> moves focus to action view when select view is focused.
+		 * * <kbd>▶</kbd> moves focus to arrow view when action view is focused,
+		 * * <kbd>◀</kbd> moves focus to action view when arrow view is focused.
 		 *
 		 * @readonly
 		 * @member {module:utils/keystrokehandler~KeystrokeHandler}

+ 21 - 0
packages/ckeditor5-ui/src/dropdown/dropdownbuttoninterface.jsdoc

@@ -0,0 +1,21 @@
+/**
+ * @license Copyright (c) 2003-2018, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/**
+ * @module ui/dropdown/dropdownbuttoninterface
+ */
+
+/**
+ * The dropdown button interface.
+ *
+ * @interface module:ui/dropdown/dropdownbuttoninterface~DropdownButtonInterface
+ * @extends module:ui/button/buttoninterface~ButtonInterface
+ */
+
+/**
+ * Fired when the arrow view is clicked. It won't be fired when the button {@link #isEnabled} is `false`.
+ *
+ * @event select
+ */

+ 1 - 1
packages/ckeditor5-ui/src/dropdown/dropdownpanelfocusable.jsdoc

@@ -8,7 +8,7 @@
  */
 
 /**
- * The dropdown panel interface interface for focusable contents. It provides two methods for managing focus of the contents
+ * The dropdown panel interface for focusable contents. It provides two methods for managing focus of the contents
  * of dropdown's panel.
  *
  * @interface module:ui/dropdown/dropdownpanelfocusable~DropdownPanelFocusable