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
