8
0
Quellcode durchsuchen

Docs: Reviewed and improved documentation of the dropdowns.

Aleksander Nowodzinski vor 8 Jahren
Ursprung
Commit
9fd8f6bb54

+ 39 - 16
packages/ckeditor5-ui/src/button/buttonview.js

@@ -17,6 +17,19 @@ import { getEnvKeystrokeText } from '@ckeditor/ckeditor5-utils/src/keyboard';
 /**
  * The button view class.
  *
+ *		const view = new ButtonView();
+ *
+ *		view.set( {
+ *			label: 'A button',
+ *			keystroke: 'Ctrl+B',
+ *			tooltip: true,
+ *			withText: true
+ *		} );
+ *
+ *		view.init();
+ *
+ *		document.body.append( view.element );
+ *
  * @extends module:ui/view~View
  */
 export default class ButtonView extends View {
@@ -27,7 +40,8 @@ export default class ButtonView extends View {
 		super( locale );
 
 		/**
-		 * The label of the button view visible to the user.
+		 * 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
@@ -61,10 +75,10 @@ export default class ButtonView extends View {
 		this.set( 'tooltip' );
 
 		/**
-		 * The position of the tooltip. See {@link module:ui/tooltip/tooltipview~TooltipView#position}
+		 * (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} is active.
+		 * **Note:** It makes sense only when the {@link #tooltip `tooltip` attribute} is defined.
 		 *
 		 * @observable
 		 * @default 's'
@@ -81,8 +95,10 @@ export default class ButtonView extends View {
 		this.set( 'type', 'button' );
 
 		/**
-		 * Controls whether the button view is "on", e.g. some feature which it represents
-		 * is currently enabled.
+		 * 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
@@ -90,7 +106,9 @@ export default class ButtonView extends View {
 		this.set( 'isOn', false );
 
 		/**
-		 * Controls whether the button view is enabled (can be clicked).
+		 * 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
@@ -98,7 +116,8 @@ export default class ButtonView extends View {
 		this.set( 'isEnabled', true );
 
 		/**
-		 * Controls whether the button view is visible.
+		 * Controls whether the button view is visible. Visible by default, buttons are hidden
+		 * using a CSS class.
 		 *
 		 * @observable
 		 * @member {Boolean} #isVisible
@@ -106,7 +125,7 @@ export default class ButtonView extends View {
 		this.set( 'isVisible', true );
 
 		/**
-		 * (Optional) Whether the label of the button is hidden (e.g. button with icon only).
+		 * (Optional) Controls whether the label of the button is hidden (e.g. an icon–only button).
 		 *
 		 * @observable
 		 * @member {Boolean} #withText
@@ -114,7 +133,8 @@ export default class ButtonView extends View {
 		this.set( 'withText', false );
 
 		/**
-		 * (Optional) Source of the icon. See {@link module:ui/icon/iconview~IconView#content}.
+		 * (Optional) An XML {@link module:ui/icon/iconview~IconView#content content} of the icon.
+		 * When defined, an {@link #iconView} will be added to the button.
 		 *
 		 * @observable
 		 * @member {String} #icon
@@ -122,7 +142,8 @@ export default class ButtonView extends View {
 		this.set( 'icon' );
 
 		/**
-		 * Controls the `tabindex` attribute of the button.
+		 * (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
@@ -147,7 +168,7 @@ export default class ButtonView extends View {
 		);
 
 		/**
-		 * Tooltip of the button view.
+		 * Tooltip of the button view. It is configurable using the {@link #tooltip tooltip attribute}.
 		 *
 		 * @readonly
 		 * @member {module:ui/tooltip/tooltipview~TooltipView} #tooltipView
@@ -155,7 +176,7 @@ export default class ButtonView extends View {
 		this.tooltipView = this._createTooltipView();
 
 		/**
-		 * Icon of the button view.
+		 * (Optional) The icon view of the button. Only present when the {@link #icon icon attribute} is defined.
 		 *
 		 * @readonly
 		 * @member {module:ui/icon/iconview~IconView} #iconView
@@ -215,9 +236,10 @@ export default class ButtonView extends View {
 		} );
 
 		/**
-		 * Fired when the button view is clicked. It won't be fired when the button is disabled.
+		 * Fired when the button view is clicked. It won't be fired when the button {@link #isEnabled}
+		 * is `false`.
 		 *
-		 * @event #execute
+		 * @event execute
 		 */
 	}
 
@@ -239,14 +261,15 @@ export default class ButtonView extends View {
 	}
 
 	/**
-	 * Focuses the button.
+	 * Focuses the {@link #element} of the button.
 	 */
 	focus() {
 		this.element.focus();
 	}
 
 	/**
-	 * Creates TooltipView instance and bind with button properties.
+	 * Creates a {@link module:ui/tooltip/tooltipview~TooltipView} instance and binds it with button
+	 * attributes.
 	 *
 	 * @private
 	 * @returns {module:ui/tooltip/tooltipview~TooltipView}

+ 22 - 2
packages/ckeditor5-ui/src/dropdown/createdropdown.js

@@ -12,8 +12,28 @@ import DropdownView from './dropdownview';
 import DropdownPanelView from './dropdownpanelview';
 
 /**
- * Creates an instance of {@link module:ui/dropdown/dropdownview~DropdownView} class using
- * defined model.
+ * A helper which creates an instance of {@link module:ui/dropdown/dropdownview~DropdownView} class using
+ * a provided {@link module:ui/dropdown/dropdownmodel~DropdownModel}.
+ *
+ *		const model = new Model( {
+ *			label: 'A dropdown',
+ *			isEnabled: true,
+ *			isOn: false,
+ *			withText: true
+ *		} );
+ *
+ *		const dropdown = createDropdown( model );
+ *
+ *		dropdown.init();
+ *
+ *		// Will render a dropdown labeled "A dropdown" with an empty panel.
+ *		document.body.appendChild( dropdown.element );
+ *
+ * The model instance remains in control of the dropdown after it has been created. E.g. changes to the
+ * {@link module:ui/dropdown/dropdownmodel~DropdownModel#label `model.label`} will be reflected in the
+ * dropdown button's {@link module:ui/button/buttonview~ButtonView#label} attribute and in DOM.
+ *
+ * Also see {@link module:ui/dropdown/list/createlistdropdown~createListDropdown}.
  *
  * @param {module:ui/dropdown/dropdownmodel~DropdownModel} model Model of this dropdown.
  * @param {module:utils/locale~Locale} locale The locale instance.

+ 12 - 3
packages/ckeditor5-ui/src/dropdown/dropdownmodel.jsdoc

@@ -16,26 +16,35 @@
 /**
  * The label of the dropdown.
  *
+ * Also see {@link module:ui/button/buttonview~ButtonView#label}.
+ *
  * @observable
  * @member {String} #label
  */
 
 /**
- * Controls whether the dropdown is enabled (can be clicked).
+ * Controls whether the dropdown is enabled, i.e. it opens the panel when clicked.
+ *
+ * Also see {@link module:ui/button/buttonview~ButtonView#isEnabled}.
  *
  * @observable
  * @member {Boolean} #isEnabled
  */
 
 /**
- * Controls whether the {@link module:ui/dropdown/dropdownview~DropdownView#buttonView} is "pushed".
+ * Controls whether the dropdown is "on". It makes sense when a feature it represents
+ * is currently active.
+ *
+ * Also see {@link module:ui/button/buttonview~ButtonView#isOn}.
  *
  * @observable
  * @member {Boolean} #isOn
  */
 
 /**
- * (Optional) Whether the label of the dropdown is visible. See {@link module:ui/button/buttonview~ButtonView#withText}.
+ * (Optional) Controls whether the label of the dropdown is visible.
+ *
+ * Also see {@link module:ui/button/buttonview~ButtonView#withText}.
  *
  * @observable
  * @member {Boolean} #withText

+ 7 - 1
packages/ckeditor5-ui/src/dropdown/dropdownpanelview.js

@@ -13,6 +13,8 @@ import Template from '../template';
 /**
  * The dropdown panel view class.
  *
+ * See {@link module:ui/dropdown/dropdownview~DropdownView} to learn about the common usage.
+ *
  * @extends module:ui/view~View
  */
 export default class DropdownPanelView extends View {
@@ -33,7 +35,11 @@ export default class DropdownPanelView extends View {
 		this.set( 'isVisible', false );
 
 		/**
-		 * Collection of the child views.
+		 * Collection of the child views in this panel.
+		 *
+		 * A common child type is the {@link module:list/list~List}. See
+		 * {@link module:ui/dropdown/list/createlistdropdown~createListDropdown} to learn more
+		 * about list dropdowns.
 		 *
 		 * @readonly
 		 * @member {module:ui/viewcollection~ViewCollection}

+ 37 - 7
packages/ckeditor5-ui/src/dropdown/dropdownview.js

@@ -15,6 +15,25 @@ import KeystrokeHandler from '@ckeditor/ckeditor5-utils/src/keystrokehandler';
 /**
  * The dropdown view class.
  *
+ *		const button = new ButtonView( locale );
+ *		const panel = new DropdownPanelView( locale );
+ *		const dropdown = new DropdownView( locale, button, panel );
+ *
+ *		panel.element.textContent = 'Content of the panel';
+ *		button.set( {
+ *			label: 'A dropdown',
+ *			withText: true
+ *		} );
+ *
+ *		dropdown.init();
+ *
+ *		// Will render a dropdown with a panel containing a "Content of the panel" text.
+ *		document.body.appendChild( dropdown.element );
+ *
+ * Also see {@link module:ui/dropdown/createdropdown~createDropdown} and
+ * {@link module:ui/dropdown/list/createlistdropdown~createListDropdown} to learn about different
+ * dropdown creation helpers.
+ *
  * @extends module:ui/view~View
  */
 export default class DropdownView extends View {
@@ -36,15 +55,23 @@ export default class DropdownView extends View {
 		} );
 
 		/**
-		 * Button of this dropdown view.
+		 * Button of the dropdown view. Clicking the button opens the {@link #panelView}.
 		 *
 		 * @readonly
-		 * @member {ui.button.ButtonView} #buttonView
+		 * @member {module:ui/button/buttonview~ButtonView} #buttonView
 		 */
 		this.buttonView = buttonView;
 
 		/**
-		 * Panel of this dropdown view.
+		 * Panel of the dropdown. It opens when the {@link #buttonView} is
+		 * {@link module:ui/button/buttonview~ButtonView#event:execute executed} (i.e. clicked).
+		 *
+		 * Child views can be added to the panel's `children` collection:
+		 *
+		 *		dropdown.panelView.children.add( childView );
+		 *
+		 * See {@link module:ui/dropdown/dropdownpanelview~DropdownPanelView#children} and
+		 * {@link module:ui/viewcollection~ViewCollection#add}.
 		 *
 		 * @readonly
 		 * @member {module:ui/dropdown/dropdownpanelview~DropdownPanelView} #panelView
@@ -52,8 +79,7 @@ export default class DropdownView extends View {
 		this.panelView = panelView;
 
 		/**
-		 * Controls whether the dropdown view is open, which also means its
-		 * {@link #panelView panel} is visible.
+		 * Controls whether the dropdown view is open, i.e. shows or hides the {@link #panelView panel}.
 		 *
 		 * @observable
 		 * @member {Boolean} #isOpen
@@ -61,7 +87,7 @@ export default class DropdownView extends View {
 		this.set( 'isOpen', false );
 
 		/**
-		 * Tracks information about DOM focus in the list.
+		 * Tracks information about DOM focus in the dropdown.
 		 *
 		 * @readonly
 		 * @member {module:utils/focustracker~FocusTracker}
@@ -69,7 +95,11 @@ export default class DropdownView extends View {
 		this.focusTracker = new FocusTracker();
 
 		/**
-		 * Instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}.
+		 * Instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}. It manages
+		 * keystrokes of the dropdown:
+		 *
+		 * * <kbd>▼</kbd> opens the dropdown,
+		 * * <kbd>◀</kbd> and <kbd>Esc</kbd> closes the dropdown.
 		 *
 		 * @readonly
 		 * @member {module:utils/keystrokehandler~KeystrokeHandler}

+ 33 - 2
packages/ckeditor5-ui/src/dropdown/list/createlistdropdown.js

@@ -15,9 +15,40 @@ import createDropdown from '../createdropdown';
 
 /**
  * Creates an instance of {@link module:ui/dropdown/list/listdropdownview~ListDropdownView} class using
- * defined model.
+ * a provided {@link module:ui/dropdown/list/listdropdownmodel~ListDropdownModel}.
  *
- * @param {module:ui/dropdown/list/listdropdownmodel~ListDropdownModel} model Model of this list dropdown.
+ *		const items = new Collection();
+ *
+ *		items.add( new Model( { label: 'First item', style: 'color: red' } ) );
+ *		items.add( new Model( { label: 'Second item', style: 'color: green', class: 'foo' } ) );
+ *
+ *		const model = new Model( {
+ *			isEnabled: true,
+ *			items,
+ *			isOn: false,
+ *			label: 'A dropdown'
+ *		} );
+ *
+ *		const dropdown = createListDropdown( model, locale );
+ *
+ *		dropdown.init();
+ *
+ *		// Will render a dropdown labeled "A dropdown" with a list in the panel
+ *		// containing two items.
+ *		document.body.appendChild( dropdown.element );
+ *
+ * The model instance remains in control of the dropdown after it has been created. E.g. changes to the
+ * {@link module:ui/dropdown/dropdownmodel~DropdownModel#label `model.label`} will be reflected in the
+ * dropdown button's {@link module:ui/button/buttonview~ButtonView#label} attribute and in DOM.
+ *
+ * The
+ * {@link module:ui/dropdown/list/listdropdownmodel~ListDropdownModel#items items collection}
+ * of the {@link module:ui/dropdown/list/listdropdownmodel~ListDropdownModel model} also controls the
+ * presence and attributes of respective {@link module:ui/list/listitemview~ListItemView list items}.
+ *
+ * See {@link module:ui/dropdown/createdropdown~createDropdown} and {@link module:list/list~List}.
+ *
+ * @param {module:ui/dropdown/list/listdropdownmodel~ListDropdownModel} model Model of the list dropdown.
  * @param {module:utils/locale~Locale} locale The locale instance.
  * @returns {module:ui/dropdown/list/listdropdownview~ListDropdownView} The list dropdown view instance.
  */

+ 8 - 5
packages/ckeditor5-ui/src/dropdown/list/listdropdownmodel.jsdoc

@@ -15,16 +15,19 @@
  */
 
 /**
- * A {@link module:utils/collection~Collection} of {@link module:utils/observablemixin~Observable} used to populate
- * the inner {@link module:ui/list/listview~ListView} instance.
+ * A {@link module:utils/collection~Collection} of {@link module:utils/observablemixin~Observable}
+ * that the inner dropdown {@link module:ui/list/listview~ListView} children are created from.
+ *
+ * Usually, it is a collection of {@link module:ui/model~Model models}.
  *
  * @observable
- * @member {Boolean} #items
+ * @member {module:utils/collection~Collection.<module:utils/observablemixin~Observable>} #items
  */
 
 /**
- * Fired when the list dropdown should be executed, usually when
- * one of the list items in {@link #items} has been executed.
+ * Fired when the list dropdown is executed. It fires when one of the list items in
+ * {@link #items the collection} has been
+ * {@link module:ui/list/listitemview~ListItemView#event:execute executed}.
  *
  * @event #execute
  */

+ 2 - 1
packages/ckeditor5-ui/src/dropdown/list/listdropdownview.jsdoc

@@ -18,7 +18,8 @@
  */
 
 /**
- * List of the list dropdown view.
+ * A child {@link module:ui/list/listview~ListView list view} of the dropdown located
+ * in its {@link module:ui/dropdown/dropdownview~DropdownView#panelView panel}.
  *
  * @readonly
  * @member {module:ui/list/listview~ListView} #listView

+ 1 - 1
packages/ckeditor5-ui/src/list/listitemview.js

@@ -97,7 +97,7 @@ export default class ListItemView extends View {
 		/**
 		 * Fired when the list item has been clicked.
 		 *
-		 * @event #execute
+		 * @event execute
 		 */
 	}