jenkins-bot has submitted this change and it was merged. Change subject: Tool*: Expand, correct docs for #onUpdateState and the related event ......................................................................
Tool*: Expand, correct docs for #onUpdateState and the related event After 5be12b4ae48bc9590f425ec2addd64226b2658ce, the #onUpdateState method actually *has* to be defined, otherwise the toolbar won't initialize. (Spotted by Prateek.) The whole thing was basically not documented, though, so let's take this opportunity to write a bit about it. Change-Id: Ia7b9203e90efa1416690a7e8da2b9a38f25e4617 --- M src/Tool.js M src/Toolbar.js M src/toolgroups/BarToolGroup.js M src/toolgroups/ListToolGroup.js M src/toolgroups/MenuToolGroup.js 5 files changed, 45 insertions(+), 18 deletions(-) Approvals: Ori.livneh: Looks good to me, but someone else must approve Jforrester: Looks good to me, approved jenkins-bot: Verified diff --git a/src/Tool.js b/src/Tool.js index c85057e..b5dd73e 100644 --- a/src/Tool.js +++ b/src/Tool.js @@ -4,6 +4,11 @@ * out when the tool is selected. Tools must also be registered with a {@link OO.ui.ToolFactory tool factory}, * which creates the tools on demand. * + * Every Tool subclass must implement two methods: + * + * - {@link #onUpdateState} + * - {@link #onSelect} + * * Tools are added to toolgroups ({@link OO.ui.ListToolGroup ListToolGroup}, * {@link OO.ui.BarToolGroup BarToolGroup}, or {@link OO.ui.MenuToolGroup MenuToolGroup}), which determine how * the tool is displayed in the toolbar. See {@link OO.ui.Toolbar toolbars} for an example. @@ -192,7 +197,11 @@ /* Methods */ /** - * Handle the toolbar state being updated. + * Handle the toolbar state being updated. This method is called when the + * {@link OO.ui.Toolbar#event-updateState 'updateState' event} is emitted on the + * {@link OO.ui.Toolbar Toolbar} that uses this tool, and should set the state of this tool + * depending on application state (usually by calling #setDisabled to enable or disable the tool, + * or #setActive to mark is as currently in-use or not). * * This is an abstract method that must be overridden in a concrete subclass. * @@ -203,7 +212,8 @@ OO.ui.Tool.prototype.onUpdateState = null; /** - * Handle the tool being selected. + * Handle the tool being selected. This method is called when the user triggers this tool, + * usually by clicking on its label/icon. * * This is an abstract method that must be overridden in a concrete subclass. * diff --git a/src/Toolbar.js b/src/Toolbar.js index 24019f1..f6c67a0 100644 --- a/src/Toolbar.js +++ b/src/Toolbar.js @@ -12,6 +12,13 @@ * The arrangement and order of the toolgroups is customized when the toolbar is set up. Tools can be presented in * any order, but each can only appear once in the toolbar. * + * The toolbar can be synchronized with the state of the external "application", like a text + * editor's editing area, marking tools as active/inactive (e.g. a 'bold' tool would be shown as + * active when the text cursor was inside bolded text) or enabled/disabled (e.g. a table caption + * tool would be disabled while the user is not editing a table). A state change is signalled by + * emitting the {@link #event-updateState 'updateState' event}, which calls Tools' + * {@link OO.ui.Tool#onUpdateState onUpdateState method}. + * * The following is an example of a basic toolbar. * * @example @@ -42,6 +49,7 @@ * // Never display this tool as "active" (selected). * this.setActive( false ); * }; + * ImageTool.prototype.onUpdateState = function () {}; * // Make this tool available in our toolFactory and thus our toolbar * toolFactory.register( ImageTool ); * @@ -57,6 +65,7 @@ * $area.text( 'Settings tool clicked!' ); * this.setActive( false ); * }; + * SettingsTool.prototype.onUpdateState = function () {}; * toolFactory.register( SettingsTool ); * * // Register two more tools, nothing interesting here @@ -71,6 +80,7 @@ * $area.text( 'More stuff tool clicked!' ); * this.setActive( false ); * }; + * StuffTool.prototype.onUpdateState = function () {}; * toolFactory.register( StuffTool ); * * // This is a PopupTool. Rather than having a custom 'onSelect' action, it will display a @@ -127,9 +137,10 @@ * // Here is where the toolbar is actually built. This must be done after inserting it into the * // document. * toolbar.initialize(); + * toolbar.emit( 'updateState' ); * * The following example extends the previous one to illustrate 'menu' toolgroups and the usage of - * 'updateState' event. + * {@link #event-updateState 'updateState' event}. * * @example * // Create the toolbar @@ -158,11 +169,7 @@ * // Never display this tool as "active" (selected). * this.setActive( false ); * }; - * // The toolbar can be synchronized with the state of some external stuff, like a text - * // editor's editing area, highlighting the tools (e.g. a 'bold' tool would be shown as active - * // when the text cursor was inside bolded text). Here we simply disable this feature. - * ImageTool.prototype.onUpdateState = function () { - * }; + * ImageTool.prototype.onUpdateState = function () {}; * // Make this tool available in our toolFactory and thus our toolbar * toolFactory.register( ImageTool ); * @@ -183,8 +190,7 @@ * // To update the menu label * this.toolbar.emit( 'updateState' ); * }; - * SettingsTool.prototype.onUpdateState = function () { - * }; + * SettingsTool.prototype.onUpdateState = function () {}; * toolFactory.register( SettingsTool ); * * // Register two more tools, nothing interesting here @@ -204,8 +210,7 @@ * // To update the menu label * this.toolbar.emit( 'updateState' ); * }; - * StuffTool.prototype.onUpdateState = function () { - * }; + * StuffTool.prototype.onUpdateState = function () {}; * toolFactory.register( StuffTool ); * * // This is a PopupTool. Rather than having a custom 'onSelect' action, it will display a @@ -328,6 +333,18 @@ OO.mixinClass( OO.ui.Toolbar, OO.EventEmitter ); OO.mixinClass( OO.ui.Toolbar, OO.ui.mixin.GroupElement ); +/* Events */ + +/** + * @event updateState + * + * An 'updateState' event must be emitted on the Toolbar (by calling `toolbar.emit( 'updateState' )`) + * every time the state of the application using the toolbar changes, and an update to the state of + * tools is required. + * + * @param {Mixed...} data Application-defined parameters + */ + /* Methods */ /** diff --git a/src/toolgroups/BarToolGroup.js b/src/toolgroups/BarToolGroup.js index 760743d..7980585 100644 --- a/src/toolgroups/BarToolGroup.js +++ b/src/toolgroups/BarToolGroup.js @@ -35,6 +35,7 @@ * // Never display this tool as "active" (selected). * this.setActive( false ); * }; + * ImageTool.prototype.onUpdateState = function () {}; * // Make this tool available in our toolFactory and thus our toolbar * toolFactory.register( ImageTool ); * diff --git a/src/toolgroups/ListToolGroup.js b/src/toolgroups/ListToolGroup.js index 5ffa919..130ad74 100644 --- a/src/toolgroups/ListToolGroup.js +++ b/src/toolgroups/ListToolGroup.js @@ -30,6 +30,7 @@ * SettingsTool.prototype.onSelect = function () { * this.setActive( false ); * }; + * SettingsTool.prototype.onUpdateState = function () {}; * toolFactory.register( SettingsTool ); * // Register two more tools, nothing interesting here * function StuffTool() { @@ -42,6 +43,7 @@ * StuffTool.prototype.onSelect = function () { * this.setActive( false ); * }; + * StuffTool.prototype.onUpdateState = function () {}; * toolFactory.register( StuffTool ); * toolbar.setup( [ * { diff --git a/src/toolgroups/MenuToolGroup.js b/src/toolgroups/MenuToolGroup.js index c76e2db..f19bc7d 100644 --- a/src/toolgroups/MenuToolGroup.js +++ b/src/toolgroups/MenuToolGroup.js @@ -7,8 +7,7 @@ * the menu label is empty. The menu can be configured with an indicator, icon, title, and/or header. * * MenuToolGroups are created by a {@link OO.ui.ToolGroupFactory tool group factory} when the toolbar - * is set up. Note that all tools must define an {@link OO.ui.Tool#onUpdateState onUpdateState} method if - * a MenuToolGroup is used. + * is set up. * * @example * // Example of a MenuToolGroup @@ -37,8 +36,7 @@ * // To update the menu label * this.toolbar.emit( 'updateState' ); * }; - * SettingsTool.prototype.onUpdateState = function () { - * }; + * SettingsTool.prototype.onUpdateState = function () {}; * toolFactory.register( SettingsTool ); * * function StuffTool() { @@ -57,8 +55,7 @@ * // To update the menu label * this.toolbar.emit( 'updateState' ); * }; - * StuffTool.prototype.onUpdateState = function () { - * }; + * StuffTool.prototype.onUpdateState = function () {}; * toolFactory.register( StuffTool ); * * // Finally define which tools and in what order appear in the toolbar. Each tool may only be -- To view, visit https://gerrit.wikimedia.org/r/255789 To unsubscribe, visit https://gerrit.wikimedia.org/r/settings Gerrit-MessageType: merged Gerrit-Change-Id: Ia7b9203e90efa1416690a7e8da2b9a38f25e4617 Gerrit-PatchSet: 4 Gerrit-Project: oojs/ui Gerrit-Branch: master Gerrit-Owner: Bartosz Dziewoński <matma....@gmail.com> Gerrit-Reviewer: Bartosz Dziewoński <matma....@gmail.com> Gerrit-Reviewer: Esanders <esand...@wikimedia.org> Gerrit-Reviewer: Jforrester <jforres...@wikimedia.org> Gerrit-Reviewer: Ori.livneh <o...@wikimedia.org> Gerrit-Reviewer: jenkins-bot <> _______________________________________________ MediaWiki-commits mailing list MediaWiki-commits@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits