[MediaWiki-commits] [Gerrit] Toolbar: Add description - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/211902
Change subject: Toolbar: Add description
..
Toolbar: Add description
Change-Id: I35c44cba5f4823559c2f8515cf903e480245cc55
---
M src/Toolbar.js
1 file changed, 43 insertions(+), 24 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/02/211902/1
diff --git a/src/Toolbar.js b/src/Toolbar.js
index f52fbff..89285ab 100644
--- a/src/Toolbar.js
+++ b/src/Toolbar.js
@@ -1,9 +1,21 @@
/**
- * Collection of tool groups.
+ * Toolbars are complex interface components that permit users to easily
access a variety
+ * of {@link OO.ui.Tool tools} (e.g., formatting commands) and actions, which
are additional commands that are
+ * part of the toolbar, but not configured as tools.
*
- * The following is a minimal example using several tools and tool groups.
+ * Individual tools are customized and then registered with a {@link
OO.ui.ToolFactory tool factory}, which creates
+ * the tools on demand. Each tool has a symbolic name (used when registering
the tool), a title (e.g., ‘Insert
+ * picture’), and an icon.
+ *
+ * Individual tools are organized in {@link OO.ui.ToolGroup toolgroups}, which
can be {@link OO.ui.MenuToolGroup menus}
+ * of tools, {@link OO.ui.ListToolGroup lists} of tools, or a single {@link
OO.ui.BarToolGroup bar} of tools.
+ * 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 following is an example of a basic toolbar.
*
* @example
+ * // Example of a toolbar
* // Create the toolbar
* var toolFactory = new OO.ui.ToolFactory();
* var toolGroupFactory = new OO.ui.ToolGroupFactory();
@@ -116,7 +128,7 @@
* // document.
* toolbar.initialize();
*
- * The following example extends the previous one to illustrate 'menu' tool
groups and the usage of
+ * The following example extends the previous one to illustrate 'menu'
toolgroups and the usage of
* 'updateState' event.
*
* @example
@@ -256,10 +268,12 @@
*
* @constructor
* @param {OO.ui.ToolFactory} toolFactory Factory for creating tools
- * @param {OO.ui.ToolGroupFactory} toolGroupFactory Factory for creating tool
groups
+ * @param {OO.ui.ToolGroupFactory} toolGroupFactory Factory for creating
toolgroups
* @param {Object} [config] Configuration options
- * @cfg {boolean} [actions] Add an actions section opposite to the tools
- * @cfg {boolean} [shadow] Add a shadow below the toolbar
+ * @cfg {boolean} [actions] Add an actions section to the toolbar. Actions are
commands that are included
+ * in the toolbar, but are not configured as tools. By default, actions are
displayed on the right side of
+ * the toolbar.
+ * @cfg {boolean} [shadow] Add a shadow below the toolbar.
*/
OO.ui.Toolbar = function OoUiToolbar( toolFactory, toolGroupFactory, config ) {
// Allow passing positional parameters inside the config object
@@ -326,9 +340,9 @@
};
/**
- * Get the tool group factory.
+ * Get the toolgroup factory.
*
- * @return {OO.Factory} Tool group factory
+ * @return {OO.Factory} Toolgroup factory
*/
OO.ui.Toolbar.prototype.getToolGroupFactory = function () {
return this.toolGroupFactory;
@@ -337,6 +351,7 @@
/**
* Handles mouse down events.
*
+ * @private
* @param {jQuery.Event} e Mouse down event
*/
OO.ui.Toolbar.prototype.onPointerDown = function ( e ) {
@@ -372,19 +387,18 @@
};
/**
- * Setup toolbar.
+ * Set up the toolbar.
*
- * Tools can be specified in the following ways:
+ * The toolbar is set up with a list of toolgroup configurations that specify
the type of
+ * toolgroup ({@link OO.ui.BarToolGroup bar}, {@link OO.ui.MenuToolGroup
menu}, or {@link OO.ui.ListToolGroup list})
+ * to add and which tools to include, exclude, promote, or demote within that
toolgroup. Please
+ * see {@link OO.ui.ToolGroup toolgroups} for more information about including
tools in toolgroups.
*
- * - A specific tool: `{ name: 'tool-name' }` or `'tool-name'`
- * - All tools in a group: `{ group: 'group-name' }`
- * - All tools: `'*'` - Using this will make the group a list with a More
label by default
- *
- * @param {Object.string,Array} groups List of tool group configurations
- * @param {Array|string} [groups.include] Tools to include
- * @param {Array|string} [groups.exclude] Tools to exclude
- * @param {Array|string} [groups.promote] Tools to promote to the beginning
- * @param {Array|string} [groups.demote] Tools to demote to the end
+ * @param {Object.string,Array} groups List of toolgroup configurations
+ * @param {Array|string} [groups.include] Tools to include in the toolgroup
+ * @param {Array|string} [groups.exclude] Tools to exclude from the toolgroup
+ * @param {Array|string} [groups.promote] Tools to promote to the beginning of
the
[MediaWiki-commits] [Gerrit] ListToolGroup: Add description and example - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/211912
Change subject: ListToolGroup: Add description and example
..
ListToolGroup: Add description and example
Change-Id: I0c255fbffe7c358886f91391461c0b91a78a99e8
---
M src/toolgroups/ListToolGroup.js
1 file changed, 82 insertions(+), 9 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/12/211912/1
diff --git a/src/toolgroups/ListToolGroup.js b/src/toolgroups/ListToolGroup.js
index e78f507..7b56f5d 100644
--- a/src/toolgroups/ListToolGroup.js
+++ b/src/toolgroups/ListToolGroup.js
@@ -1,9 +1,77 @@
/**
- * Drop down list layout of tools as labeled icon buttons.
+ * ListToolGroups are one of three types of {@link OO.ui.ToolGroup toolgroups}
that are used to
+ * create {@link OO.ui.Toolbar toolbars} (the other types of groups are {@link
OO.ui.MenuToolGroup MenuToolGroup}
+ * and {@link OO.ui.BarToolGroup BarToolGroup}). The {@link OO.ui.Tool tools}
in a ListToolGroup are displayed
+ * by label in a dropdown menu. The title of the tool is used as the label
text. The menu itself can be configured
+ * with a label, icon, indicator, header, and title.
*
- * This layout allows some tools to be collapsible, controlled by a More /
Fewer option at the
- * bottom of the main list. These are not automatically positioned at the
bottom of the list; you
- * may want to use the 'promote' and 'demote' configuration options to achieve
this.
+ * ListToolGroups can be configured to be expanded and collapsed. Collapsed
lists will have a ‘More’ option that
+ * users can select to see the full list of tools. If a collapsed toolgroup is
expanded, a ‘Fewer’ option permits
+ * users to collapse the list again.
+ *
+ * ListToolGroups are created by a {@link OO.ui.ToolGroupFactory toolgroup
factory} when the toolbar is set up. The factory
+ * requires the ListToolGroup's symbolic name, 'list', which is specified
along with the other configurations. For more
+ * information about how to add tools to a ListToolGroup, please see {@link
OO.ui.ToolGroup toolgroup}.
+ *
+ * @example
+ * // Example of a ListToolGroup
+ * var toolFactory = new OO.ui.ToolFactory();
+ * var toolGroupFactory = new OO.ui.ToolGroupFactory();
+ * var toolbar = new OO.ui.Toolbar( toolFactory, toolGroupFactory );
+ *
+ * // Configure and register two tools
+ * function SettingsTool() {
+ * SettingsTool.super.apply( this, arguments );
+ * }
+ * OO.inheritClass( SettingsTool, OO.ui.Tool );
+ * SettingsTool.static.name = 'settings';
+ * SettingsTool.static.icon = 'settings';
+ * SettingsTool.static.title = 'Change settings';
+ * SettingsTool.prototype.onSelect = function () {
+ * this.setActive( false );
+ * };
+ * toolFactory.register( SettingsTool );
+ * // Register two more tools, nothing interesting here
+ * function StuffTool() {
+ * StuffTool.super.apply( this, arguments );
+ * }
+ * OO.inheritClass( StuffTool, OO.ui.Tool );
+ * StuffTool.static.name = 'stuff';
+ * StuffTool.static.icon = 'ellipsis';
+ * StuffTool.static.title = 'Change the world';
+ * StuffTool.prototype.onSelect = function () {
+ * this.setActive( false );
+ * };
+ * toolFactory.register( StuffTool );
+ * toolbar.setup( [
+ * {
+ * // Configurations for list toolgroup.
+ * type: 'list',
+ * label: 'ListToolGroup',
+ * indicator: 'down',
+ * icon: 'picture',
+ * title: 'This is the title, displayed when user moves the mouse
over the list toolgroup',
+ * header: 'This is the header',
+ * include: [ 'settings', 'stuff' ],
+ * allowCollapse: ['stuff']
+ * }
+ * ] );
+ *
+ * // Create some UI around the toolbar and place it in the document
+ * var frame = new OO.ui.PanelLayout( {
+ * expanded: false,
+ * framed: true
+ * } );
+ * frame.$element.append(
+ * toolbar.$element
+ * );
+ * $( 'body' ).append( frame.$element );
+ * // Build the toolbar. This must be done after the toolbar has been
appended to the document.
+ * toolbar.initialize();
+ *
+ * For more information about toolbars in general, please see the [OOjs UI
documentation on MediaWiki][1].
+ *
+ * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Toolbars
*
* @class
* @extends OO.ui.PopupToolGroup
@@ -11,11 +79,16 @@
* @constructor
* @param {OO.ui.Toolbar} toolbar
* @param {Object} [config] Configuration options
- * @cfg {Array} [allowCollapse] List of tools that can be collapsed. Remaining
tools will be always
- * shown.
- * @cfg {Array} [forceExpand] List of tools that *may not* be collapsed. All
remaining tools will be
- * allowed to be collapsed.
- * @cfg {boolean} [expanded=false] Whether the collapsible tools
[MediaWiki-commits] [Gerrit] PopupTool: Add description and example - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/211306
Change subject: PopupTool: Add description and example
..
PopupTool: Add description and example
Change-Id: I8d4f7a06ca4c16ad3346c2e9972f16d7aed9bee3
---
M src/tools/PopupTool.js
1 file changed, 24 insertions(+), 1 deletion(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/06/211306/1
diff --git a/src/tools/PopupTool.js b/src/tools/PopupTool.js
index 98f93d7..01fb91c 100644
--- a/src/tools/PopupTool.js
+++ b/src/tools/PopupTool.js
@@ -1,5 +1,28 @@
/**
- * Tool that shows a popup when selected.
+ * Popup tools open a popup window when they are selected from the {@link
OO.ui.Toolbar toolbar}. Each popup tool is configured
+ * with a static name, title, and icon, as well with as any popup
configurations. Unlike other tools, popup tools do not require that developers
specify
+ * an #onSelect or #onUpdateState method, as these methods have been
implemented already.
+ *
+ * // Example of a popup tool. When selected, a popup tool displays
+ * // a popup window.
+ * function HelpTool( toolGroup, config ) {
+ *OO.ui.PopupTool.call( this, toolGroup, $.extend( { popup: {
+ *padded: true,
+ *label: 'Help',
+ *head: true
+ *} }, config ) );
+ *this.popup.$body.append( 'pI am helpful!/p' );
+ * };
+ * OO.inheritClass( HelpTool, OO.ui.PopupTool );
+ * HelpTool.static.name = 'help';
+ * HelpTool.static.icon = 'help';
+ * HelpTool.static.title = 'Help';
+ * toolFactory.register( HelpTool );
+ *
+ * For an example of a toolbar that contains a popup tool, see {@link
OO.ui.Toolbar toolbars}. For more information about
+ * toolbars in genreral, please see the [OOjs UI documentation on
MediaWiki][1].
+ *
+ * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Toolbars
*
* @abstract
* @class
--
To view, visit https://gerrit.wikimedia.org/r/211306
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I8d4f7a06ca4c16ad3346c2e9972f16d7aed9bee3
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] ToolGroup: Add description and mark protected methods - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/211293
Change subject: ToolGroup: Add description and mark protected methods
..
ToolGroup: Add description and mark protected methods
Change-Id: I09b034ff2eb4336010074617a707c1c5fd482334
---
M src/ToolGroup.js
1 file changed, 41 insertions(+), 12 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/93/211293/1
diff --git a/src/ToolGroup.js b/src/ToolGroup.js
index eab3cea..de048fc 100644
--- a/src/ToolGroup.js
+++ b/src/ToolGroup.js
@@ -1,11 +1,27 @@
/**
- * Collection of tools.
+ * ToolGroups are collections of {@link OO.ui.Tool tools} that are used in a
{@link OO.ui.Toolbar toolbar}.
+ * The type of toolgroup ({@link OO.ui.ListToolGroup list}, {@link
OO.ui.BarToolGroup bar}, or {@link OO.ui.MenuToolGroup menu})
+ * to which a tool belongs determines how the tool is arranged and displayed
in the toolbar. Toolgroups
+ * themselves are created on demand with a {@link OO.ui.ToolGroupFactory
toolgroup factory}.
*
- * Tools can be specified in the following ways:
+ * Toolgroups can contain individual tools, groups of tools, or all available
tools:
*
- * - A specific tool: `{ name: 'tool-name' }` or `'tool-name'`
- * - All tools in a group: `{ group: 'group-name' }`
- * - All tools: `'*'`
+ * To include an individual tool (or array of individual tools), specify tools
by symbolic name:
+ *
+ * include: [ 'tool-name' ] or [ { name: 'tool-name' }]
+ *
+ * To include a group of tools, specify the group name. (The tool's static
‘group’ config is used to assign the tool to a group.)
+ *
+ * include: [ { group: 'group-name' } ]
+ *
+ * To include all tools that are not yet assigned to a toolgroup, use the
catch-all selector, an asterisk (*):
+ *
+ * include: '*'
+ *
+ * See {@link OO.ui.Toolbar toolbars} for a full example. For more information
about toolbars in general,
+ * please see the [OOjs UI documentation on MediaWiki][1].
+ *
+ * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Toolbars
*
* @abstract
* @class
@@ -15,10 +31,12 @@
* @constructor
* @param {OO.ui.Toolbar} toolbar
* @param {Object} [config] Configuration options
- * @cfg {Array|string} [include=[]] List of tools to include
- * @cfg {Array|string} [exclude=[]] List of tools to exclude
- * @cfg {Array|string} [promote=[]] List of tools to promote to the beginning
- * @cfg {Array|string} [demote=[]] List of tools to demote to the end
+ * @cfg {Array|string} [include=[]] List of tools to include in the toolgroup.
+ * @cfg {Array|string} [exclude=[]] List of tools to exclude from the
toolgroup.
+ * @cfg {Array|string} [promote=[]] List of tools to promote to the beginning
of the toolgroup.
+ * @cfg {Array|string} [demote=[]] List of tools to demote to the end of the
toolgroup.
+ * This setting is particularly useful when tools have been added to the
toolgroup
+ * en masse (e.g., via the catch-all selector).
*/
OO.ui.ToolGroup = function OoUiToolGroup( toolbar, config ) {
// Allow passing positional parameters inside the config object
@@ -95,6 +113,11 @@
/**
* Show acceleration labels in tooltips.
*
+ * Note: The OOjs UI library does not include an accelerator system, but does
contain
+ * a hook for one. To use an accelerator system, subclass the {@link
OO.ui.Toolbar toolbar} and
+ * override the {@link OO.ui.Toolbar#getToolAccelerator getToolAccelerator}
method, which is
+ * meant to return a label that describes the accelerator keys for a given
tool (e.g., 'Ctrl + M').
+ *
* @static
* @inheritable
* @property {boolean}
@@ -141,6 +164,7 @@
/**
* Handle mouse down and key down events.
*
+ * @protected
* @param {jQuery.Event} e Mouse down or key down event
*/
OO.ui.ToolGroup.prototype.onMouseKeyDown = function ( e ) {
@@ -161,6 +185,7 @@
/**
* Handle captured mouse up and key up events.
*
+ * @protected
* @param {Event} e Mouse up or key up event
*/
OO.ui.ToolGroup.prototype.onCapturedMouseKeyUp = function ( e ) {
@@ -174,6 +199,7 @@
/**
* Handle mouse up and key up events.
*
+ * @protected
* @param {jQuery.Event} e Mouse up or key up event
*/
OO.ui.ToolGroup.prototype.onMouseKeyUp = function ( e ) {
@@ -194,6 +220,7 @@
/**
* Handle mouse over and focus events.
*
+ * @protected
* @param {jQuery.Event} e Mouse over or focus event
*/
OO.ui.ToolGroup.prototype.onMouseOverFocus = function ( e ) {
@@ -207,6 +234,7 @@
/**
* Handle mouse out and blur events.
*
+ * @protected
* @param {jQuery.Event} e Mouse out or blur event
*/
OO.ui.ToolGroup.prototype.onMouseOutBlur = function ( e ) {
@@ -246,6 +274,7 @@
* - a tool being added that may be included
* - a tool already included being overridden
*
+ * @protected
* @param {string} name Symbolic name of tool
*/
OO.ui.ToolGroup.prototype.onToolFactoryRegister = function () {
@@ -253,9 +282,9 @@
};
/**
- * Get
[MediaWiki-commits] [Gerrit] PopupToolGroup: Add description and mark protected methods - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/211304
Change subject: PopupToolGroup: Add description and mark protected methods
..
PopupToolGroup: Add description and mark protected methods
Change-Id: I27ee20bdef340fbfcd94ad81944ad60ca7a6f037
---
M src/toolgroups/PopupToolGroup.js
1 file changed, 10 insertions(+), 4 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/04/211304/1
diff --git a/src/toolgroups/PopupToolGroup.js b/src/toolgroups/PopupToolGroup.js
index 0fbdf4f..511a79c 100644
--- a/src/toolgroups/PopupToolGroup.js
+++ b/src/toolgroups/PopupToolGroup.js
@@ -1,5 +1,7 @@
/**
- * Popup list of tools with an icon and optional label.
+ * PopupToolGroup is an abstract base class used by both {@link
OO.ui.MenuToolGroup MenuToolGroup}
+ * and {@link OO.ui.ListToolGroup ListToolGroup} to provide a popup--an
overlaid menu or list of tools with an
+ * optional icon and label. This class can be used for other base classes that
also use this functionality.
*
* @abstract
* @class
@@ -14,7 +16,7 @@
* @constructor
* @param {OO.ui.Toolbar} toolbar
* @param {Object} [config] Configuration options
- * @cfg {string} [header] Text to display at the top of the pop-up
+ * @cfg {string} [header] Text to display at the top of the popup
*/
OO.ui.PopupToolGroup = function OoUiPopupToolGroup( toolbar, config ) {
// Allow passing positional parameters inside the config object
@@ -99,6 +101,7 @@
*
* The event is actually generated from a mouseup/keyup, so it is not a normal
blur event object.
*
+ * @protected
* @param {jQuery.Event} e Mouse up or key up event
*/
OO.ui.PopupToolGroup.prototype.onBlur = function ( e ) {
@@ -125,6 +128,7 @@
/**
* Handle mouse up and key up events.
*
+ * @protected
* @param {jQuery.Event} e Mouse up or key up event
*/
OO.ui.PopupToolGroup.prototype.onHandleMouseKeyUp = function ( e ) {
@@ -139,6 +143,7 @@
/**
* Handle mouse down and key down events.
*
+ * @protected
* @param {jQuery.Event} e Mouse down or key down event
*/
OO.ui.PopupToolGroup.prototype.onHandleMouseKeyDown = function ( e ) {
@@ -152,9 +157,10 @@
};
/**
- * Switch into active mode.
+ * Switch into 'active' mode.
*
- * When active, mouseup events anywhere in the document will trigger
deactivation.
+ * When active, the popup is visible. A mouseup event anywhere in the document
will trigger
+ * deactivation.
*/
OO.ui.PopupToolGroup.prototype.setActive = function ( value ) {
value = !!value;
--
To view, visit https://gerrit.wikimedia.org/r/211304
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I27ee20bdef340fbfcd94ad81944ad60ca7a6f037
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] ToolFactory: Add description - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/211289
Change subject: ToolFactory: Add description
..
ToolFactory: Add description
Change-Id: I436627b48a2a0e3e24384e1826cde9a56d17d57f
---
M src/ToolFactory.js
1 file changed, 7 insertions(+), 1 deletion(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/89/211289/1
diff --git a/src/ToolFactory.js b/src/ToolFactory.js
index aada2e9..822e0ce 100644
--- a/src/ToolFactory.js
+++ b/src/ToolFactory.js
@@ -1,5 +1,11 @@
/**
- * Factory for tools.
+ * A ToolFactory creates tools on demand. All tools ({@link OO.ui.Tool Tools},
{@link OO.ui.PopupTool PopupTools},
+ * and {@link OO.ui.ToolGroupTool ToolGroupTools}) must be registered with a
tool factory. Tools are
+ * registered by their symbolic name. See {@link OO.ui.Toolbar toolbars} for
an example.
+ *
+ * For more information about toolbars in general, please see the [OOjs UI
documentation on MediaWiki][1].
+ *
+ * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Toolbars
*
* @class
* @extends OO.Factory
--
To view, visit https://gerrit.wikimedia.org/r/211289
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I436627b48a2a0e3e24384e1826cde9a56d17d57f
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] ToolGroupFactory: Add description - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/211287
Change subject: ToolGroupFactory: Add description
..
ToolGroupFactory: Add description
Change-Id: I43379a24347fc6fa685b98d901dde6a02e69c1ae
---
M src/ToolGroupFactory.js
1 file changed, 13 insertions(+), 2 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/87/211287/1
diff --git a/src/ToolGroupFactory.js b/src/ToolGroupFactory.js
index 109b86e..98d07ba 100644
--- a/src/ToolGroupFactory.js
+++ b/src/ToolGroupFactory.js
@@ -1,6 +1,17 @@
/**
- * Factory for tool groups.
+ * ToolGroupFactories create {@link OO.ui.ToolGroup toolgroups} on demand. The
toolgroup classes must
+ * specify a symbolic name and be registered with the factory. The following
classes are registered by
+ * default:
*
+ * - {@link OO.ui.BarToolGroup BarToolGroups} (‘bar’)
+ * - {@link OO.ui.MenuToolGroup MenuToolGroups} (‘menu’)
+ * - {@link OO.ui.ListToolGroup ListToolGroups} (‘list’)
+ *
+ * See {@link OO.ui.Toolbar toolbars} for an example.
+ *
+ * For more information about toolbars in general, please see the [OOjs UI
documentation on MediaWiki][1].
+ *
+ * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Toolbars
* @class
* @extends OO.Factory
* @constructor
@@ -25,7 +36,7 @@
/* Static Methods */
/**
- * Get a default set of classes to be registered on construction
+ * Get a default set of classes to be registered on construction.
*
* @return {Function[]} Default classes
*/
--
To view, visit https://gerrit.wikimedia.org/r/211287
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I43379a24347fc6fa685b98d901dde6a02e69c1ae
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] ToolGroupTool: Add description and example - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/211152
Change subject: ToolGroupTool: Add description and example
..
ToolGroupTool: Add description and example
Change-Id: I9f29b5a9fc7f18c19386df86e6021901ba0f1e69
---
M src/tools/ToolGroupTool.js
1 file changed, 35 insertions(+), 6 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/52/211152/1
diff --git a/src/tools/ToolGroupTool.js b/src/tools/ToolGroupTool.js
index b8f70a3..69c2036 100644
--- a/src/tools/ToolGroupTool.js
+++ b/src/tools/ToolGroupTool.js
@@ -1,6 +1,31 @@
/**
- * Tool that has a tool group inside. This is a bad workaround for the lack of
proper hierarchical
- * menus in toolbars (T74159).
+ * A ToolGroupTool is a special sort of tool that can contain other {@link
OO.ui.Tool tools}
+ * and {@link OO.ui.ToolGroup toolgroups}. The ToolGroupTool was specifically
designed to be used
+ * inside a {@link OO.ui.BarToolGroup bar} toolgroup to provide access to
additional tools from
+ * the bar item. Included tools will be displayed in a dropdown {@link
OO.ui.ListToolGroup list}
+ * when the ToolGroupTool is selected.
+ *
+ * // Example: ToolGroupTool with two nested tools, 'setting1' and
'setting2', defined elsewhere.
+ *
+ * function SettingsTool() {
+ * SettingsTool.super.apply( this, arguments );
+ * };
+ * OO.inheritClass( SettingsTool, OO.ui.ToolGroupTool );
+ * SettingsTool.static.name = 'settings';
+ * SettingsTool.static.title = 'Change settings';
+ * SettingsTool.static.groupConfig = {
+ * icon: 'settings',
+ * label: 'ToolGroupTool',
+ * include: [ 'setting1', 'setting2' ]
+ * };
+ * toolFactory.register( SettingsTool );
+ *
+ * For more information, please see the [OOjs UI documentation on
MediaWiki][1].
+ *
+ * Please note that this implementation is subject to change per [T74159] [2].
+ *
+ * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Toolbars#ToolGroupTool
+ * [2]: https://phabricator.wikimedia.org/T74159
*
* @abstract
* @class
@@ -40,7 +65,11 @@
/* Static Properties */
/**
- * Tool group configuration. See OO.ui.Toolbar#setup for the accepted values.
+ * Toolgroup configuration.
+ *
+ * The toolgroup configuration consists of the tools to include, as well as an
icon and label
+ * to use for the bar item. Tools can be included by symbolic name, group, or
with the
+ * wildcard selector. Please see {@link OO.ui.ToolGroup toolgroup} for more
information.
*
* @property {Object.string,Array}
*/
@@ -78,10 +107,10 @@
};
/**
- * Build a OO.ui.ToolGroup from the configuration.
+ * Build a {@link OO.ui.ToolGroup toolgroup} from the specified configuration.
*
- * @param {Object.string,Array} group Tool group configuration. See
OO.ui.Toolbar#setup for the
- * accepted values.
+ * @param {Object.string,Array} group Toolgroup configuration. Please see
{@link OO.ui.ToolGroup toolgroup} for
+ * more information.
* @return {OO.ui.ListToolGroup}
*/
OO.ui.ToolGroupTool.prototype.createGroup = function ( group ) {
--
To view, visit https://gerrit.wikimedia.org/r/211152
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I9f29b5a9fc7f18c19386df86e6021901ba0f1e69
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] BarToolGroup: Add description and example - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/211147
Change subject: BarToolGroup: Add description and example
..
BarToolGroup: Add description and example
Change-Id: I4b22ef828785d344d4c9786f3f1a1b07420b04a2
---
M src/toolgroups/BarToolGroup.js
1 file changed, 88 insertions(+), 1 deletion(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/47/211147/1
diff --git a/src/toolgroups/BarToolGroup.js b/src/toolgroups/BarToolGroup.js
index 038894d..6d6858c 100644
--- a/src/toolgroups/BarToolGroup.js
+++ b/src/toolgroups/BarToolGroup.js
@@ -1,5 +1,92 @@
/**
- * Horizontal bar layout of tools as icon buttons.
+ * BarToolGroups are one of three types of {@link OO.ui.ToolGroup toolgroups}
that are used to
+ * create {@link OO.ui.Toolbar toolbars} (the other types of groups are {@link
OO.ui.MenuToolGroup MenuToolGroup}
+ * and {@link OO.ui.ListToolGroup ListToolGroup}). The {@link OO.ui.Tool
tools} in a BarToolGroup are
+ * displayed by icon in a single row. The title of the tool is displayed when
users move the mouse over
+ * the tool.
+ *
+ * BarToolGroups are created by a {@link OO.ui.ToolGroupFactory tool group
factory} when the toolbar is
+ * set up.
+ *
+ * @example
+ * // Example of a BarToolGroup with two tools
+ * var toolFactory = new OO.ui.ToolFactory();
+ * var toolGroupFactory = new OO.ui.ToolGroupFactory();
+ * var toolbar = new OO.ui.Toolbar( toolFactory, toolGroupFactory );
+ *
+ * // We will be placing status text in this element when tools are used
+ * var $area = $( 'p' ).text( 'Example of a BarToolGroup with two
tools.' );
+ *
+ * // Define the tools that we're going to place in our toolbar
+ *
+ * // Create a class inheriting from OO.ui.Tool
+ * function PictureTool() {
+ * PictureTool.super.apply( this, arguments );
+ * }
+ * OO.inheritClass( PictureTool, OO.ui.Tool );
+ * // Each tool must have a 'name' (used as an internal identifier, see
later) and at least one
+ * // of 'icon' and 'title' (displayed icon and text).
+ * PictureTool.static.name = 'picture';
+ * PictureTool.static.icon = 'picture';
+ * PictureTool.static.title = 'Insert picture';
+ * // Defines the action that will happen when this tool is selected
(clicked).
+ * PictureTool.prototype.onSelect = function () {
+ * $area.text( 'Picture tool clicked!' );
+ * // Never display this tool as active (selected).
+ * this.setActive( false );
+ * };
+ * // Make this tool available in our toolFactory and thus our toolbar
+ * toolFactory.register( PictureTool );
+ *
+ * // This is a PopupTool. Rather than having a custom 'onSelect' action,
it will display a
+ * // little popup window (a PopupWidget).
+ * function HelpTool( toolGroup, config ) {
+ * OO.ui.PopupTool.call( this, toolGroup, $.extend( { popup: {
+ * padded: true,
+ * label: 'Help',
+ * head: true
+ * } }, config ) );
+ * this.popup.$body.append( 'pI am helpful!/p' );
+ * }
+ * OO.inheritClass( HelpTool, OO.ui.PopupTool );
+ * HelpTool.static.name = 'help';
+ * HelpTool.static.icon = 'help';
+ * HelpTool.static.title = 'Help';
+ * toolFactory.register( HelpTool );
+ *
+ * // Finally define which tools and in what order appear in the toolbar.
Each tool may only be
+ * // used once (but not all defined tools must be used).
+ * toolbar.setup( [
+ * {
+ * // 'bar' tool groups display tools by icon only
+ * type: 'bar',
+ * include: [ 'picture', 'help' ]
+ * }
+ * ] );
+ *
+ * // Create some UI around the toolbar and place it in the document
+ * var frame = new OO.ui.PanelLayout( {
+ * expanded: false,
+ * framed: true
+ * } );
+ * var contentFrame = new OO.ui.PanelLayout( {
+ * expanded: false,
+ * padded: true
+ * } );
+ * frame.$element.append(
+ * toolbar.$element,
+ * contentFrame.$element.append( $area )
+ * );
+ * $( 'body' ).append( frame.$element );
+ *
+ * // Here is where the toolbar is actually built. This must be done after
inserting it into the
+ * // document.
+ * toolbar.initialize();
+ *
+ * For more information about how to add tools to a bar tool group, please see
{@link OO.ui.ToolGroup toolgroup}.
+ * For more information about toolbars in general, please see the [OOjs UI
documentation on MediaWiki][1].
+ *
+ * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Toolbars
*
* @class
* @extends OO.ui.ToolGroup
--
To view, visit https://gerrit.wikimedia.org/r/211147
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I4b22ef828785d344d4c9786f3f1a1b07420b04a2
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
[MediaWiki-commits] [Gerrit] MenuToolGroup: Add description, example and mark private method - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/211143
Change subject: MenuToolGroup: Add description, example and mark private method
..
MenuToolGroup: Add description, example and mark private method
Change-Id: I12c0d7506b9798fafef8684b4b9c54d2e5d5d716
---
M src/toolgroups/MenuToolGroup.js
1 file changed, 100 insertions(+), 1 deletion(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/43/211143/1
diff --git a/src/toolgroups/MenuToolGroup.js b/src/toolgroups/MenuToolGroup.js
index aef69a9..7323c94 100644
--- a/src/toolgroups/MenuToolGroup.js
+++ b/src/toolgroups/MenuToolGroup.js
@@ -1,5 +1,102 @@
/**
- * Drop down menu layout of tools as selectable menu items.
+ * MenuToolGroups are one of three types of {@link OO.ui.ToolGroup toolgroups}
that are used to
+ * create {@link OO.ui.Toolbar toolbars} (the other types of groups are {@link
OO.ui.BarToolGroup BarToolGroup}
+ * and {@link OO.ui.ListToolGroup ListToolGroup}). MenuToolGroups contain
selectable {@link OO.ui.Tool tools},
+ * which are displayed by label in a dropdown menu. The tool's title is used
as the label text, and the
+ * menu label is updated to reflect which tool or tools are currently
selected. If no tools are selected,
+ * 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.
+ *
+ * @example
+ * // Example of a MenuToolGroup
+ * var toolFactory = new OO.ui.ToolFactory();
+ * var toolGroupFactory = new OO.ui.ToolGroupFactory();
+ * var toolbar = new OO.ui.Toolbar( toolFactory, toolGroupFactory );
+ *
+ * // We will be placing status text in this element when tools are used
+ * var $area = $( 'p' ).text( 'An example of a MenuToolGroup. Select a
tool from the dropdown menu.' );
+ *
+ * // Define the tools that we're going to place in our toolbar
+ *
+ * function SettingsTool() {
+ * SettingsTool.super.apply( this, arguments );
+ * this.reallyActive = false;
+ * }
+ * OO.inheritClass( SettingsTool, OO.ui.Tool );
+ * SettingsTool.static.name = 'settings';
+ * SettingsTool.static.icon = 'settings';
+ * SettingsTool.static.title = 'Change settings';
+ * SettingsTool.prototype.onSelect = function () {
+ * $area.text( 'Settings tool clicked!' );
+ * // Toggle the active state on each click
+ * this.reallyActive = !this.reallyActive;
+ * this.setActive( this.reallyActive );
+ * // To update the menu label
+ * this.toolbar.emit( 'updateState' );
+ * };
+ * SettingsTool.prototype.onUpdateState = function () {
+ * };
+ * toolFactory.register( SettingsTool );
+ *
+ * function StuffTool() {
+ * StuffTool.super.apply( this, arguments );
+ * this.reallyActive = false;
+ * }
+ * OO.inheritClass( StuffTool, OO.ui.Tool );
+ * StuffTool.static.name = 'stuff';
+ * StuffTool.static.icon = 'ellipsis';
+ * StuffTool.static.title = 'More stuff';
+ * StuffTool.prototype.onSelect = function () {
+ * $area.text( 'More stuff tool clicked!' );
+ * // Toggle the active state on each click
+ * this.reallyActive = !this.reallyActive;
+ * this.setActive( this.reallyActive );
+ * // To update the menu label
+ * this.toolbar.emit( 'updateState' );
+ * };
+ * StuffTool.prototype.onUpdateState = function () {
+ * };
+ * toolFactory.register( StuffTool );
+ *
+ * // Finally define which tools and in what order appear in the toolbar.
Each tool may only be
+ * // used once (but not all defined tools must be used).
+ * toolbar.setup( [
+ * {
+ * type: 'menu',
+ * header: 'This is the (optional) header',
+ * title: 'This is the (optional) title',
+ * indicator: 'down',
+ * include: [ 'settings', 'stuff' ]
+ * }
+ * ] );
+ *
+ * // Create some UI around the toolbar and place it in the document
+ * var frame = new OO.ui.PanelLayout( {
+ * expanded: false,
+ * framed: true
+ * } );
+ * var contentFrame = new OO.ui.PanelLayout( {
+ * expanded: false,
+ * padded: true
+ * } );
+ * frame.$element.append(
+ * toolbar.$element,
+ * contentFrame.$element.append( $area )
+ * );
+ * $( 'body' ).append( frame.$element );
+ *
+ * // Here is where the toolbar is actually built. This must be done after
inserting it into the
+ * // document.
+ * toolbar.initialize();
+ * toolbar.emit( 'updateState' );
+ *
+ * For more information about how to add tools to
[MediaWiki-commits] [Gerrit] Tool: Add description - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/210830
Change subject: Tool: Add description
..
Tool: Add description
Change-Id: I84ef5460cc022ecfb0003057c1719fd51a236562
---
M src/Tool.js
1 file changed, 61 insertions(+), 24 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/30/210830/1
diff --git a/src/Tool.js b/src/Tool.js
index 603c063..f763e11 100644
--- a/src/Tool.js
+++ b/src/Tool.js
@@ -1,5 +1,15 @@
/**
- * Generic toolbar tool.
+ * Tools, together with {@link OO.ui.ToolGroup toolgroups}, constitute {@link
OO.ui.Toolbar toolbars}.
+ * Each tool is configured with a static name, title, and icon and is
customized with the command to carry
+ * 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.
+ *
+ * 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.
+ *
+ * For more information, please see the [OOjs UI documentation on
MediaWiki][1].
+ * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Toolbars
*
* @abstract
* @class
@@ -11,7 +21,16 @@
* @constructor
* @param {OO.ui.ToolGroup} toolGroup
* @param {Object} [config] Configuration options
- * @cfg {string|Function} [title] Title text or a function that returns text
+ * @cfg {string|Function} [title] Title text or a function that returns text.
If this config is omitted, the value of
+ * the {@link #static-title static title} property is used.
+ *
+ * The title is used in different ways depending on the type of toolgroup
that contains the tool. The
+ * title is used as a tooltip if the tool is part of a {@link
OO.ui.BarToolGroup bar} toolgroup, or as the label text if the tool is
+ * part of a {@link OO.ui.ListToolGroup list} or {@link OO.ui.MenuToolGroup
menu} toolgroup.
+ *
+ * For bar toolgroups, a description of the accelerator key is appended to
the title if an accelerator key
+ * is associated with an action by the same name as the tool and accelerator
functionality has been added to the application.
+ * To add accelerator key functionality, you must subclass OO.ui.Toolbar and
override the {@link OO.ui.Toolbar#getToolAccelerator getToolAccelerator} method.
*/
OO.ui.Tool = function OoUiTool( toolGroup, config ) {
// Allow passing positional parameters inside the config object
@@ -75,11 +94,6 @@
OO.mixinClass( OO.ui.Tool, OO.ui.FlaggedElement );
OO.mixinClass( OO.ui.Tool, OO.ui.TabIndexedElement );
-/* Events */
-
-/**
- * @event select
- */
/* Static Properties */
@@ -92,6 +106,9 @@
/**
* Symbolic name of tool.
*
+ * The symbolic name is used internally to register the tool with a {@link
OO.ui.ToolFactory ToolFactory}. It can
+ * also be used when adding tools to toolgroups.
+ *
* @abstract
* @static
* @inheritable
@@ -100,7 +117,10 @@
OO.ui.Tool.static.name = '';
/**
- * Tool group.
+ * Symbolic name of the group.
+ *
+ * The group name is used to associate tools with each other so that they can
be selected later by
+ * a {@link OO.ui.ToolGroup toolgroup}.
*
* @abstract
* @static
@@ -110,22 +130,17 @@
OO.ui.Tool.static.group = '';
/**
- * Tool title.
- *
- * Title is used as a tooltip when the tool is part of a bar tool group, or a
label when the tool
- * is part of a list or menu tool group. If a trigger is associated with an
action by the same name
- * as the tool, a description of its keyboard shortcut for the appropriate
platform will be
- * appended to the title if the tool is part of a bar tool group.
+ * Tool title text or a function that returns title text. The value of the
static property is overridden if the #title config option is used.
*
* @abstract
* @static
* @inheritable
- * @property {string|Function} Title text or a function that returns text
+ * @property {string|Function}
*/
OO.ui.Tool.static.title = '';
/**
- * Whether this tool should be displayed with both title and label when used
in a bar tool group.
+ * Display both icon and label when the tool is used in a {@link
OO.ui.BarToolGroup bar} toolgroup.
* Normally only the icon is displayed, or only the label if no icon is given.
*
* @static
@@ -135,7 +150,10 @@
OO.ui.Tool.static.displayBothIconAndLabel = false;
/**
- * Tool can be automatically added to catch-all groups.
+ * Add tool to catch-all groups automatically.
+ *
+ * A catch-all group, which contains all tools that do not currently belong to
a toolgroup,
+ * can be included in a toolgroup using the wildcard selector, an asterisk (*).
*
* @static
* @inheritable
@@ -144,7 +162,11 @@
OO.ui.Tool.static.autoAddToCatchall = true;
/**
- * Tool can be automatically
[MediaWiki-commits] [Gerrit] CardLayout: Fix typo - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/208700
Change subject: CardLayout: Fix typo
..
CardLayout: Fix typo
Change-Id: Ifdda6c301997abb38ac3044b911db5e9bca89b2f
---
M src/layouts/CardLayout.js
1 file changed, 2 insertions(+), 2 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/00/208700/1
diff --git a/src/layouts/CardLayout.js b/src/layouts/CardLayout.js
index 16f2464..353aedc 100644
--- a/src/layouts/CardLayout.js
+++ b/src/layouts/CardLayout.js
@@ -88,7 +88,7 @@
/**
* Set or unset the tab item.
*
- * Specify an {@link OO.ui.TabOptionWidget tab option} to set it,
+ * Specify a {@link OO.ui.TabOptionWidget tab option} to set it,
* or `null` to clear the tab item. To customize the tab item itself (e.g., to
set a label or tab
* level), use #setupTabItem instead of this method.
*
@@ -107,7 +107,7 @@
* Set up the tab item.
*
* Use this method to customize the tab item (e.g., to add a label or tab
level). To set or unset
- * the tab item itself (with an {@link OO.ui.TabOptionWidget tab option} or
`null`), use
+ * the tab item itself (with a {@link OO.ui.TabOptionWidget tab option} or
`null`), use
* the #setTabItem method instead.
*
* @param {OO.ui.TabOptionWidget} tabItem Tab option widget to set up
--
To view, visit https://gerrit.wikimedia.org/r/208700
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: Ifdda6c301997abb38ac3044b911db5e9bca89b2f
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] PopupButtonWidget: Update align config in example - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/208296
Change subject: PopupButtonWidget: Update align config in example
..
PopupButtonWidget: Update align config in example
Change-Id: I8dd8446497b13eb885a7d3bd1484a2058bc179cb
---
M src/widgets/PopupButtonWidget.js
1 file changed, 1 insertion(+), 1 deletion(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/96/208296/1
diff --git a/src/widgets/PopupButtonWidget.js b/src/widgets/PopupButtonWidget.js
index 4300239..5643b77 100644
--- a/src/widgets/PopupButtonWidget.js
+++ b/src/widgets/PopupButtonWidget.js
@@ -10,7 +10,7 @@
* popup: {
* $content: $( 'pAdditional options here./p' ),
* padded: true,
- * align: 'left'
+ * align: 'force-left'
* }
* } );
* // Append the button to the DOM.
--
To view, visit https://gerrit.wikimedia.org/r/208296
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I8dd8446497b13eb885a7d3bd1484a2058bc179cb
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] MenuLayout: Add example - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/204326
Change subject: MenuLayout: Add example
..
MenuLayout: Add example
Change-Id: I5f4581a350ad75fad0ff4a2fad7feaa79c075658
---
M src/layouts/MenuLayout.js
1 file changed, 39 insertions(+), 3 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/26/204326/1
diff --git a/src/layouts/MenuLayout.js b/src/layouts/MenuLayout.js
index d5bce45..656cb8e 100644
--- a/src/layouts/MenuLayout.js
+++ b/src/layouts/MenuLayout.js
@@ -1,8 +1,44 @@
/**
- * Layout with a content and menu area.
+ * MenuLayouts combine a menu and a content {@link OO.ui.PanelLayout panel}.
The menu is positioned relative to the content (after, before, top, or bottom)
+ * and its size is customized with the #menuSize config. The content area will
fill all remaining space.
*
- * The menu area can be positioned at the top, after, bottom or before. The
content area will fill
- * all remaining space.
+ * @example
+ * var menuLayout = new OO.ui.MenuLayout( {
+ * position: 'top'
+ * } ),
+ * menuPanel = new OO.ui.PanelLayout( { padded: true, expanded: true,
scrollable: true } ),
+ * contentPanel = new OO.ui.PanelLayout( { padded: true, expanded:
true, scrollable: true } ),
+ * select = new OO.ui.SelectWidget( {
+ * items: [
+ * new OO.ui.OptionWidget( {
+ * data: 'before',
+ * label: 'Before',
+ * } ),
+ * new OO.ui.OptionWidget( {
+ * data: 'after',
+ * label: 'After',
+ * } ),
+ * new OO.ui.OptionWidget( {
+ * data: 'top',
+ * label: 'Top',
+ * } ),
+ * new OO.ui.OptionWidget( {
+ * data: 'bottom',
+ * label: 'Bottom',
+ * } )
+ * ]
+ * } ).on( 'select', function ( item ) {
+ *menuLayout.setMenuPosition( item.getData() );
+ * } );
+ *
+ * menuLayout.$menu.append(
+ * menuPanel.$element.append( 'bMenu panel/b', select.$element )
+ * );
+ * menuLayout.$content.append(
+ * contentPanel.$element.append( 'bContent panel/b', 'pNote that
the menu is positioned relative to the content panel: top, bottom, after,
before./p')
+ * );
+ * $( 'body' ).append( menuLayout.$element );
+ *
*
* @class
* @extends OO.ui.Layout
--
To view, visit https://gerrit.wikimedia.org/r/204326
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I5f4581a350ad75fad0ff4a2fad7feaa79c075658
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] Error: Add description - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/201790
Change subject: Error: Add description
..
Error: Add description
Change-Id: I45f5c3f346c069b8735cb6efeff1c7c68ec48efd
---
M src/Error.js
1 file changed, 28 insertions(+), 5 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/90/201790/1
diff --git a/src/Error.js b/src/Error.js
index fef26cf..af87b72 100644
--- a/src/Error.js
+++ b/src/Error.js
@@ -1,11 +1,30 @@
/**
+ * Errors contain a required message (either a string or jQuery selection)
that is used to describe what went wrong
+ * in a {@link OO.ui.Process process}. The error's #recoverable and #warning
configurations are used to customize the
+ * appearance and functionality of the error interface.
+ *
+ * The basic error interface contains a formatted error message as well as two
buttons: 'Dismiss' and 'Try again' (i.e., the error
+ * is 'recoverable' by default). If the error is not recoverable, the 'Try
again' button will not be rendered and the widget
+ * that initiated the failed process will be disabled.
+ *
+ * If the error is a warning, the error interface will include a 'Dismiss' and
a 'Continue' button, which will try the
+ * process again.
+ *
+ * For an example of error interfaces, please see the [OOjs UI documentation
on MediaWiki][1].
+ *
+ * [1]:
https://www.mediawiki.org/wiki/OOjs_UI/Windows/Process_Dialogs#Processes_and_errors
+ *
* @class
*
* @constructor
* @param {string|jQuery} message Description of error
* @param {Object} [config] Configuration options
- * @cfg {boolean} [recoverable=true] Error is recoverable
- * @cfg {boolean} [warning=false] Whether this error is a warning or not.
+ * @cfg {boolean} [recoverable=true] Error is recoverable.
+ * By default, errors are recoverable, and users can try the process again.
+ * @cfg {boolean} [warning=false] Error is a warning.
+ * If the error is a warning, the error interface will include a
+ * 'Dismiss' and a 'Continue' button. It is the responsibility of the
developer to ensure that the warning
+ * is not triggered a second time if the user chooses to continue.
*/
OO.ui.Error = function OoUiError( message, config ) {
// Allow passing positional parameters inside the config object
@@ -30,7 +49,9 @@
/* Methods */
/**
- * Check if error can be recovered from.
+ * Check if the error is recoverable.
+ *
+ * If the error is recoverable, users are able to try the process again.
*
* @return {boolean} Error is recoverable
*/
@@ -39,7 +60,9 @@
};
/**
- * Check if the error is a warning
+ * Check if the error is a warning.
+ *
+ * If the error is a warning, the error interface will include a 'Dismiss' and
a 'Continue' button.
*
* @return {boolean} Error is warning
*/
@@ -59,7 +82,7 @@
};
/**
- * Get error message as text.
+ * Get the error message text.
*
* @return {string} Error message
*/
--
To view, visit https://gerrit.wikimedia.org/r/201790
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I45f5c3f346c069b8735cb6efeff1c7c68ec48efd
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] Process: Add description - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/201393
Change subject: Process: Add description
..
Process: Add description
Change-Id: I30d1d38cf1c85583df425714e8197dd0632db816
---
M src/Process.js
1 file changed, 28 insertions(+), 20 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/93/201393/1
diff --git a/src/Process.js b/src/Process.js
index e00e557..649ffb9 100644
--- a/src/Process.js
+++ b/src/Process.js
@@ -1,17 +1,25 @@
/**
- * A list of functions, called in sequence.
+ * A Process is a list of steps that are called in sequence. The step can be a
number, a jQuery promise,
+ * or a function:
*
- * If a function added to a process returns boolean false the process will
stop; if it returns an
- * object with a `promise` method the process will use the promise to either
continue to the next
- * step when the promise is resolved or stop when the promise is rejected.
+ * - **number**: the process will wait for the specified number of
milliseconds before proceeding.
+ * - **promise**: the process will continue to the next step when the promise
is successfully resolved
+ * or stop if the promise is rejected.
+ * - **function**: the process will execute the function. The process will
stop if the function returns
+ * either a boolean `false` or a promise that is rejected; if the function
returns a number, the process
+ * will wait for that number of milliseconds before proceeding.
+ *
+ * If the process fails, an {@link OO.ui.Error error} is generated. Depending
on how the error is
+ * configured, users can dismiss the error and try the process again, or not.
If a process is stopped,
+ * its remaining steps will not be performed.
*
* @class
*
* @constructor
- * @param {number|jQuery.Promise|Function} step Time to wait, promise to wait
for or function to
- * call, see #createStep for more information
- * @param {Object} [context=null] Context to call the step function in,
ignored if step is a number
- * or a promise
+ * @param {number|jQuery.Promise|Function} step Number of miliseconds to wait
before proceeding, promise
+ * that must be resolved before proceeding, or a function to execute. See
#createStep for more information. see #createStep for more information
+ * @param {Object} [context=null] Execution context of the function. The
context is ignored if the step is
+ * a number or promise.
* @return {Object} Step object, with `callback` and `context` properties
*/
OO.ui.Process = function ( step, context ) {
@@ -33,9 +41,9 @@
/**
* Start the process.
*
- * @return {jQuery.Promise} Promise that is resolved when all steps have
completed or rejected when
- * any of the steps return boolean false or a promise which gets rejected;
upon stopping the
- * process, the remaining steps will not be taken
+ * @return {jQuery.Promise} Promise that is resolved when all steps have
successfully completed.
+ * If any of the steps return a promise that is rejected or a boolean false,
this promise is rejected
+ * and any remaining steps are not performed.
*/
OO.ui.Process.prototype.execute = function () {
var i, len, promise;
@@ -103,16 +111,16 @@
* @private
* @param {number|jQuery.Promise|Function} step
*
- * - Number of milliseconds to wait; or
- * - Promise to wait to be resolved; or
+ * - Number of milliseconds to wait before proceeding
+ * - Promise that must be resolved before proceeding
* - Function to execute
- * - If it returns boolean false the process will stop
- * - If it returns an object with a `promise` method the process will use
the promise to either
- * continue to the next step when the promise is resolved or stop when the
promise is rejected
- * - If it returns a number, the process will wait for that number of
milliseconds before
- * proceeding
- * @param {Object} [context=null] Context to call the step function in,
ignored if step is a number
- * or a promise
+ * - If the function returns a boolean false the process will stop
+ * - If the function returns a promise, the process will continue to the next
+ * step when the promise is resolved or stop if the promise is rejected
+ * - If the function returns a number, the process will wait for that number
of
+ * milliseconds before proceeding
+ * @param {Object} [context=null] Execution context of the function. The
context is
+ * ignored if the step is a number or promise.
* @return {Object} Step object, with `callback` and `context` properties
*/
OO.ui.Process.prototype.createStep = function ( step, context ) {
--
To view, visit https://gerrit.wikimedia.org/r/201393
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I30d1d38cf1c85583df425714e8197dd0632db816
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger
[MediaWiki-commits] [Gerrit] OutlineOption: Add description - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/200597
Change subject: OutlineOption: Add description
..
OutlineOption: Add description
Change-Id: Ie0f938f6aac9f09976a26daa196084062258769d
---
M src/widgets/OutlineOptionWidget.js
1 file changed, 10 insertions(+), 6 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/97/200597/1
diff --git a/src/widgets/OutlineOptionWidget.js
b/src/widgets/OutlineOptionWidget.js
index aac36c0..d792fee 100644
--- a/src/widgets/OutlineOptionWidget.js
+++ b/src/widgets/OutlineOptionWidget.js
@@ -1,5 +1,9 @@
/**
- * Items for an OO.ui.OutlineSelectWidget.
+ * OutlineOptionWidget is an item in an {@link OO.ui.OutlineSelectWidget
OutlineSelectWidget}.
+ *
+ * Currently, this class is only used by {@link OO.ui.BookletLayout booklet
layouts}, which contain
+ * {@link OO.ui.PageLayout page layouts}. See {@link OO.ui.BookletLayout
BookletLayout}
+ * for an example.
*
* @class
* @extends OO.ui.DecoratedOptionWidget
@@ -7,7 +11,7 @@
* @constructor
* @param {Object} [config] Configuration options
* @cfg {number} [level] Indentation level
- * @cfg {boolean} [movable] Allow modification from outline controls
+ * @cfg {boolean} [movable] Allow modification from {@link
OO.ui.OutlineControlsWidget outline controls}.
*/
OO.ui.OutlineOptionWidget = function OoUiOutlineOptionWidget( config ) {
// Configuration initialization
@@ -45,7 +49,7 @@
/**
* Check if item is movable.
*
- * Movability is used by outline controls.
+ * Movability is used by {@link OO.ui.OutlineControlsWidget outline controls}.
*
* @return {boolean} Item is movable
*/
@@ -56,7 +60,7 @@
/**
* Check if item is removable.
*
- * Removability is used by outline controls.
+ * Removability is used by {@link OO.ui.OutlineControlsWidget outline
controls}.
*
* @return {boolean} Item is removable
*/
@@ -76,7 +80,7 @@
/**
* Set movability.
*
- * Movability is used by outline controls.
+ * Movability is used by {@link OO.ui.OutlineControlsWidget outline controls}.
*
* @param {boolean} movable Item is movable
* @chainable
@@ -90,7 +94,7 @@
/**
* Set removability.
*
- * Removability is used by outline controls.
+ * Removability is used by {@link OO.ui.OutlineControlsWidget outline
controls}.
*
* @param {boolean} movable Item is removable
* @chainable
--
To view, visit https://gerrit.wikimedia.org/r/200597
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: Ie0f938f6aac9f09976a26daa196084062258769d
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] ActionFieldLayout: Add description and example - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/200626
Change subject: ActionFieldLayout: Add description and example
..
ActionFieldLayout: Add description and example
Change-Id: I09427cbcc8f61746d1b8ee196f58c0fcae3d1517
---
M src/layouts/ActionFieldLayout.js
1 file changed, 40 insertions(+), 3 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/26/200626/1
diff --git a/src/layouts/ActionFieldLayout.js b/src/layouts/ActionFieldLayout.js
index 3801755..59640ed 100644
--- a/src/layouts/ActionFieldLayout.js
+++ b/src/layouts/ActionFieldLayout.js
@@ -1,5 +1,41 @@
/**
- * Layout made of a field, a button, and an optional label.
+ * ActionFieldLayouts are used with OO.ui.FieldsetLayout. The layout consists
of a field-widget, a button,
+ * and an optional label and/or help text. The field-widget (e.g., a {@link
OO.ui.TextInputWidget TextInputWidget}),
+ * is required and is specified before any optional configuration settings.
+ *
+ * Labels can be aligned in one of four ways:
+ *
+ * - **left**: The label is placed before the field-widget and aligned with
the left margin.
+ * A left-alignment is used for forms with many fields.
+ * - **right**: The label is placed before the field-widget and aligned to the
right margin.
+ * A right-alignment is used for long but familiar forms which users tab
through,
+ * verifying the current field with a quick glance at the label.
+ * - **top**: The label is placed above the field-widget. A top-alignment is
used for brief forms
+ * that users fill out from top to bottom.
+ * - **inline**: The label is placed after the field-widget and aligned to the
left.
+ * An inline-alignment is best used with checkboxes or radio buttons.
+ *
+ * Help text is accessed via a help icon that appears in the upper right
corner of the rendered field layout when help
+ * text is specified.
+ *
+ * @example
+ * // Example of an ActionFieldLayout
+ * var actionFieldLayout = new OO.ui.ActionFieldLayout(
+ * new OO.ui.TextInputWidget( {
+ * placeholder: 'Field widget'
+ * } ),
+ * new OO.ui.ButtonWidget( {
+ * label: 'Button'
+ * } ),
+ * {
+ * label: 'An ActionFieldLayout. This label is aligned top',
+ * align: 'top',
+ * help: 'This is help text'
+ * }
+ * );
+ *
+ * $( 'body' ).append( actionFieldLayout.$element );
+ *
*
* @class
* @extends OO.ui.FieldLayout
@@ -8,8 +44,9 @@
* @param {OO.ui.Widget} fieldWidget Field widget
* @param {OO.ui.ButtonWidget} buttonWidget Button widget
* @param {Object} [config] Configuration options
- * @cfg {string} [align='left'] Alignment mode, either 'left', 'right', 'top'
or 'inline'
- * @cfg {string} [help] Explanatory text shown as a '?' icon.
+ * @cfg {string} [align='left'] Alignment of the label: 'left', 'right', 'top'
or 'inline'
+ * @cfg {string} [help] Help text. When help text is specified, a help icon
will appear in the
+ * upper-right corner of the rendered field.
*/
OO.ui.ActionFieldLayout = function OoUiActionFieldLayout( fieldWidget,
buttonWidget, config ) {
// Allow passing positional parameters inside the config object
--
To view, visit https://gerrit.wikimedia.org/r/200626
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I09427cbcc8f61746d1b8ee196f58c0fcae3d1517
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] PageLayout: Add description - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/200198
Change subject: PageLayout: Add description
..
PageLayout: Add description
Change-Id: I4500d7315b067c96f274192bc033633b7c52c923
---
M src/layouts/PageLayout.js
1 file changed, 34 insertions(+), 14 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/98/200198/1
diff --git a/src/layouts/PageLayout.js b/src/layouts/PageLayout.js
index 111fa1e..2e40567 100644
--- a/src/layouts/PageLayout.js
+++ b/src/layouts/PageLayout.js
@@ -1,5 +1,11 @@
/**
- * Page within an booklet layout.
+ * PageLayouts are used within {@link OO.ui.BookletLayout booklet layouts} to
create pages that users can select and display
+ * from the booklet's optional {@link OO.ui.OutlineSelectWidget outline}
navigation. Pages are usually not instantiated directly,
+ * rather extended to include the required content and functionality.
+ *
+ * Each page must have a unique symbolic name, which is passed to the
constructor. In addition, the page’s outline
+ * item is customized (with a label, outline level, etc.) using the
#setupOutlineItem method. See
+ * {@link OO.ui.BookletLayout BookletLayout} for an example.
*
* @class
* @extends OO.ui.PanelLayout
@@ -37,6 +43,9 @@
/* Events */
/**
+ * An 'active' event is emitted when the page becomes active. Pages become
active when they are
+ * shown in a booklet layout that is configured to display only one page at a
time.
+ *
* @event active
* @param {boolean} active Page is active
*/
@@ -44,7 +53,7 @@
/* Methods */
/**
- * Get page name.
+ * Get the symbolic name of the page.
*
* @return {string} Symbolic name of page
*/
@@ -55,6 +64,9 @@
/**
* Check if page is active.
*
+ * Pages become active when they are shown in a {@link OO.ui.BookletLayout
booklet layout} that is configured to display
+ * only one page at a time. Additional CSS is applied to the page's outline
item to reflect the active state.
+ *
* @return {boolean} Page is active
*/
OO.ui.PageLayout.prototype.isActive = function () {
@@ -64,21 +76,23 @@
/**
* Get outline item.
*
- * @return {OO.ui.OutlineOptionWidget|null} Outline item widget
+ * The outline item allows users to access the page from the booklet’s outline
+ * navigation. The outline item itself can be customized (with a label, level,
etc.) using the #setupOutlineItem method.
+ *
+ * @return {OO.ui.OutlineOptionWidget|null} Outline option widget
*/
OO.ui.PageLayout.prototype.getOutlineItem = function () {
return this.outlineItem;
};
/**
- * Set outline item.
+ * Set or unset the outline item.
*
- * @localdoc Subclasses should override #setupOutlineItem instead of this
method to adjust the
- * outline item as desired; this method is called for setting (with an
object) and unsetting
- * (with null) and overriding methods would have to check the value of
`outlineItem` to avoid
- * operating on null instead of an OO.ui.OutlineOptionWidget object.
+ * Specify an {@link OO.ui.OutlineOptionWidget outline option} to set it,
+ * or `null` to clear the outline item. To customize the outline item itself
(e.g., to set a label or outline
+ * level), use #setupOutlineItem instead of this method.
*
- * @param {OO.ui.OutlineOptionWidget|null} outlineItem Outline item widget,
null to clear
+ * @param {OO.ui.OutlineOptionWidget|null} outlineItem Outline option widget,
null to clear
* @chainable
*/
OO.ui.PageLayout.prototype.setOutlineItem = function ( outlineItem ) {
@@ -90,11 +104,13 @@
};
/**
- * Setup outline item.
+ * Set up the outline item.
*
- * @localdoc Subclasses should override this method to adjust the outline item
as desired.
+ * Use this method to customize the outline item (e.g., to add a label or
outline level). To set or unset
+ * the outline item itself (with an {@link OO.ui.OutlineOptionWidget outline
option} or `null`), use
+ * the #setOutlineItem method instead.
*
- * @param {OO.ui.OutlineOptionWidget} outlineItem Outline item widget to setup
+ * @param {OO.ui.OutlineOptionWidget} outlineItem Outline option widget to set
up
* @chainable
*/
OO.ui.PageLayout.prototype.setupOutlineItem = function () {
@@ -102,9 +118,13 @@
};
/**
- * Set page active state.
+ * Set the page to its 'active' state.
*
- * @param {boolean} Page is active
+ * Pages become active when they are shown in a booklet layout that is
configured to display only one page at a time. Additional
+ * CSS is applied to the outline item to reflect the page's active state.
Outside of the booklet
+ * context, setting the active state on a page does nothing.
+ *
+ * @param {boolean} value Page is active
* @fires active
*/
OO.ui.PageLayout.prototype.setActive = function ( active ) {
--
To view, visit https://gerrit.wikimedia.org/r/200198
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType:
[MediaWiki-commits] [Gerrit] StackLayout: Add description and example - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/200224
Change subject: StackLayout: Add description and example
..
StackLayout: Add description and example
Change-Id: I87e168d5cf60a83927dd11faa539f75567791bd9
---
M src/layouts/StackLayout.js
1 file changed, 46 insertions(+), 20 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/24/200224/1
diff --git a/src/layouts/StackLayout.js b/src/layouts/StackLayout.js
index 8b0f580..58f35d3 100644
--- a/src/layouts/StackLayout.js
+++ b/src/layouts/StackLayout.js
@@ -1,5 +1,26 @@
/**
- * Layout containing a series of mutually exclusive pages.
+ * StackLayouts contain a series of {@link OO.ui.PanelLayout panel layouts}.
By default, only one panel is displayed
+ * at a time, though the stack layout can also be configured to show all
contained panels, one after another,
+ * by setting the #continuous option to 'true'.
+ *
+ * @example
+ * // A stack layout with two panels, configured to be displayed
continously
+ * var myStack = new OO.ui.StackLayout( {
+ * items: [
+ * new OO.ui.PanelLayout( {
+ * $content: $( 'pPanel One/p' ),
+ * padded: true,
+ * framed: true
+ * } ),
+ * new OO.ui.PanelLayout( {
+ * $content: $( 'pPanel Two/p' ),
+ * padded: true,
+ * framed: true
+ * } )
+ * ],
+ * continuous: true
+ * } );
+ * $( 'body' ).append( myStack.$element );
*
* @class
* @extends OO.ui.PanelLayout
@@ -7,8 +28,8 @@
*
* @constructor
* @param {Object} [config] Configuration options
- * @cfg {boolean} [continuous=false] Show all pages, one after another
- * @cfg {OO.ui.Layout[]} [items] Layouts to add
+ * @cfg {boolean} [continuous=false] Show all panels, one after another. By
default, only one panel is displayed at a time.
+ * @cfg {OO.ui.Layout[]} [items] Panel layouts to add to the stack layout.
*/
OO.ui.StackLayout = function OoUiStackLayout( config ) {
// Configuration initialization
@@ -42,14 +63,17 @@
/* Events */
/**
+ * A 'set' event is emitted when panels are {@link #addItems added}, {@link
#removeItems removed},
+ * {@link #clearItems cleared} or {@link #setItem displayed}.
+ *
* @event set
- * @param {OO.ui.Layout|null} item Current item or null if there is no longer
a layout shown
+ * @param {OO.ui.Layout|null} item Current panel or `null` if no panel is shown
*/
/* Methods */
/**
- * Get the current item.
+ * Get the current panel.
*
* @return {OO.ui.Layout|null}
*/
@@ -75,12 +99,14 @@
};
/**
- * Add items.
+ * Add panel layouts to the stack layout.
*
- * Adding an existing item (by value) will move it.
+ * Panels will be added to the end of the stack layout array unless the
optional index parameter specifies a different
+ * insertion point. Adding a panel that is already in the stack will move it
to the end of the array or the point specified
+ * by the index.
*
- * @param {OO.ui.Layout[]} items Items to add
- * @param {number} [index] Index to insert items after
+ * @param {OO.ui.Layout[]} items Panels to add
+ * @param {number} [index] Index of the insertion point
* @chainable
*/
OO.ui.StackLayout.prototype.addItems = function ( items, index ) {
@@ -98,11 +124,12 @@
};
/**
- * Remove items.
+ * Remove the specified panels from the stack layout.
*
- * Items will be detached, not removed, so they can be used later.
+ * Removed panels are detached from the DOM, not removed, so that they may be
reused. To remove all panels,
+ * you may wish to use the #clearItems method instead.
*
- * @param {OO.ui.Layout[]} items Items to remove
+ * @param {OO.ui.Layout[]} items Panels to remove
* @chainable
* @fires set
*/
@@ -122,9 +149,10 @@
};
/**
- * Clear all items.
+ * Clear all panels from the stack layout.
*
- * Items will be detached, not removed, so they can be used later.
+ * Cleared panels are detached from the DOM, not removed, so that they may be
reused. To remove only
+ * a subset of panels, use the #removeItems method.
*
* @chainable
* @fires set
@@ -137,14 +165,11 @@
};
/**
- * Show item.
+ * Show the specified panel.
*
- * Any currently shown item will be hidden.
+ * If another panel is currently displayed, it will be hidden.
*
- * FIXME: If the passed item to show has not been added in the items list, then
- * this method drops it and unsets the current item.
- *
- * @param {OO.ui.Layout} item Item to show
+ * @param {OO.ui.Layout} item Panel to show
* @chainable
* @fires set
*/
@@ -169,6 +194,7 @@
* Ensure all items are hidden except for the selected one.
* This method does nothing when the stack is continuous.
*
+ * @private
* @param {OO.ui.Layout[]} items Item list iterate over
* @param {OO.ui.Layout} [selectedItem] Selected
[MediaWiki-commits] [Gerrit] BookletLayout: Add description and example - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/199797
Change subject: BookletLayout: Add description and example
..
BookletLayout: Add description and example
Change-Id: I2c2f0c3d9741f53c3f3aa6ed6ba3141ea2dc0870
---
M src/layouts/BookletLayout.js
1 file changed, 75 insertions(+), 20 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/97/199797/1
diff --git a/src/layouts/BookletLayout.js b/src/layouts/BookletLayout.js
index 5c2d195..cdba753 100644
--- a/src/layouts/BookletLayout.js
+++ b/src/layouts/BookletLayout.js
@@ -1,5 +1,42 @@
/**
- * Layout containing a series of pages.
+ * BookletLayouts contain {@link OO.ui.PageLayout page layouts} as well as
+ * an {@link OO.ui.OutlineSelectWidget outline} that allows users to easily
navigate
+ * through the pages and select which one to display. By default, only one
page is
+ * displayed at a time and the outline is hidden. When a user navigates to a
new page,
+ * the booklet layout automatically focuses on the first focusable element,
unless the
+ * default setting is changed. Optionally, booklets can be configured to show
+ * {@link OO.ui.OutlineControlsWidget controls} for adding, moving, and
removing items.
+ *
+ * @example
+ * // Example of a BookletLayout that contains two PageLayouts.
+ *
+ * function PageOneLayout( name, config ) {
+ * PageOneLayout.super.call( this, name, config );
+ * this.$element.append( 'pFirst page/pp(This booklet has an
outline, displayed on the left)/p' );
+ * }
+ * OO.inheritClass( PageOneLayout, OO.ui.PageLayout );
+ * PageOneLayout.prototype.setupOutlineItem = function () {
+ * this.outlineItem.setLabel( 'Page One' );
+ * };
+ *
+ * function PageTwoLayout( name, config ) {
+ * PageTwoLayout.super.call( this, name, config );
+ * this.$element.append( 'pSecond page/p' );
+ * }
+ * OO.inheritClass( PageTwoLayout, OO.ui.PageLayout );
+ * PageTwoLayout.prototype.setupOutlineItem = function () {
+ * this.outlineItem.setLabel( 'Page Two' );
+ * };
+ *
+ * var page1 = new PageOneLayout( 'one' ),
+ * page2 = new PageTwoLayout( 'two' );
+ *
+ * var booklet = new OO.ui.BookletLayout( {
+ * outlined: true
+ * } );
+ *
+ * booklet.addPages ( [ page1, page2 ] );
+ * $( 'body' ).append( booklet.$element );
*
* @class
* @extends OO.ui.MenuLayout
@@ -7,8 +44,8 @@
* @constructor
* @param {Object} [config] Configuration options
* @cfg {boolean} [continuous=false] Show all pages, one after another
- * @cfg {boolean} [autoFocus=true] Focus on the first focusable element when
changing to a page
- * @cfg {boolean} [outlined=false] Show an outline
+ * @cfg {boolean} [autoFocus=true] Focus on the first focusable element when a
new page is displayed.
+ * @cfg {boolean} [outlined=false] Show the outline. The outline is used to
navigate through the pages of the booklet.
* @cfg {boolean} [editable=false] Show controls for adding, removing and
reordering pages
*/
OO.ui.BookletLayout = function OoUiBookletLayout( config ) {
@@ -74,17 +111,23 @@
/* Events */
/**
+ * A 'set' event is emitted when a page is {@link #setPage set} to be
displayed by the booklet layout.
* @event set
* @param {OO.ui.PageLayout} page Current page
*/
/**
+ * An 'add' event is emitted when pages are {@link #addPages added} to the
booklet layout.
+ *
* @event add
* @param {OO.ui.PageLayout[]} page Added pages
* @param {number} index Index pages were added at
*/
/**
+ * A 'remove' event is emitted when pages are {@link #clearPages cleared} or
+ * {@link #removePages removed} from the booklet.
+ *
* @event remove
* @param {OO.ui.PageLayout[]} pages Removed pages
*/
@@ -94,6 +137,7 @@
/**
* Handle stack layout focus.
*
+ * @private
* @param {jQuery.Event} e Focusin event
*/
OO.ui.BookletLayout.prototype.onStackLayoutFocus = function ( e ) {
@@ -113,6 +157,7 @@
/**
* Handle stack layout set events.
*
+ * @private
* @param {OO.ui.PanelLayout|null} page The page panel that is now the current
panel
*/
OO.ui.BookletLayout.prototype.onStackLayoutSet = function ( page ) {
@@ -153,6 +198,7 @@
/**
* Handle outline widget select events.
*
+ * @private
* @param {OO.ui.OptionWidget|null} item Selected item
*/
OO.ui.BookletLayout.prototype.onOutlineSelectWidgetSelect = function ( item ) {
@@ -164,7 +210,7 @@
/**
* Check if booklet has an outline.
*
- * @return {boolean}
+ * @return {boolean} Booklet has an outline
*/
OO.ui.BookletLayout.prototype.isOutlined = function () {
return this.outlined;
@@ -173,7 +219,7 @@
/**
* Check if booklet has editing controls.
*
- * @return {boolean}
+ * @return {boolean} Booklet is editable
*/
OO.ui.BookletLayout.prototype.isEditable = function () {
return this.editable;
@@ -182,7 +228,7
[MediaWiki-commits] [Gerrit] LookupElement: Add description and mark private and protecte... - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/198806
Change subject: LookupElement: Add description and mark private and protected
methods
..
LookupElement: Add description and mark private and protected methods
Change-Id: Iabddf330dfdee9995ab7914ab4156424f05cc511
---
M src/elements/LookupElement.js
1 file changed, 32 insertions(+), 8 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/06/198806/1
diff --git a/src/elements/LookupElement.js b/src/elements/LookupElement.js
index 5802e5e..c34d1ac 100644
--- a/src/elements/LookupElement.js
+++ b/src/elements/LookupElement.js
@@ -1,19 +1,26 @@
/**
- * Mixin that adds a menu showing suggested values for a OO.ui.TextInputWidget.
+ * LookupElement is a mixin that creates a {@link
OO.ui.TextInputMenuSelectWidget menu} of suggested values for
+ * a {@link OO.ui.TextInputWidget text input widget}. Suggested values are
based on the characters the user types
+ * into the text input field and, in general, the menu is only displayed when
the user types. If a suggested value is chosen
+ * from the lookup menu, that value becomes the value of the input field.
*
- * Subclasses that set the value of #lookupInput from #onLookupMenuItemChoose
should
- * be aware that this will cause new suggestions to be looked up for the new
value. If this is
- * not desired, disable lookups with #setLookupsDisabled, then set the value,
then re-enable lookups.
+ * Note that a new menu of suggested items is displayed when a value is chosen
from the lookup menu. If this is
+ * not the desired behavior, disable lookup menus with the #setLookupsDisabled
method, then set the value, then
+ * re-enable lookups.
+ *
+ * See the [OOjs UI demos][1] for an example.
+ *
+ * [1]:
https://tools.wmflabs.org/oojs-ui/oojs-ui/demos/index.html#widgets-apex-vector-ltr
*
* @class
* @abstract
*
* @constructor
* @param {Object} [config] Configuration options
- * @cfg {jQuery} [$overlay] Overlay for dropdown; defaults to relative
positioning
- * @cfg {jQuery} [$container=this.$element] Element to render menu under
- * @cfg {boolean} [allowSuggestionsWhenEmpty=false] Whether suggestions will
be requested
- * and shown when the user has not typed anything yet.
+ * @cfg {jQuery} [$overlay] Overlay for the lookup menu; defaults to relative
positioning
+ * @cfg {jQuery} [$container=this.$element] The container element. The lookup
menu is rendered beneath the specified element.
+ * @cfg {boolean} [allowSuggestionsWhenEmpty=false] Request and display a
lookup menu when the text input is empty.
+ * By default, the lookup menu is not generated and displayed until the user
begins to type.
*/
OO.ui.LookupElement = function OoUiLookupElement( config ) {
// Configuration initialization
@@ -58,6 +65,7 @@
/**
* Handle input focus event.
*
+ * @protected
* @param {jQuery.Event} e Input focus event
*/
OO.ui.LookupElement.prototype.onLookupInputFocus = function () {
@@ -68,6 +76,7 @@
/**
* Handle input blur event.
*
+ * @protected
* @param {jQuery.Event} e Input blur event
*/
OO.ui.LookupElement.prototype.onLookupInputBlur = function () {
@@ -78,6 +87,7 @@
/**
* Handle input mouse down event.
*
+ * @protected
* @param {jQuery.Event} e Input mouse down event
*/
OO.ui.LookupElement.prototype.onLookupInputMouseDown = function () {
@@ -93,6 +103,7 @@
/**
* Handle input change event.
*
+ * @protected
* @param {string} value New input value
*/
OO.ui.LookupElement.prototype.onLookupInputChange = function () {
@@ -104,6 +115,7 @@
/**
* Handle the lookup menu being shown/hidden.
*
+ * @protected
* @param {boolean} visible Whether the lookup menu is now visible.
*/
OO.ui.LookupElement.prototype.onLookupMenuToggle = function ( visible ) {
@@ -119,6 +131,7 @@
/**
* Handle menu item 'choose' event, updating the text input value to the value
of the clicked item.
*
+ * @protected
* @param {OO.ui.MenuOptionWidget|null} item Selected item
*/
OO.ui.LookupElement.prototype.onLookupMenuItemChoose = function ( item ) {
@@ -130,6 +143,7 @@
/**
* Get lookup menu.
*
+ * @private
* @return {OO.ui.TextInputMenuSelectWidget}
*/
OO.ui.LookupElement.prototype.getLookupMenu = function () {
@@ -150,6 +164,7 @@
/**
* Open the menu. If there are no entries in the menu, this does nothing.
*
+ * @private
* @chainable
*/
OO.ui.LookupElement.prototype.openLookupMenu = function () {
@@ -162,6 +177,7 @@
/**
* Close the menu, empty it, and abort any pending request.
*
+ * @private
* @chainable
*/
OO.ui.LookupElement.prototype.closeLookupMenu = function () {
@@ -177,6 +193,7 @@
*
* If lookups have been disabled with #setLookupsDisabled, this function does
nothing.
*
+ * @private
* @chainable
*/
OO.ui.LookupElement.prototype.populateLookupMenu = function () {
@@ -215,6 +232,7 @@
/**
* Select
[MediaWiki-commits] [Gerrit] SearchWidget: Add description and mark private methods - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/199144
Change subject: SearchWidget: Add description and mark private methods
..
SearchWidget: Add description and mark private methods
Change-Id: Id096a31531ea00c08c39b7e4fd16785b346cecab
---
M src/widgets/SearchWidget.js
1 file changed, 24 insertions(+), 5 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/44/199144/1
diff --git a/src/widgets/SearchWidget.js b/src/widgets/SearchWidget.js
index b236c3a..0ceecb8 100644
--- a/src/widgets/SearchWidget.js
+++ b/src/widgets/SearchWidget.js
@@ -1,8 +1,14 @@
/**
- * Search widget.
+ * SearchWidgets combine a {@link OO.ui.TextInputWidget text input field},
where users can type a search query,
+ * and a {@link OO.ui.TextInputMenuSelectWidget menu} of search results, which
is displayed beneath the query
+ * field. Unlike {@link OO.ui.LookupElement lookup menus}, search result menus
are always visible to the user.
+ * Users can choose an item from the menu or type a query into the text field
to search for a matching result item.
+ * In general, search widgets are used inside a separate {@link OO.ui.Dialog
dialog} window.
*
- * Search widgets combine a query input, placed above, and a results selection
widget, placed below.
- * Results are cleared and populated each time the query is changed.
+ * Each time the query is changed, the search result menu is cleared and
repopulated. Please see
+ * the [OOjs UI demos][1] for an example.
+ *
+ * [1]:
https://tools.wmflabs.org/oojs-ui/oojs-ui/demos/#dialogs-mediawiki-vector-ltr
*
* @class
* @extends OO.ui.Widget
@@ -59,11 +65,19 @@
/* Events */
/**
+ * A 'highlight' event is emitted when an item is highlighted. The highlight
indicates which
+ * item will be selected. When a user mouses over a menu item, it is
highlighted. If a search
+ * string is typed into the query field instead, the first menu item that
matches the query
+ * will be highlighted.
+
* @event highlight
* @param {Object|null} item Item data or null if no item is highlighted
*/
/**
+ * A 'select' event is emitted when an item is selected. A menu item is
selected when it is clicked,
+ * or when a user types a search query, a menu result is highlighted, and the
user presses enter.
+ *
* @event select
* @param {Object|null} item Item data or null if no item is selected
*/
@@ -73,6 +87,7 @@
/**
* Handle query key down events.
*
+ * @private
* @param {jQuery.Event} e Key down event
*/
OO.ui.SearchWidget.prototype.onQueryKeydown = function ( e ) {
@@ -95,6 +110,7 @@
*
* Clears existing results. Subclasses should repopulate items according to
new query.
*
+ * @private
* @param {string} value New value
*/
OO.ui.SearchWidget.prototype.onQueryChange = function () {
@@ -107,6 +123,7 @@
*
* Selects highlighted item.
*
+ * @private
* @param {string} value New value
*/
OO.ui.SearchWidget.prototype.onQueryEnter = function () {
@@ -117,6 +134,7 @@
/**
* Handle select widget highlight events.
*
+ * @private
* @param {OO.ui.OptionWidget} item Highlighted item
* @fires highlight
*/
@@ -127,6 +145,7 @@
/**
* Handle select widget select events.
*
+ * @private
* @param {OO.ui.OptionWidget} item Selected item
* @fires select
*/
@@ -144,9 +163,9 @@
};
/**
- * Get the results list.
+ * Get the search results menu.
*
- * @return {OO.ui.SelectWidget} Select list
+ * @return {OO.ui.SelectWidget} Menu of search results
*/
OO.ui.SearchWidget.prototype.getResults = function () {
return this.results;
--
To view, visit https://gerrit.wikimedia.org/r/199144
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: Id096a31531ea00c08c39b7e4fd16785b346cecab
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] TabIndexElement: Mark private method - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/198765
Change subject: TabIndexElement: Mark private method
..
TabIndexElement: Mark private method
Change-Id: I5daa8047a4a3001cc4d81c577921a4c4f0b92a3a
---
M src/elements/TabIndexedElement.js
1 file changed, 1 insertion(+), 0 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/65/198765/1
diff --git a/src/elements/TabIndexedElement.js
b/src/elements/TabIndexedElement.js
index 2f7f093..5c2151a 100644
--- a/src/elements/TabIndexedElement.js
+++ b/src/elements/TabIndexedElement.js
@@ -99,6 +99,7 @@
* Update the `tabindex` attribute, in case of changes to tab index or
* disabled state.
*
+ * @private
* @chainable
*/
OO.ui.TabIndexedElement.prototype.updateTabIndex = function () {
--
To view, visit https://gerrit.wikimedia.org/r/198765
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I5daa8047a4a3001cc4d81c577921a4c4f0b92a3a
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] ButtonElement: Clarify description - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/198761
Change subject: ButtonElement: Clarify description
..
ButtonElement: Clarify description
Change-Id: I2c54610a0510006ae1158023c72c1ec69abcc9cf
---
M src/elements/ButtonElement.js
1 file changed, 20 insertions(+), 6 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/61/198761/1
diff --git a/src/elements/ButtonElement.js b/src/elements/ButtonElement.js
index fab6a1a..c8e76db 100644
--- a/src/elements/ButtonElement.js
+++ b/src/elements/ButtonElement.js
@@ -9,8 +9,9 @@
*
* @constructor
* @param {Object} [config] Configuration options
- * @cfg {jQuery} [$button] Button node, assigned to #$button, omit to use a
generated `a`
- * @cfg {boolean} [framed=true] Render button with a frame
+ * @cfg {jQuery} [$button] The button element created by the class.
+ * If this configuration is omitted, the button element will use a generated
`a`.
+ * @cfg {boolean} [framed=true] Render the button with a frame
* @cfg {string} [accessKey] Button's access key
*/
OO.ui.ButtonElement = function OoUiButtonElement( config ) {
@@ -45,6 +46,11 @@
/**
* Cancel mouse down events.
*
+ * This property is usually set to `true` to prevent the focus from changing
when the button is clicked.
+ * Classes such as {@link OO.ui.DraggableElement DraggableElement} and {@link
OO.ui.ButtonOptionWidget ButtonOptionWidget}
+ * use a value of `false` so that dragging behavior is possible and mousedown
events can be handled by a
+ * parent widget.
+ *
* @static
* @inheritable
* @property {boolean}
@@ -54,6 +60,8 @@
/* Events */
/**
+ * A 'click' event is emitted when the button element is clicked.
+ *
* @event click
*/
@@ -62,7 +70,9 @@
/**
* Set the button element.
*
- * If an element is already set, it will be cleaned up before setting up the
new element.
+ * This method is used to retarget a button mixin so that its functionality
applies to
+ * the specified button element instead of the one created by the class. If a
button element
+ * is already set, the method will remove the mixin’s effect on that element.
*
* @param {jQuery} $button Element to use as button
*/
@@ -194,7 +204,7 @@
};
/**
- * Toggle frame.
+ * Render the button with or without a frame. Omit the `framed` parameter to
toggle the button frame on and off.
*
* @param {boolean} [framed] Make button framed, omit to toggle
* @chainable
@@ -213,7 +223,7 @@
};
/**
- * Set access key.
+ * Set the button's access key.
*
* @param {string} accessKey Button's access key, use empty string to remove
* @chainable
@@ -236,7 +246,11 @@
};
/**
- * Set active state.
+ * Set the button to its 'active' state.
+ *
+ * The active state occurs when a {@link OO.ui.ButtonOptionWidget
ButtonOptionWidget} or
+ * a {@link OO.ui.ToggleButtonWidget ToggleButtonWidget} is pressed. This
method does nothing
+ * for other button types.
*
* @param {boolean} [value] Make button active
* @chainable
--
To view, visit https://gerrit.wikimedia.org/r/198761
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I2c54610a0510006ae1158023c72c1ec69abcc9cf
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] MenuSectionOptionWidget: Add description and example - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/199153
Change subject: MenuSectionOptionWidget: Add description and example
..
MenuSectionOptionWidget: Add description and example
Change-Id: I59abc093dc6e38242d7f26d5d5634bc6d50c2484
---
M src/widgets/MenuSectionOptionWidget.js
1 file changed, 30 insertions(+), 1 deletion(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/53/199153/1
diff --git a/src/widgets/MenuSectionOptionWidget.js
b/src/widgets/MenuSectionOptionWidget.js
index 8986711..b3f2c89 100644
--- a/src/widgets/MenuSectionOptionWidget.js
+++ b/src/widgets/MenuSectionOptionWidget.js
@@ -1,5 +1,34 @@
/**
- * Section to group one or more items in a OO.ui.MenuSelectWidget.
+ * MenuSectionOptionWidgets are used inside {@link OO.ui.MenuSelectWidget menu
select widgets} to group one or more related
+ * {@link OO.ui.MenuOptionWidget menu options}. MenuSectionOptionWidgets
cannot be highlighted or selected.
+ *
+ * @example
+ * var myDropdown = new OO.ui.DropdownWidget( {
+ * menu: {
+ * items: [
+ * new OO.ui.MenuSectionOptionWidget( {
+ * label: 'Dogs'
+ * }),
+ * new OO.ui.MenuOptionWidget( {
+ * data: 'corgi',
+ * label: 'Welsh Corgi'
+ * } ),
+ * new OO.ui.MenuOptionWidget( {
+ * data: 'poodle',
+ * label: 'Standard Poodle'
+ * } ),
+ * new OO.ui.MenuSectionOptionWidget( {
+ * label: 'Cats'
+ * } ),
+ * new OO.ui.MenuOptionWidget( {
+ * data: 'lion',
+ * label: 'Lion'
+ * } )
+ * ]
+ * }
+ * } );
+ * $( 'body' ).append( myDropdown.$element );
+ *
*
* @class
* @extends OO.ui.DecoratedOptionWidget
--
To view, visit https://gerrit.wikimedia.org/r/199153
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I59abc093dc6e38242d7f26d5d5634bc6d50c2484
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] PanelLayout: Add description and example - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/198417
Change subject: PanelLayout: Add description and example
..
PanelLayout: Add description and example
Change-Id: I34f0edcdd6794b1b7a1e87cf3086cc3bf32adbc7
---
M src/layouts/PanelLayout.js
1 file changed, 15 insertions(+), 4 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/17/198417/1
diff --git a/src/layouts/PanelLayout.js b/src/layouts/PanelLayout.js
index b3e026a..9183f59 100644
--- a/src/layouts/PanelLayout.js
+++ b/src/layouts/PanelLayout.js
@@ -1,5 +1,16 @@
/**
- * Layout that expands to cover the entire area of its parent, with optional
scrolling and padding.
+ * PanelLayouts expand to cover the entire area of their parent. They can be
configured with scrolling, padding,
+ * and a frame, and are often used together with {@link OO.ui.StackLayout
StackLayouts}.
+ *
+ * @example
+ * // Example of a panel layout
+ * var panel = new OO.ui.PanelLayout( {
+ * expanded: false,
+ * framed: true,
+ * padded: true,
+ * $content: $( 'pA panel layout with padding and a frame./p' )
+ * } );
+ * $( 'body' ).append( panel.$element );
*
* @class
* @extends OO.ui.Layout
@@ -7,9 +18,9 @@
* @constructor
* @param {Object} [config] Configuration options
* @cfg {boolean} [scrollable=false] Allow vertical scrolling
- * @cfg {boolean} [padded=false] Pad the content from the edges
- * @cfg {boolean} [expanded=true] Expand size to fill the entire parent element
- * @cfg {boolean} [framed=false] Wrap in a frame to visually separate from
outside content
+ * @cfg {boolean} [padded=false] Add padding between the content and the edges
of the panel.
+ * @cfg {boolean} [expanded=true] Expand the panel to fill the entire parent
element.
+ * @cfg {boolean} [framed=false] Render the panel with a frame to visually
separate it from outside content.
*/
OO.ui.PanelLayout = function OoUiPanelLayout( config ) {
// Configuration initialization
--
To view, visit https://gerrit.wikimedia.org/r/198417
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I34f0edcdd6794b1b7a1e87cf3086cc3bf32adbc7
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] FieldsetLayout: Add description and example - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/198275
Change subject: FieldsetLayout: Add description and example
..
FieldsetLayout: Add description and example
Change-Id: Ic9a27a7ecff87d84dc9479b7a21f5ad7c3e2aa9f
---
M src/layouts/FieldsetLayout.js
1 file changed, 30 insertions(+), 3 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/75/198275/1
diff --git a/src/layouts/FieldsetLayout.js b/src/layouts/FieldsetLayout.js
index a3b14f4..1a21e8e 100644
--- a/src/layouts/FieldsetLayout.js
+++ b/src/layouts/FieldsetLayout.js
@@ -1,7 +1,34 @@
/**
- * Layout made of a fieldset and optional legend.
+ * FieldsetLayouts are composed of one or more {@link OO.ui.FieldLayout
FieldLayouts},
+ * which each contain an individual widget and, optionally, a label. Each
Fieldset can be
+ * configured with a label as well. For more information and examples,
+ * please see the [OOjs UI documentation on MediaWiki][1].
*
- * Just add OO.ui.FieldLayout items.
+ * @example
+ * // Example of a fieldset layout
+ * var input1 = new OO.ui.TextInputWidget( {
+ * placeholder: 'A text input field'
+ * } );
+ *
+ * var input2 = new OO.ui.TextInputWidget( {
+ * placeholder: 'A text input field'
+ * } );
+ *
+ * var fieldset = new OO.ui.FieldsetLayout( {
+ * label: 'Example of a fieldset layout'
+ * } );
+ *
+ * fieldset.addItems( [
+ * new OO.ui.FieldLayout( input1, {
+ * label: 'Field One'
+ * } ),
+ * new OO.ui.FieldLayout( input2, {
+ * label: 'Field Two'
+ * } )
+ * ] );
+ * $( 'body' ).append( fieldset.$element );
+ *
+ * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Layouts/Fields_and_Fieldsets
*
* @class
* @extends OO.ui.Layout
@@ -11,7 +38,7 @@
*
* @constructor
* @param {Object} [config] Configuration options
- * @cfg {OO.ui.FieldLayout[]} [items] Items to add
+ * @cfg {OO.ui.FieldLayout[]} [items] An array of fields to add to the
fieldset. See OO.ui.FieldLayout for more information about fields.
*/
OO.ui.FieldsetLayout = function OoUiFieldsetLayout( config ) {
// Configuration initialization
--
To view, visit https://gerrit.wikimedia.org/r/198275
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: Ic9a27a7ecff87d84dc9479b7a21f5ad7c3e2aa9f
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] FieldLayout: Clarify description and mark private methods - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/198281
Change subject: FieldLayout: Clarify description and mark private methods
..
FieldLayout: Clarify description and mark private methods
Change-Id: Ic359784bd5de7bf622567741bfde3282d6f9c11c
---
M src/layouts/FieldLayout.js
1 file changed, 6 insertions(+), 3 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/81/198281/1
diff --git a/src/layouts/FieldLayout.js b/src/layouts/FieldLayout.js
index 0d50dbd..8638574 100644
--- a/src/layouts/FieldLayout.js
+++ b/src/layouts/FieldLayout.js
@@ -25,8 +25,9 @@
* @constructor
* @param {OO.ui.Widget} fieldWidget Field widget
* @param {Object} [config] Configuration options
- * @cfg {string} [align='left'] Alignment mode, either 'left', 'right', 'top'
or 'inline'
- * @cfg {string} [help] Explanatory text shown as a '?' icon.
+ * @cfg {string} [align='left'] Alignment of the label: 'left', 'right', 'top'
or 'inline'
+ * @cfg {string} [help] Help text. When help text is specified, a help icon
will appear
+ * in the upper-right corner of the rendered field.
*/
OO.ui.FieldLayout = function OoUiFieldLayout( fieldWidget, config ) {
// Allow passing positional parameters inside the config object
@@ -97,6 +98,7 @@
/**
* Handle field disable events.
*
+ * @private
* @param {boolean} value Field is disabled
*/
OO.ui.FieldLayout.prototype.onFieldDisable = function ( value ) {
@@ -106,6 +108,7 @@
/**
* Handle label mouse click events.
*
+ * @private
* @param {jQuery.Event} e Mouse click event
*/
OO.ui.FieldLayout.prototype.onLabelClick = function () {
@@ -114,7 +117,7 @@
};
/**
- * Get the field.
+ * Get the widget contained by the field.
*
* @return {OO.ui.Widget} Field widget
*/
--
To view, visit https://gerrit.wikimedia.org/r/198281
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: Ic359784bd5de7bf622567741bfde3282d6f9c11c
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] FormLayout: Add description, example, and mark private method - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/198296
Change subject: FormLayout: Add description, example, and mark private method
..
FormLayout: Add description, example, and mark private method
Change-Id: I327ac743705ea2bb2bdb4a04d6f5918c74111820
---
M src/layouts/FormLayout.js
1 file changed, 41 insertions(+), 2 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/96/198296/1
diff --git a/src/layouts/FormLayout.js b/src/layouts/FormLayout.js
index 8c0d151..edb2a2c 100644
--- a/src/layouts/FormLayout.js
+++ b/src/layouts/FormLayout.js
@@ -1,5 +1,41 @@
/**
- * Layout with an HTML form.
+ * FormLayouts are used to wrap {@link OO.ui.FieldsetLayout FieldsetLayouts}
when you intend to use browser-based
+ * form submission for the fields instead of handling them in JavaScript. Form
layouts can be configured with an
+ * HTML form action, an encoding type, and a method using the #action,
#enctype, and #method configs, respectively.
+ *
+ * @example
+ * // Example of a form layout that wraps a fieldset layout
+ * var input1 = new OO.ui.TextInputWidget( {
+ * placeholder: 'Username'
+ * } );
+ * var input2 = new OO.ui.TextInputWidget( {
+ * placeholder: 'Password',
+ * type: 'password'
+ * } );
+ * var submit = new OO.ui.ButtonInputWidget( {
+ * label: 'Submit'
+ * } );
+ *
+ * var fieldset = new OO.ui.FieldsetLayout( {
+ * label: 'A form layout'
+ * } );
+ * fieldset.addItems( [
+ * new OO.ui.FieldLayout( input1, {
+ * label: 'Username',
+ * align: 'top'
+ * } ),
+ * new OO.ui.FieldLayout( input2, {
+ * label: 'Password',
+ * align: 'top'
+ * } ),
+ * new OO.ui.FieldLayout( submit )
+ * ] );
+ * var form = new OO.ui.FormLayout( {
+ * items: [ fieldset ],
+ * action: '/api/formhandler',
+ * method: 'get'
+ * } )
+ * $( 'body' ).append( form.$element );
*
* @class
* @extends OO.ui.Layout
@@ -10,7 +46,7 @@
* @cfg {string} [method] HTML form `method` attribute
* @cfg {string} [action] HTML form `action` attribute
* @cfg {string} [enctype] HTML form `enctype` attribute
- * @cfg {OO.ui.FieldsetLayout[]} [items] Items to add
+ * @cfg {OO.ui.FieldsetLayout[]} [items] Fieldset layouts to add to the form
layout.
*/
OO.ui.FormLayout = function OoUiFormLayout( config ) {
// Configuration initialization
@@ -46,6 +82,8 @@
/* Events */
/**
+ * A 'submit' event is emitted when the form is submitted.
+ *
* @event submit
*/
@@ -58,6 +96,7 @@
/**
* Handle form submit events.
*
+ * @private
* @param {jQuery.Event} e Submit event
* @fires submit
*/
--
To view, visit https://gerrit.wikimedia.org/r/198296
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I327ac743705ea2bb2bdb4a04d6f5918c74111820
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] Layout: Add description - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/198400
Change subject: Layout: Add description
..
Layout: Add description
Change-Id: I82d03c82f218c43a87737757dc179ae6a36b0bd6
---
M src/Layout.js
1 file changed, 5 insertions(+), 1 deletion(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/00/198400/1
diff --git a/src/Layout.js b/src/Layout.js
index 36a4cf4..d0c368f 100644
--- a/src/Layout.js
+++ b/src/Layout.js
@@ -1,5 +1,9 @@
/**
- * Container for elements.
+ * Layouts are containers for elements and are used to arrange other widgets
of arbitrary type in a way
+ * that is centrally controlled and can be updated dynamically. Layouts can
be, and usually are, combined.
+ * See {@link OO.ui.FieldsetLayout FieldsetLayout}, {@link OO.ui.FieldLayout
FieldLayout}, {@link OO.ui.FormLayout FormLayout},
+ * {@link OO.ui.PanelLayout PanelLayout}, {@link OO.ui.StackLayout
StackLayout}, {@link OO.ui.PageLayout PageLayout},
+ * and {@link OO.ui.BookletLayout BookletLayout} for more information and
examples.
*
* @abstract
* @class
--
To view, visit https://gerrit.wikimedia.org/r/198400
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I82d03c82f218c43a87737757dc179ae6a36b0bd6
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] DraggableGroupElement: Clarify description and mark private ... - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/197253
Change subject: DraggableGroupElement: Clarify description and mark private
methods
..
DraggableGroupElement: Clarify description and mark private methods
Change-Id: Ia702facbc9a008debdcc6c16be6db5c9a23ff989
---
M src/elements/DraggableGroupElement.js
1 file changed, 24 insertions(+), 5 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/53/197253/1
diff --git a/src/elements/DraggableGroupElement.js
b/src/elements/DraggableGroupElement.js
index 1b69eb1..2b28da7 100644
--- a/src/elements/DraggableGroupElement.js
+++ b/src/elements/DraggableGroupElement.js
@@ -8,8 +8,12 @@
*
* @constructor
* @param {Object} [config] Configuration options
- * @cfg {jQuery} [$group] Container node, assigned to #$group, omit to use a
generated `div`
- * @cfg {string} [orientation] Item orientation, 'horizontal' or 'vertical'.
Defaults to 'vertical'
+ * @cfg {jQuery} [$group] The container element created by the class. If this
configuration is omitted,
+ * the group element will use a generated `div`.
+ * @cfg {string} [orientation] Item orientation: `'horizontal'` or
`'vertical'`. The orientation
+ * should match the layout of the items. Items displayed in a single row
+ * or in several rows should use `horizontal` orientation. The `vertical`
orientation should only be
+ * used when the items are displayed in a single column. Defaults to
`'vertical'`
*/
OO.ui.DraggableGroupElement = function OoUiDraggableGroupElement( config ) {
// Configuration initialization
@@ -60,6 +64,8 @@
/* Events */
/**
+ * A ‘reorder’ event is emitted when the order of items in the group changes.
+ *
* @event reorder
* @param {OO.ui.DraggableElement} item Reordered item
* @param {number} [newIndex] New index for the item
@@ -69,6 +75,8 @@
/**
* Respond to item drag start event
+ *
+ * @private
* @param {OO.ui.DraggableElement} item Dragged item
*/
OO.ui.DraggableGroupElement.prototype.onItemDragStart = function ( item ) {
@@ -97,6 +105,8 @@
/**
* Respond to item drag end event
+ *
+ * @private
*/
OO.ui.DraggableGroupElement.prototype.onItemDragEnd = function () {
this.unsetDragItem();
@@ -105,6 +115,8 @@
/**
* Handle drop event and switch the order of the items accordingly
+ *
+ * @private
* @param {OO.ui.DraggableElement} item Dropped item
* @fires reorder
*/
@@ -129,6 +141,8 @@
/**
* Handle dragleave event.
+ *
+ * @private
*/
OO.ui.DraggableGroupElement.prototype.onDragLeave = function () {
// This means the item was dragged outside the widget
@@ -139,6 +153,8 @@
/**
* Respond to dragover event
+ *
+ * @private
* @param {jQuery.Event} event Event details
*/
OO.ui.DraggableGroupElement.prototype.onDragOver = function ( e ) {
@@ -210,6 +226,7 @@
/**
* Set a dragged item
+ *
* @param {OO.ui.DraggableElement} item Dragged item
*/
OO.ui.DraggableGroupElement.prototype.setDragItem = function ( item ) {
@@ -227,15 +244,17 @@
};
/**
- * Get the current dragged item
- * @return {OO.ui.DraggableElement|null} item Dragged item or null if no item
is dragged
+ * Get the item that is currently being dragged.
+ *
+ * @return {OO.ui.DraggableElement|null} The currently dragged item, or `null`
if no item is being dragged
*/
OO.ui.DraggableGroupElement.prototype.getDragItem = function () {
return this.dragItem;
};
/**
- * Check if there's an item being dragged.
+ * Check if an item in the group is currently being dragged.
+ *
* @return {Boolean} Item is being dragged
*/
OO.ui.DraggableGroupElement.prototype.isDragging = function () {
--
To view, visit https://gerrit.wikimedia.org/r/197253
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: Ia702facbc9a008debdcc6c16be6db5c9a23ff989
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] FlaggedElement: Add example and clarify description - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/197106
Change subject: FlaggedElement: Add example and clarify description
..
FlaggedElement: Add example and clarify description
Change-Id: If8bbc015dbfe189c9efd9183dafc68fecb504792
---
M src/elements/FlaggedElement.js
1 file changed, 29 insertions(+), 7 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/06/197106/1
diff --git a/src/elements/FlaggedElement.js b/src/elements/FlaggedElement.js
index ab36f2d..241ba0e 100644
--- a/src/elements/FlaggedElement.js
+++ b/src/elements/FlaggedElement.js
@@ -11,6 +11,24 @@
* - **destructive**: Destructive styling is applied to convey that the widget
will remove something.
* - **constructive**: Constructive styling is applied to convey that the
widget will create something.
*
+ * The flags affect the appearance of the buttons:
+ *
+ * @example
+ * // FlaggedElement is mixed into ButtonWidget to provide styling flags
+ * var button1 = new OO.ui.ButtonWidget( {
+ * label : 'Constructive',
+ * flags :'constructive'
+ * } );
+ * var button2 = new OO.ui.ButtonWidget( {
+ * label : 'Destructive',
+ * flags :'destructive'
+ * } );
+ * var button3 = new OO.ui.ButtonWidget( {
+ * label : 'Progressive',
+ * flags :'progressive'
+ * } );
+ * $( 'body' ).append( button1.$element, button2.$element,
button3.$element );
+ *
* {@link OO.ui.ActionWidget ActionWidgets}, which are a special kind of
button that execute an action, use these flags: **primary** and **safe**.
* Please see the [OOjs UI documentation on MediaWiki] [1] for more
information.
*
@@ -24,7 +42,9 @@
* @cfg {string|string[]} [flags] The name or names of the flags (e.g.,
'constructive' or 'primary') to apply.
* Please see the [OOjs UI documentation on MediaWiki] [2] for more
information about available flags.
* [2]: https://www.mediawiki.org/wiki/OOjs_UI/Elements/Flagged
- * @cfg {jQuery} [$flagged] Flagged node, assigned to $flagged, omit to use
$element
+ * @cfg {jQuery} [$flagged] The flagged element. By default,
+ * the flagged functionality is applied to the element created by the class
($element).
+ * If a different element is specified, the flagged functionality will be
applied to it instead.
*/
OO.ui.FlaggedElement = function OoUiFlaggedElement( config ) {
// Configuration initialization
@@ -56,9 +76,10 @@
/**
* Set the flagged element.
*
- * If an element is already set, it will be cleaned up before setting up the
new element.
+ * This method is used to retarget a flagged mixin so that its functionality
applies to the specified element.
+ * If an element is already set, the method will remove the mixin’s effect on
that element.
*
- * @param {jQuery} $flagged Element to add flags to
+ * @param {jQuery} $flagged Element that should be flagged
*/
OO.ui.FlaggedElement.prototype.setFlaggedElement = function ( $flagged ) {
var classNames = Object.keys( this.flags ).map( function ( flag ) {
@@ -73,10 +94,10 @@
};
/**
- * Check if a flag is set.
+ * Check if the specified flag is set.
*
* @param {string} flag Name of flag
- * @return {boolean} Has flag
+ * @return {boolean} The flag is set
*/
OO.ui.FlaggedElement.prototype.hasFlag = function ( flag ) {
return flag in this.flags;
@@ -123,8 +144,9 @@
/**
* Add one or more flags.
*
- * @param {string|string[]|Object.string, boolean} flags One or more flags
to add, or an object
- * keyed by flag name containing boolean set/remove instructions.
+ * @param {string|string[]|Object.string, boolean} flags A flag name, an
array of flag names,
+ * or an object keyed by flag name with a boolean value that indicates
whether the flag should
+ * be added (`true`) or removed (`false`).
* @chainable
* @fires flag
*/
--
To view, visit https://gerrit.wikimedia.org/r/197106
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: If8bbc015dbfe189c9efd9183dafc68fecb504792
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] GroupElement: Clarify description - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/197113
Change subject: GroupElement: Clarify description
..
GroupElement: Clarify description
Change-Id: Ic6a33de242219c92268b2eed737f65672f154d96
---
M src/elements/GroupElement.js
1 file changed, 34 insertions(+), 22 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/13/197113/1
diff --git a/src/elements/GroupElement.js b/src/elements/GroupElement.js
index 0abd8b8..51cf5d2 100644
--- a/src/elements/GroupElement.js
+++ b/src/elements/GroupElement.js
@@ -11,7 +11,8 @@
*
* @constructor
* @param {Object} [config] Configuration options
- * @cfg {jQuery} [$group] Container node, assigned to #$group, omit to use a
generated `div`
+ * @cfg {jQuery} [$group] The container element created by the class. If this
configuration
+ * is omitted, the group element will use a generated `div`.
*/
OO.ui.GroupElement = function OoUiGroupElement( config ) {
// Configuration initialization
@@ -45,7 +46,7 @@
};
/**
- * Check if there are no items.
+ * Check if a group contains no items.
*
* @return {boolean} Group is empty
*/
@@ -54,9 +55,13 @@
};
/**
- * Get items.
+ * Get all items in the group.
*
- * @return {OO.ui.Element[]} Items
+ * The method returns an array of item references (e.g., [button1, button2,
button3]) and is useful
+ * when synchronizing groups of items, or whenever the references are required
(e.g., when removing items
+ * from a group).
+ *
+ * @return {OO.ui.Element[]} An array of items.
*/
OO.ui.GroupElement.prototype.getItems = function () {
return this.items.slice( 0 );
@@ -65,7 +70,8 @@
/**
* Get an item by its data.
*
- * Data is compared by a hash of its value. Only the first item with matching
data will be returned.
+ * Only the first item with matching data will be returned. To return all
matching items,
+ * use the #getItemsFromData method.
*
* @param {Object} data Item data to search for
* @return {OO.ui.Element|null} Item with equivalent data, `null` if none
exists
@@ -87,7 +93,7 @@
/**
* Get items by their data.
*
- * Data is compared by a hash of its value. All items with matching data will
be returned.
+ * All items with matching data will be returned. To return only the first
match, use the #getItemFromData method instead.
*
* @param {Object} data Item data to search for
* @return {OO.ui.Element[]} Items with equivalent data
@@ -108,15 +114,18 @@
};
/**
- * Add an aggregate item event.
+ * Aggregate the events emitted by the group.
*
- * Aggregated events are listened to on each item and then emitted by the
group under a new name,
- * and with an additional leading parameter containing the item that emitted
the original event.
- * Other arguments that were emitted from the original event are passed
through.
+ * When events are aggregated, the group will listen to all contained items
for the event,
+ * and then emit the event under a new name. The new event will contain an
additional leading
+ * parameter containing the item that emitted the original event. Other
arguments emitted from
+ * the original event are passed through.
*
- * @param {Object.string,string|null} events Aggregate events emitted by
group, keyed by item
- * event, use null value to remove aggregation
- * @throws {Error} If aggregation already exists
+ * @param {Object.string,string|null} events An object keyed by the name of
the event that should be
+ * aggregated (e.g., ‘click’) and the value of the new name to use (e.g.,
‘groupClick’).
+ * A `null` value will remove aggregated events.
+
+ * @throws {Error} An error is thrown if aggregation already exists.
*/
OO.ui.GroupElement.prototype.aggregate = function ( events ) {
var i, len, item, add, remove, itemEvent, groupEvent;
@@ -161,12 +170,13 @@
};
/**
- * Add items.
+ * Add items to the group.
*
- * Adding an existing item will move it.
+ * Items will be added to the end of the group array unless the optional
`index` parameter specifies
+ * a different insertion point. Adding an existing item will move it to the
end of the array or the point specified by the `index`.
*
- * @param {OO.ui.Element[]} items Items
- * @param {number} [index] Index to insert items at
+ * @param {OO.ui.Element[]} items An array of items to add to the group
+ * @param {number} [index] Index of the insertion point
* @chainable
*/
OO.ui.GroupElement.prototype.addItems = function ( items, index ) {
@@ -212,11 +222,12 @@
};
/**
- * Remove items.
+ * Remove the specified items from a group.
*
- * Items will be detached, not removed, so they can be used later.
+ * Removed items are detached (not removed) from the DOM so that they may be
reused.
+ * To remove all items from a group, you may wish to use the #clearItems
method instead.
*
- * @param {OO.ui.Element[]} items Items to remove
+ *
[MediaWiki-commits] [Gerrit] TitledElement: Clarify description - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/197248
Change subject: TitledElement: Clarify description
..
TitledElement: Clarify description
Change-Id: I791777db43b81085412c1cc693c33cf6c2f3ac01
---
M src/elements/TitledElement.js
1 file changed, 5 insertions(+), 4 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/48/197248/1
diff --git a/src/elements/TitledElement.js b/src/elements/TitledElement.js
index 08cbbad..8b69d63 100644
--- a/src/elements/TitledElement.js
+++ b/src/elements/TitledElement.js
@@ -21,7 +21,7 @@
* If this config is omitted, the title functionality is applied to $element,
the
* element created by the class.
* @cfg {string|Function} [title] The title text or a function that returns
text. If
- * this config is omitted, the value of the static `title` property is used.
+ * this config is omitted, the value of the {@link #static-title static
title} property is used.
*/
OO.ui.TitledElement = function OoUiTitledElement( config ) {
// Configuration initialization
@@ -57,9 +57,10 @@
/**
* Set the titled element.
*
- * If an element is already set, it will be cleaned up before setting up the
new element.
+ * This method is used to retarget a titledElement mixin so that its
functionality applies to the specified element.
+ * If an element is already set, the mixin’s effect on that element is removed
before the new element is set up.
*
- * @param {jQuery} $titled Element to set title on
+ * @param {jQuery} $titled Element that should use the 'titled' functionality
*/
OO.ui.TitledElement.prototype.setTitledElement = function ( $titled ) {
if ( this.$titled ) {
@@ -75,7 +76,7 @@
/**
* Set title.
*
- * @param {string|Function|null} title Title text, a function that returns
text or null for no title
+ * @param {string|Function|null} title Title text, a function that returns
text, or `null` for no title
* @chainable
*/
OO.ui.TitledElement.prototype.setTitle = function ( title ) {
--
To view, visit https://gerrit.wikimedia.org/r/197248
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I791777db43b81085412c1cc693c33cf6c2f3ac01
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] IndicatorElement: Clarify description - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/197128
Change subject: IndicatorElement: Clarify description
..
IndicatorElement: Clarify description
Change-Id: I77f597627b612249fef72f3b6cd91c195fc28ce7
---
M src/elements/IndicatorElement.js
1 file changed, 11 insertions(+), 7 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/28/197128/1
diff --git a/src/elements/IndicatorElement.js b/src/elements/IndicatorElement.js
index 8ce3c21..5c6294d 100644
--- a/src/elements/IndicatorElement.js
+++ b/src/elements/IndicatorElement.js
@@ -93,9 +93,9 @@
};
/**
- * Set indicator name.
+ * Set the indicator by its symbolic name: ‘alert’, ‘down’, ‘next’,
‘previous’, ‘required’, ‘up’. Use `null` to remove the indicator.
*
- * @param {string|null} indicator Symbolic name of indicator to use or null
for no indicator
+ * @param {string|null} indicator Symbolic name of indicator, or `null` for no
indicator
* @chainable
*/
OO.ui.IndicatorElement.prototype.setIndicator = function ( indicator ) {
@@ -120,10 +120,12 @@
};
/**
- * Set indicator title.
+ * Set the indicator title.
*
- * @param {string|Function|null} indicator Indicator title text, a function
that returns text or
- * null for no indicator title
+ * The title is displayed when a user moves the mouse over the indicator.
+ *
+ * @param {string|Function|null} indicator Indicator title text, a function
that returns text, or
+ * `null` for no indicator title
* @chainable
*/
OO.ui.IndicatorElement.prototype.setIndicatorTitle = function ( indicatorTitle
) {
@@ -146,7 +148,7 @@
};
/**
- * Get indicator name.
+ * Get the symbolic name of the indicator (e.g., ‘alert’ or ‘down’).
*
* @return {string} Symbolic name of indicator
*/
@@ -155,7 +157,9 @@
};
/**
- * Get indicator title.
+ * Get the indicator title.
+ *
+ * The title is displayed when a user moves the mouse over the indicator.
*
* @return {string} Indicator title text
*/
--
To view, visit https://gerrit.wikimedia.org/r/197128
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I77f597627b612249fef72f3b6cd91c195fc28ce7
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] TabIndexedElement: Clarify description - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/197241
Change subject: TabIndexedElement: Clarify description
..
TabIndexedElement: Clarify description
Change-Id: I0238947ebf622abf88624344cee7a34fab0fd965
---
M src/elements/TabIndexedElement.js
1 file changed, 15 insertions(+), 10 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/41/197241/1
diff --git a/src/elements/TabIndexedElement.js
b/src/elements/TabIndexedElement.js
index 70b3ef9..7089e00 100644
--- a/src/elements/TabIndexedElement.js
+++ b/src/elements/TabIndexedElement.js
@@ -29,9 +29,12 @@
*
* @constructor
* @param {Object} [config] Configuration options
- * @cfg {jQuery} [$tabIndexed] tabIndexed node, assigned to #$tabIndexed, omit
to use #$element
- * @cfg {number|null} [tabIndex=0] Tab index value. Use 0 to use default
ordering, use -1 to
- * prevent tab focusing, use null to suppress the `tabindex` attribute.
+ * @cfg {jQuery} [$tabIndexed] The element that should use the tabindex
functionality. By default,
+ * the functionality is applied to the element created by the class
($element). If a different element is specified, the tabindex
+ * functionality will be applied to it instead.
+ * @cfg {number|null} [tabIndex=0] Number that specifies the element’s
position in the tab-navigation
+ * order (e.g., 1 for the first focusable element). Use 0 to use the default
navigation order; use -1
+ * to remove the element from the tab-navigation flow.
*/
OO.ui.TabIndexedElement = function OoUiTabIndexedElement( config ) {
// Configuration initialization
@@ -56,11 +59,13 @@
/* Methods */
/**
- * Set the element with `tabindex` attribute.
+ * Set the element that should use the tabindex functionality.
*
- * If an element is already set, it will be cleaned up before setting up the
new element.
+ * This method is used to retarget a tabindex mixin so that its functionality
applies
+ * to the specified element. If an element is currently using the
functionality, the mixin’s
+ * effect on that element is removed before the new elemement is set up.
*
- * @param {jQuery} $tabIndexed Element to set tab index on
+ * @param {jQuery} $tabIndexed Element that should use the tabindex
functionality
* @chainable
*/
OO.ui.TabIndexedElement.prototype.setTabIndexedElement = function (
$tabIndexed ) {
@@ -74,9 +79,9 @@
};
/**
- * Set tab index value.
+ * Set the value of the tabindex.
*
- * @param {number|null} tabIndex Tab index value or null for no tab index
+ * @param {number|null} tabIndex Tabindex value, or `null` for no tabindex
* @chainable
*/
OO.ui.TabIndexedElement.prototype.setTabIndex = function ( tabIndex ) {
@@ -123,9 +128,9 @@
};
/**
- * Get tab index value.
+ * Get the value of the tabindex.
*
- * @return {number|null} Tab index value
+ * @return {number|null} Tabindex value
*/
OO.ui.TabIndexedElement.prototype.getTabIndex = function () {
return this.tabIndex;
--
To view, visit https://gerrit.wikimedia.org/r/197241
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I0238947ebf622abf88624344cee7a34fab0fd965
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] Dialog: Fix links to static properties - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/196600
Change subject: Dialog: Fix links to static properties
..
Dialog: Fix links to static properties
Change-Id: I02c2e240118b17b331799096482ac2301963604f
---
M src/Dialog.js
1 file changed, 4 insertions(+), 3 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/00/196600/1
diff --git a/src/Dialog.js b/src/Dialog.js
index 65c13cd..0ef7b11 100644
--- a/src/Dialog.js
+++ b/src/Dialog.js
@@ -211,9 +211,10 @@
* @inheritdoc
*
* @param {Object} [data] Dialog opening data
- * @param {jQuery|string|Function|null} [data.title] Dialog title, omit to use
#static-title
- * @param {Object[]} [data.actions] List of OO.ui.ActionWidget configuration
options for each
- * action item, omit to use #static-actions
+ * @param {jQuery|string|Function|null} [data.title] Dialog title, omit to use
+ * the {@link #static-title static title}
+ * @param {Object[]} [data.actions] List of configuration options for each
+ * {@link OO.ui.ActionWidget action widget}, omit to use {@link
#static-actions static actions}.
*/
OO.ui.Dialog.prototype.getSetupProcess = function ( data ) {
data = data || {};
--
To view, visit https://gerrit.wikimedia.org/r/196600
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I02c2e240118b17b331799096482ac2301963604f
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] Window: Clarify description of setDimensions method - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/196598
Change subject: Window: Clarify description of setDimensions method
..
Window: Clarify description of setDimensions method
Change-Id: I466c960b7a81f080744c0d51da5dbcc0a7062302
---
M src/Window.js
1 file changed, 3 insertions(+), 2 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/98/196598/1
diff --git a/src/Window.js b/src/Window.js
index e22c7f9..55e0a85 100644
--- a/src/Window.js
+++ b/src/Window.js
@@ -403,9 +403,10 @@
};
/**
- * Set window dimensions.
+ * Set window dimensions. This method is called by the {@link
OO.ui.WindowManager window manager}
+ * when the window is opening. In general, setDimensions should not be called
directly.
*
- * Properties are applied to the frame container.
+ * To set the size of the window, use the #setSize method.
*
* @param {Object} dim CSS dimension properties
* @param {string|number} [dim.width] Width
--
To view, visit https://gerrit.wikimedia.org/r/196598
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I466c960b7a81f080744c0d51da5dbcc0a7062302
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] WindowManager: Clarify description and mark private methods - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/196659
Change subject: WindowManager: Clarify description and mark private methods
..
WindowManager: Clarify description and mark private methods
Change-Id: I9befef225f1e92bfe22ea29eebe37c702be2c392
---
M src/WindowManager.js
1 file changed, 61 insertions(+), 42 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/59/196659/1
diff --git a/src/WindowManager.js b/src/WindowManager.js
index 9483afb..6f25b56 100644
--- a/src/WindowManager.js
+++ b/src/WindowManager.js
@@ -50,6 +50,8 @@
* @constructor
* @param {Object} [config] Configuration options
* @cfg {OO.Factory} [factory] Window factory to use for automatic
instantiation
+ * Note that window classes that are instantiated with a factory must have
+ * a {@link OO.ui.Dialog#static-name static name} property that specifies a
symbolic name.
* @cfg {boolean} [modal=true] Prevent interaction outside the dialog
*/
OO.ui.WindowManager = function OoUiWindowManager( config ) {
@@ -92,34 +94,30 @@
/* Events */
/**
- * Window is opening.
- *
- * Fired when the window begins to be opened.
+ * An 'opening' event is emitted when the window begins to be opened.
*
* @event opening
* @param {OO.ui.Window} win Window that's being opened
- * @param {jQuery.Promise} opening Promise resolved when window is opened;
when the promise is
- * resolved the first argument will be a promise which will be resolved when
the window begins
- * closing, the second argument will be the opening data; progress
notifications will be fired on
- * the promise for `setup` and `ready` when those processes are completed
respectively.
+ * @param {jQuery.Promise} opening An `opening` promise resolved with a value
when the window is opened successfully.
+ * When the `opening` promise is resolved, the first argument of the value is
an 'opened' promise, the second argument
+ * is the opening data. The `opening` promise emits `setup` and `ready`
notifications when those processes are complete.
* @param {Object} data Window opening data
*/
/**
- * Window is closing.
- *
- * Fired when the window begins to be closed.
+ * A 'closing' event is emitted when the window begins to be closed.
*
* @event closing
* @param {OO.ui.Window} win Window that's being closed
- * @param {jQuery.Promise} closing Promise resolved when window is closed;
when the promise
- * is resolved the first argument will be a the closing data; progress
notifications will be fired
- * on the promise for `hold` and `teardown` when those processes are
completed respectively.
+ * @param {jQuery.Promise} closing A `closing` promise is resolved with a
value when the window
+ * is closed successfully. The promise emits `hold` and `teardown`
notifications when those
+ * processes are complete. When the `closing` promise is resolved, the first
argument of its value
+ * is the closing data.
* @param {Object} data Window closing data
*/
/**
- * Window was resized.
+ * A 'resize' event is emitted when a window is resized.
*
* @event resize
* @param {OO.ui.Window} win Window that was resized
@@ -128,7 +126,7 @@
/* Static Properties */
/**
- * Map of symbolic size names and CSS properties.
+ * Map of the symbolic name of each window size and its CSS properties.
*
* @static
* @inheritable
@@ -155,9 +153,9 @@
};
/**
- * Symbolic name of default size.
+ * Symbolic name of the default window size.
*
- * Default size is used if the window's requested size is not recognized.
+ * The default size is used if the window's requested size is not recognized.
*
* @static
* @inheritable
@@ -170,6 +168,7 @@
/**
* Handle window resize events.
*
+ * @private
* @param {jQuery.Event} e Window resize event
*/
OO.ui.WindowManager.prototype.onWindowResize = function () {
@@ -180,6 +179,7 @@
/**
* Handle window resize events.
*
+ * @private
* @param {jQuery.Event} e Window resize event
*/
OO.ui.WindowManager.prototype.afterWindowResize = function () {
@@ -234,7 +234,7 @@
};
/**
- * Get the number of milliseconds to wait between beginning opening and
executing setup process.
+ * Get the number of milliseconds to wait after opening begins before
executing the ‘setup’ process.
*
* @param {OO.ui.Window} win Window being opened
* @param {Object} [data] Window opening data
@@ -245,7 +245,7 @@
};
/**
- * Get the number of milliseconds to wait between finishing setup and
executing ready process.
+ * Get the number of milliseconds to wait after setup has finished before
executing the ‘ready’ process.
*
* @param {OO.ui.Window} win Window being opened
* @param {Object} [data] Window opening data
@@ -256,7 +256,7 @@
};
/**
- * Get the number of milliseconds to wait between beginning closing and
executing hold process.
+ * Get the number of milliseconds to wait
[MediaWiki-commits] [Gerrit] Widget: Clarify description - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/196725
Change subject: Widget: Clarify description
..
Widget: Clarify description
Change-Id: Ib17c529c338c5393d85fde0cb54398842afe11d9
---
M src/Widget.js
1 file changed, 11 insertions(+), 4 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/25/196725/1
diff --git a/src/Widget.js b/src/Widget.js
index b9680f1..4929e05 100644
--- a/src/Widget.js
+++ b/src/Widget.js
@@ -10,7 +10,8 @@
*
* @constructor
* @param {Object} [config] Configuration options
- * @cfg {boolean} [disabled=false] Disable
+ * @cfg {boolean} [disabled=false] Disable the widget. Disabled widgets cannot
be used and their
+ * appearance reflects this state.
*/
OO.ui.Widget = function OoUiWidget( config ) {
// Initialize config
@@ -40,11 +41,17 @@
/**
* @event disable
+ *
+ * A 'disable' event is emitted when a widget is disabled.
+ *
* @param {boolean} disabled Widget is disabled
*/
/**
* @event toggle
+ *
+ * A 'toggle' event is emitted when the visibility of the widget changes.
+ *
* @param {boolean} visible Widget is visible
*/
@@ -53,16 +60,16 @@
/**
* Check if the widget is disabled.
*
- * @return {boolean} Button is disabled
+ * @return {boolean} Widget is disabled
*/
OO.ui.Widget.prototype.isDisabled = function () {
return this.disabled;
};
/**
- * Set the disabled state of the widget.
+ * Set the 'disabled' state of the widget.
*
- * This should probably change the widgets' appearance and prevent it from
being used.
+ * When a widget is disabled, it cannot be used and its appearance is updated
to reflect this state.
*
* @param {boolean} disabled Disable widget
* @chainable
--
To view, visit https://gerrit.wikimedia.org/r/196725
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: Ib17c529c338c5393d85fde0cb54398842afe11d9
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] MenuSelectWidget: Clarify description - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/196719
Change subject: MenuSelectWidget: Clarify description
..
MenuSelectWidget: Clarify description
Change-Id: I67a6f17572d3c3a7211bb25a697aea99465fd5d2
---
M src/widgets/MenuSelectWidget.js
1 file changed, 13 insertions(+), 7 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/19/196719/1
diff --git a/src/widgets/MenuSelectWidget.js b/src/widgets/MenuSelectWidget.js
index 24d7e97..a1755ed 100644
--- a/src/widgets/MenuSelectWidget.js
+++ b/src/widgets/MenuSelectWidget.js
@@ -1,8 +1,9 @@
/**
* MenuSelectWidget is a {@link OO.ui.SelectWidget select widget} that
contains options and
- * is used together with OO.ui.MenuOptionWidget. See {@link
OO.ui.DropdownWidget DropdownWidget} and
- * {@link OO.ui.ComboBoxWidget ComboBoxWidget} for examples of interfaces that
contain menus.
- * MenuSelectWidgets themselves are not designed to be instantiated directly,
rather subclassed
+ * is used together with OO.ui.MenuOptionWidget. It is designed be used as
part of another widget.
+ * See {@link OO.ui.DropdownWidget DropdownWidget}, {@link
OO.ui.ComboBoxWidget ComboBoxWidget},
+ * and {@link OO.ui.LookupElement LookupElement} for examples of widgets that
contain menus.
+ * MenuSelectWidgets themselves are not instantiated directly, rather
subclassed
* and customized to be opened, closed, and displayed as needed.
*
* By default, menus are clipped to the visible viewport and are not visible
when a user presses the
@@ -24,9 +25,12 @@
*
* @constructor
* @param {Object} [config] Configuration options
- * @cfg {OO.ui.TextInputWidget} [input] Input to bind keyboard handlers to
- * @cfg {OO.ui.Widget} [widget] Widget to bind mouse handlers to
- * @cfg {boolean} [autoHide=true] Hide the menu when the mouse is pressed
outside the menu
+ * @cfg {OO.ui.TextInputWidget} [input] Text input used to implement option
highlighting for menu items that match
+ * the text the user types. This config is used by {@link
OO.ui.ComboBoxWidget ComboBoxWidget}
+ * and {@link OO.ui.LookupElement LookupElement}
+ * @cfg {OO.ui.Widget} [widget] Widget associated with the menu’s active
state. If the user clicks the mouse
+ * anywhere on the page outside of this widget, the menu is hidden.
+ * @cfg {boolean} [autoHide=true] Hide the menu when the mouse is pressed
outside the menu.
*/
OO.ui.MenuSelectWidget = function OoUiMenuSelectWidget( config ) {
// Configuration initialization
@@ -138,8 +142,10 @@
/**
* Choose an item.
*
- * This will close the menu, unlike #selectItem which only changes selection.
+ * When a user chooses an item, the menu is closed.
*
+ * Note that ‘choose’ should never be modified programmatically. A user can
choose an option with the keyboard
+ * or mouse and it becomes selected. To select an item programmatically, use
the #selectItem method.
* @param {OO.ui.OptionWidget} item Item to choose
* @chainable
*/
--
To view, visit https://gerrit.wikimedia.org/r/196719
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I67a6f17572d3c3a7211bb25a697aea99465fd5d2
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] Window: Clarify descriptions of methods and configs - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/196074
Change subject: Window: Clarify descriptions of methods and configs
..
Window: Clarify descriptions of methods and configs
Change-Id: I259fe8c092561d98411aa1f3e78569666876fe02
---
M src/Window.js
1 file changed, 96 insertions(+), 60 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/74/196074/1
diff --git a/src/Window.js b/src/Window.js
index ec75552..e22c7f9 100644
--- a/src/Window.js
+++ b/src/Window.js
@@ -40,8 +40,8 @@
*
* @constructor
* @param {Object} [config] Configuration options
- * @cfg {string} [size] Symbolic name of dialog size, `small`, `medium`,
`large`, `larger` or
- * `full`; omit to use #static-size
+ * @cfg {string} [size] Symbolic name of the dialog size: `small`, `medium`,
`large`, `larger` or
+ * `full`. If omitted, the value of the {@link #static-size static size}
property will be used.
*/
OO.ui.Window = function OoUiWindow( config ) {
// Configuration initialization
@@ -88,9 +88,9 @@
/* Static Properties */
/**
- * Symbolic name of size.
+ * Symbolic name of the window size: `small`, `medium`, `large`, `larger` or
`full`.
*
- * Size is used if no size is configured during construction.
+ * The static size is used if no #size is configured during construction.
*
* @static
* @inheritable
@@ -103,6 +103,7 @@
/**
* Handle mouse down events.
*
+ * @private
* @param {jQuery.Event} e Mouse down event
*/
OO.ui.Window.prototype.onMouseDown = function ( e ) {
@@ -113,7 +114,7 @@
};
/**
- * Check if window has been initialized.
+ * Check if the window has been initialized.
*
* Initialization occurs when a window is added to a manager.
*
@@ -124,7 +125,7 @@
};
/**
- * Check if window is visible.
+ * Check if the window is visible.
*
* @return {boolean} Window is visible
*/
@@ -133,9 +134,10 @@
};
/**
- * Check if window is opening.
+ * Check if the window is opening.
*
- * This is a wrapper around OO.ui.WindowManager#isOpening.
+ * This method is a wrapper around the window manager's {@link
OO.ui.WindowManager#isOpening isOpening}
+ * method.
*
* @return {boolean} Window is opening
*/
@@ -144,9 +146,9 @@
};
/**
- * Check if window is closing.
+ * Check if the window is closing.
*
- * This is a wrapper around OO.ui.WindowManager#isClosing.
+ * This method is a wrapper around the window manager's {@link
OO.ui.WindowManager#isClosing isClosing} method.
*
* @return {boolean} Window is closing
*/
@@ -155,9 +157,9 @@
};
/**
- * Check if window is opened.
+ * Check if the window is opened.
*
- * This is a wrapper around OO.ui.WindowManager#isOpened.
+ * This method is a wrapper around the window manager's {@link
OO.ui.WindowManager#isOpened isOpened} method.
*
* @return {boolean} Window is opened
*/
@@ -168,6 +170,9 @@
/**
* Get the window manager.
*
+ * All windows must be attached to a window manager, which is used to open
+ * and close the window and control its presentation.
+ *
* @return {OO.ui.WindowManager} Manager of window
*/
OO.ui.Window.prototype.getManager = function () {
@@ -175,9 +180,9 @@
};
/**
- * Get the window size.
+ * Get the symbolic name of the window size (e.g., `small` or `medium`).
*
- * @return {string} Symbolic size name, e.g. `small`, `medium`, `large`,
`larger`, `full`
+ * @return {string} Symbolic name of the size: `small`, `medium`, `large`,
`larger`, `full`
*/
OO.ui.Window.prototype.getSize = function () {
return this.size;
@@ -207,9 +212,16 @@
};
/**
- * Get the height of the dialog contents.
+ * Get the height of the full window contents (i.e., the window head, body and
foot together).
*
- * @return {number} Content height
+ * What consistitutes the head, body, and foot varies depending on the window
type.
+ * A {@link OO.ui.MessageDialog message dialog} displays a title and message
in its body,
+ * and any actions in the foot. A {@link OO.ui.ProcessDialog process dialog}
displays a title
+ * and special actions in the head, and dialog content in the body.
+ *
+ * To get just the height of the dialog body, use the #getBodyHeight method.
+ *
+ * @return {number} The height of the window contents (the dialog head, body
and foot) in pixels
*/
OO.ui.Window.prototype.getContentHeight = function () {
var bodyHeight,
@@ -239,34 +251,42 @@
};
/**
- * Get the height of the dialog contents.
+ * Get the height of the window body.
*
- * When this function is called, the dialog will temporarily have been resized
+ * To get the height of the full window contents (the window body, head, and
foot together),
+ * use #getContentHeight.
+ *
+ * When this function is called, the window will temporarily have been resized
* to height=1px, so .scrollHeight measurements can be taken accurately.
*
- * @return {number} Height of content
+ *
[MediaWiki-commits] [Gerrit] OutlineControlsWidget: Add description - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/196096
Change subject: OutlineControlsWidget: Add description
..
OutlineControlsWidget: Add description
Change-Id: I755a4f56f17639a4c8a0798747b0a09e11a45fd7
---
M src/widgets/OutlineControlsWidget.js
1 file changed, 4 insertions(+), 2 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/96/196096/1
diff --git a/src/widgets/OutlineControlsWidget.js
b/src/widgets/OutlineControlsWidget.js
index 3106cfb..9830149 100644
--- a/src/widgets/OutlineControlsWidget.js
+++ b/src/widgets/OutlineControlsWidget.js
@@ -1,7 +1,7 @@
/**
- * Set of controls for an OO.ui.OutlineSelectWidget.
- *
+ * OutlineControlsWidget is a set of controls for an {@link
OO.ui.OutlineSelectWidget outline select widget}.
* Controls include moving items up and down, removing items, and adding
different kinds of items.
+ * Currently, this class is only used by {@link OO.ui.BookletLayout
BookletLayouts}.
*
* @class
* @extends OO.ui.Widget
@@ -87,6 +87,8 @@
/* Methods */
/**
+ *
+ * @private
* Handle outline change events.
*/
OO.ui.OutlineControlsWidget.prototype.onOutlineChange = function () {
--
To view, visit https://gerrit.wikimedia.org/r/196096
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I755a4f56f17639a4c8a0798747b0a09e11a45fd7
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] OutlineSelectWidget: Add description - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/196093
Change subject: OutlineSelectWidget: Add description
..
OutlineSelectWidget: Add description
Change-Id: I1b89826c98f255d15602718fe6af1e588f135c1a
---
M src/widgets/OutlineSelectWidget.js
1 file changed, 3 insertions(+), 2 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/93/196093/1
diff --git a/src/widgets/OutlineSelectWidget.js
b/src/widgets/OutlineSelectWidget.js
index ac7b542..dd76823 100644
--- a/src/widgets/OutlineSelectWidget.js
+++ b/src/widgets/OutlineSelectWidget.js
@@ -1,7 +1,8 @@
/**
- * Structured list of items.
+ * OutlineSelectWidget is a structured list that contains {@link
OO.ui.OutlineOptionWidget outline options}
+ * A set of controls can be provided with an {@link
OO.ui.OutlineControlsWidget outline controls} widget.
*
- * Use with OO.ui.OutlineOptionWidget.
+ * Currently, this class is only used by {@link OO.ui.BookletLayout
BookletLayouts}.
*
* @class
* @extends OO.ui.SelectWidget
--
To view, visit https://gerrit.wikimedia.org/r/196093
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I1b89826c98f255d15602718fe6af1e588f135c1a
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] InputWidget: Clarify description - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/196127
Change subject: InputWidget: Clarify description
..
InputWidget: Clarify description
Change-Id: Ie969abac04ed3d767e9ae60bd043f0aaf7a96ea3
---
M src/widgets/InputWidget.js
1 file changed, 13 insertions(+), 5 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/27/196127/1
diff --git a/src/widgets/InputWidget.js b/src/widgets/InputWidget.js
index a05a70f..de790ba 100644
--- a/src/widgets/InputWidget.js
+++ b/src/widgets/InputWidget.js
@@ -14,9 +14,10 @@
*
* @constructor
* @param {Object} [config] Configuration options
- * @cfg {string} [name=''] HTML input name
- * @cfg {string} [value=''] Input value
- * @cfg {Function} [inputFilter] Filter function to apply to the input. Takes
a string argument and returns a string.
+ * @cfg {string} [name=''] The value of the input’s HTML `name` attribute.
+ * @cfg {string} [value=''] The value of the input.
+ * @cfg {Function} [inputFilter] The name of an input filter function. Input
filters modify the value of an input
+ * before it is accepted.
*/
OO.ui.InputWidget = function OoUiInputWidget( config ) {
// Configuration initialization
@@ -55,6 +56,9 @@
/**
* @event change
+ *
+ * A change event is emitted when the value of the input changes.
+ *
* @param {string} value
*/
@@ -77,6 +81,7 @@
/**
* Handle potentially value-changing events.
*
+ * @private
* @param {jQuery.Event} e Key down, mouse up, cut, paste, change, input, or
select event
*/
OO.ui.InputWidget.prototype.onEdit = function () {
@@ -105,9 +110,10 @@
};
/**
- * Sets the direction of the current input, either RTL or LTR
+ * Set the direction of the input, either RTL (right-to-left) or LTR
(left-to-right).
*
* @param {boolean} isRTL
+ * Direction is right-to-left
*/
OO.ui.InputWidget.prototype.setRTL = function ( isRTL ) {
this.$input.prop( 'dir', isRTL ? 'rtl' : 'ltr' );
@@ -154,7 +160,9 @@
};
/**
- * Simulate the behavior of clicking on a label bound to this input.
+ * Simulate the behavior of clicking on a label bound to this input. This
method is only called by
+ * {@link OO.ui.LabelWidget LabelWidget} and {@link OO.ui.FieldLayout
FieldLayout}. It should not be
+ * called directly.
*/
OO.ui.InputWidget.prototype.simulateLabelClick = function () {
if ( !this.isDisabled() ) {
--
To view, visit https://gerrit.wikimedia.org/r/196127
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: Ie969abac04ed3d767e9ae60bd043f0aaf7a96ea3
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] ActionSet: Clarify description: - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/196118
Change subject: ActionSet: Clarify description:
..
ActionSet: Clarify description:
Change-Id: Id9844f58b658deb5844a8dfcb74e62a514ce13c5
---
M src/ActionSet.js
1 file changed, 1 insertion(+), 1 deletion(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/18/196118/1
diff --git a/src/ActionSet.js b/src/ActionSet.js
index ef79e7a..a011cbe 100644
--- a/src/ActionSet.js
+++ b/src/ActionSet.js
@@ -1,7 +1,7 @@
/**
* ActionSets manage the behavior of the {@link OO.ui.ActionWidget action
widgets} that comprise them.
* Actions can be made available for specific contexts (modes) and
circumstances
- * (abilities).
+ * (abilities). Action sets are primarily used with {@link OO.ui.Dialog
Dialogs}.
*
* ActionSets contain two types of actions:
*
--
To view, visit https://gerrit.wikimedia.org/r/196118
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: Id9844f58b658deb5844a8dfcb74e62a514ce13c5
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] ActionWidget: Clarify description and mark private method - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/196112
Change subject: ActionWidget: Clarify description and mark private method
..
ActionWidget: Clarify description and mark private method
Change-Id: I79d7a82014a643eb2c92a689b0f71cca8999c76f
---
M src/widgets/ActionWidget.js
1 file changed, 21 insertions(+), 9 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/12/196112/1
diff --git a/src/widgets/ActionWidget.js b/src/widgets/ActionWidget.js
index 67bf368..789f04f 100644
--- a/src/widgets/ActionWidget.js
+++ b/src/widgets/ActionWidget.js
@@ -1,7 +1,10 @@
/**
* An ActionWidget is a {@link OO.ui.ButtonWidget button widget} that executes
an action.
* Action widgets are used with OO.ui.ActionSet, which manages the behavior
and availability
- * of the actions. Please see the [OOjs UI documentation on MediaWiki] [1] for
more information
+ * of the actions.
+ *
+ * Both actions and action sets are primarily used with {@link OO.ui.Dialog
Dialogs}.
+ * Please see the [OOjs UI documentation on MediaWiki] [1] for more information
* and examples.
*
* [1]:
https://www.mediawiki.org/wiki/OOjs_UI/Windows/Process_Dialogs#Action_sets
@@ -12,9 +15,11 @@
*
* @constructor
* @param {Object} [config] Configuration options
- * @cfg {string} [action] Symbolic action name
- * @cfg {string[]} [modes] Symbolic mode names
- * @cfg {boolean} [framed=false] Render button with a frame
+ * @cfg {string} [action] Symbolic name of the action (e.g., ‘continue’ or
‘cancel’).
+ * @cfg {string[]} [modes] Symbolic names of the modes (e.g., ‘edit’ or
‘read’) in which the action
+ * should be made available. See the action set's {@link
OO.ui.ActionSet#setMode setMode} method
+ * for more information about setting modes.
+ * @cfg {boolean} [framed=false] Render the action button with a frame
*/
OO.ui.ActionWidget = function OoUiActionWidget( config ) {
// Configuration initialization
@@ -44,23 +49,25 @@
/* Events */
/**
+ * A resize event is emitted when the size of the widget changes.
+ *
* @event resize
*/
/* Methods */
/**
- * Check if action is available in a certain mode.
+ * Check if the action is configured to be available in the specified `mode`.
*
* @param {string} mode Name of mode
- * @return {boolean} Has mode
+ * @return {boolean} The action is configured with the mode
*/
OO.ui.ActionWidget.prototype.hasMode = function ( mode ) {
return this.modes.indexOf( mode ) !== -1;
};
/**
- * Get symbolic action name.
+ * Get the symbolic name of the action (e.g., ‘continue’ or ‘cancel’).
*
* @return {string}
*/
@@ -69,7 +76,11 @@
};
/**
- * Get symbolic mode names.
+ * Get the symbolic name of the mode or modes for which the action is
configured to be available.
+ *
+ * The current mode is set with the action set's {@link
OO.ui.ActionSet#setMode setMode} method.
+ * Only actions that are configured to be avaiable in the current mode will be
visible. All other actions
+ * are hidden.
*
* @return {string[]}
*/
@@ -80,6 +91,7 @@
/**
* Emit a resize event if the size has changed.
*
+ * @private
* @chainable
*/
OO.ui.ActionWidget.prototype.propagateResize = function () {
@@ -144,7 +156,7 @@
};
/**
- * Toggle visibility of button.
+ * Toggle the visibility of the action button.
*
* @param {boolean} [show] Show button, omit to toggle visibility
* @chainable
--
To view, visit https://gerrit.wikimedia.org/r/196112
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I79d7a82014a643eb2c92a689b0f71cca8999c76f
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] ButtonInputWidget: Clarify description of configs and methods - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/195319
Change subject: ButtonInputWidget: Clarify description of configs and methods
..
ButtonInputWidget: Clarify description of configs and methods
Change-Id: I8e6df894c81c95b6d0e4294834fbe3eff338501d
---
M src/widgets/ButtonInputWidget.js
1 file changed, 10 insertions(+), 9 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/19/195319/1
diff --git a/src/widgets/ButtonInputWidget.js b/src/widgets/ButtonInputWidget.js
index 9777699..bda5b18 100644
--- a/src/widgets/ButtonInputWidget.js
+++ b/src/widgets/ButtonInputWidget.js
@@ -27,11 +27,11 @@
*
* @constructor
* @param {Object} [config] Configuration options
- * @cfg {string} [type='button'] HTML tag `type` attribute, may be 'button',
'submit' or 'reset'
- * @cfg {boolean} [useInputTag=false] Whether to use `input/` rather than
`button/`. Only useful
- * if you need IE 6 support in a form with multiple buttons. If you use this
option, icons and
- * indicators will not be displayed, it won't be possible to have a
non-plaintext label, and it
- * won't be possible to set a value (which will internally become identical
to the label).
+ * @cfg {string} [type='button'] The value of the HTML `'type'` attribute:
'button', 'submit' or 'reset'.
+ * @cfg {boolean} [useInputTag=false] Use an `input/` tag instead of a
`button/` tag, the default.
+ * Widgets configured to be an `input/` do not support {@link #icon icons}
and {@link #indicator indicators},
+ * non-plaintext {@link #label labels}, or {@link #value values}. In general,
useInputTag should only
+ * be set to `true` when there’s need to support IE6 in a form with multiple
buttons.
*/
OO.ui.ButtonInputWidget = function OoUiButtonInputWidget( config ) {
// Configuration initialization
@@ -82,10 +82,10 @@
/**
* Set label value.
*
- * Overridden to support setting the 'value' of `input/` elements.
+ * If #useInputTag is `true`, the label is set as the `value` of the
`input/` tag.
*
- * @param {jQuery|string|Function|null} label Label nodes; text; a function
that returns nodes or
- * text; or null for no label
+ * @param {jQuery|string|Function|null} label Label nodes, text, a function
that returns nodes or
+ * text, or `null` for no label
* @chainable
*/
OO.ui.ButtonInputWidget.prototype.setLabel = function ( label ) {
@@ -110,7 +110,8 @@
/**
* Set the value of the input.
*
- * Overridden to disable for `input/` elements, which have value identical
to the label.
+ * This method is disabled for button inputs configured as {@link #useInputTag
input/ tags}, as
+ * they do not support {@link #value values}.
*
* @param {string} value New value
* @chainable
--
To view, visit https://gerrit.wikimedia.org/r/195319
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I8e6df894c81c95b6d0e4294834fbe3eff338501d
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] ActionSet: Add description for events and clarify method des... - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/195489
Change subject: ActionSet: Add description for events and clarify method
descriptions
..
ActionSet: Add description for events and clarify method descriptions
Change-Id: I5a6a80e587afe71c38a47d998a506f2b48a33e34
---
M src/ActionSet.js
1 file changed, 63 insertions(+), 33 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/89/195489/1
diff --git a/src/ActionSet.js b/src/ActionSet.js
index 1d23999..148976f 100644
--- a/src/ActionSet.js
+++ b/src/ActionSet.js
@@ -1,7 +1,14 @@
/**
- * ActionSets manage the behavior of the {@link OO.ui.ActionWidget Action
widgets} that comprise them.
+ * ActionSets manage the behavior of the {@link OO.ui.ActionWidget action
widgets} that comprise them.
* Actions can be made available for specific contexts (modes) and
circumstances
- * (abilities). Please see the [OOjs UI documentation on MediaWiki][1] for
more information.
+ * (abilities).
+ *
+ * ActionSets contain two types of actions:
+ *
+ * - Special: Special actions are the first visible actions with special
flags, such as 'safe' and 'primary', the default special flags. Additional
special flags can be configured in subclasses with the static #specialFlags
property.
+ * - Other: Other actions include all non-special visible actions.
+ *
+ * Please see the [OOjs UI documentation on MediaWiki][1] for more information.
*
* @example
* // Example: An action set used in a process dialog
@@ -115,26 +122,43 @@
/**
* @event click
+ *
+ * A 'click' event is emitted when an action is clicked.
+ *
* @param {OO.ui.ActionWidget} action Action that was clicked
*/
/**
* @event resize
+ *
+ * A 'resize' event is emitted when an action widget is resized.
+ *
* @param {OO.ui.ActionWidget} action Action that was resized
*/
/**
* @event add
+ *
+ * An 'add' event is emitted when actions are added to the action set.
+ *
* @param {OO.ui.ActionWidget[]} added Actions added
*/
/**
* @event remove
+ *
+ * A 'remove' event is emitted when actions are {@link #remove removed}
+ * or {@link #clear cleared}.
+ *
* @param {OO.ui.ActionWidget[]} added Actions removed
*/
/**
* @event change
+ *
+ * A 'change' event is emitted when actions are added, cleared, or removed
from the
+ * action set or when the {@link #setMode mode} is changed.
+ *
*/
/* Methods */
@@ -155,7 +179,7 @@
};
/**
- * Check if a action is one of the special actions.
+ * Check if an action is one of the special actions.
*
* @param {OO.ui.ActionWidget} action Action to check
* @return {boolean} Action is special
@@ -173,15 +197,16 @@
};
/**
- * Get actions.
+ * Get action widgets based on the specified filter: ‘actions’, ‘flags’,
‘modes’, ‘visible’,
+ * or ‘disabled’.
*
* @param {Object} [filters] Filters to use, omit to get all actions
- * @param {string|string[]} [filters.actions] Actions that actions must have
- * @param {string|string[]} [filters.flags] Flags that actions must have
- * @param {string|string[]} [filters.modes] Modes that actions must have
- * @param {boolean} [filters.visible] Actions must be visible
- * @param {boolean} [filters.disabled] Actions must be disabled
- * @return {OO.ui.ActionWidget[]} Actions matching all criteria
+ * @param {string|string[]} [filters.actions] Actions that action widgets must
have
+ * @param {string|string[]} [filters.flags] Flags that action widgets must
have (e.g., 'safe')
+ * @param {string|string[]} [filters.modes] Modes that action widgets must have
+ * @param {boolean} [filters.visible] Action widgets must be visible
+ * @param {boolean} [filters.disabled] Action widgets must be disabled
+ * @return {OO.ui.ActionWidget[]} Action widgets matching all criteria
*/
OO.ui.ActionSet.prototype.get = function ( filters ) {
var i, len, list, category, actions, index, match, matches;
@@ -233,12 +258,12 @@
};
/**
- * Get special actions.
+ * Get 'special' actions.
*
- * Special actions are the first visible actions with special flags, such as
'safe' and 'primary'.
- * Special flags can be configured by changing #static-specialFlags in a
subclass.
+ * Special actions are the first visible action widgets with special flags,
such as 'safe' and 'primary'.
+ * Special flags can be configured in subclasses by changing the static
#specialFlags property.
*
- * @return {OO.ui.ActionWidget|null} Safe action
+ * @return {OO.ui.ActionWidget[]|null} 'Special' action widgets.
*/
OO.ui.ActionSet.prototype.getSpecial = function () {
this.organize();
@@ -246,11 +271,11 @@
};
/**
- * Get other actions.
+ * Get 'other' actions.
*
- * Other actions include all non-special visible actions.
+ * Other actions include all non-special visible action widgets.
*
- * @return {OO.ui.ActionWidget[]} Other actions
+ * @return {OO.ui.ActionWidget[]}
[MediaWiki-commits] [Gerrit] TextInputMenuSelectWidget: Add description and mark private ... - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/194983
Change subject: TextInputMenuSelectWidget: Add description and mark private
methods
..
TextInputMenuSelectWidget: Add description and mark private methods
Change-Id: I686553574e6f0aca3279d4d8acad49d86ee3f0db
---
M src/widgets/TextInputMenuSelectWidget.js
1 file changed, 6 insertions(+), 4 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/83/194983/1
diff --git a/src/widgets/TextInputMenuSelectWidget.js
b/src/widgets/TextInputMenuSelectWidget.js
index 6bc4927..6b971e8 100644
--- a/src/widgets/TextInputMenuSelectWidget.js
+++ b/src/widgets/TextInputMenuSelectWidget.js
@@ -1,8 +1,8 @@
/**
- * Menu for a text input widget.
- *
- * This menu is specially designed to be positioned beneath a text input
widget. The menu's position
- * is automatically calculated and maintained when the menu is toggled or the
window is resized.
+ * TextInputMenuSelectWidget is a menu that is specially designed to be
positioned beneath
+ * a {@link OO.ui.TextInputWidget text input} field. The menu's position is
automatically
+ * calculated and maintained when the menu is toggled or the window is resized.
+ * See OO.ui.ComboBoxWidget for an example of a widget that uses this class.
*
* @class
* @extends OO.ui.MenuSelectWidget
@@ -43,6 +43,7 @@
/**
* Handle window resize event.
*
+ * @private
* @param {jQuery.Event} e Window resize event
*/
OO.ui.TextInputMenuSelectWidget.prototype.onWindowResize = function () {
@@ -82,6 +83,7 @@
/**
* Position the menu.
*
+ * @private
* @chainable
*/
OO.ui.TextInputMenuSelectWidget.prototype.position = function () {
--
To view, visit https://gerrit.wikimedia.org/r/194983
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I686553574e6f0aca3279d4d8acad49d86ee3f0db
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] Dialog: Mark private methods and add description of methods ... - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/194906
Change subject: Dialog: Mark private methods and add description of methods and
configs
..
Dialog: Mark private methods and add description of methods and configs
Change-Id: Ia9fcfd46aaac97809c54173a6823abdd53d3ef3c
---
M src/Dialog.js
1 file changed, 31 insertions(+), 8 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/06/194906/1
diff --git a/src/Dialog.js b/src/Dialog.js
index ddf63b9..65c13cd 100644
--- a/src/Dialog.js
+++ b/src/Dialog.js
@@ -76,6 +76,11 @@
/**
* Symbolic name of dialog.
*
+ * The dialog class must have a symbolic name in order to be registered with
OO.Factory.
+ * Please see the [OOjs UI documentation on MediaWiki] [3] for more
information.
+ *
+ * [3]: https://www.mediawiki.org/wiki/OOjs_UI/Windows/Window_managers
+ *
* @abstract
* @static
* @inheritable
@@ -84,26 +89,35 @@
OO.ui.Dialog.static.name = '';
/**
- * Dialog title.
+ * The dialog title.
+ *
+ * The title can be specified as a plaintext string, a {@link
OO.ui.LabelElement Label} node, or a function
+ * that will produce a Label node or string. The title can also be specified
with data passed to the
+ * constructor (see #getSetupProcess). In this case, the static value will be
overriden.
*
* @abstract
* @static
* @inheritable
- * @property {jQuery|string|Function} Label nodes, text or a function that
returns nodes or text
+ * @property {jQuery|string|Function}
*/
OO.ui.Dialog.static.title = '';
/**
- * List of OO.ui.ActionWidget configuration options.
+ * An array of configured {@link OO.ui.ActionWidget action widgets}.
+ *
+ * Actions can also be specified with data passed to the constructor (see
#getSetupProcess). In this case, the static
+ * value will be overriden.
+ *
+ * [2]:
https://www.mediawiki.org/wiki/OOjs_UI/Windows/Process_Dialogs#Action_sets
*
* @static
- * inheritable
+ * @inheritable
* @property {Object[]}
*/
OO.ui.Dialog.static.actions = [];
/**
- * Close dialog when the escape key is pressed.
+ * Close the dialog when the 'Esc' key is pressed.
*
* @static
* @abstract
@@ -117,6 +131,7 @@
/**
* Handle frame document key down events.
*
+ * @private
* @param {jQuery.Event} e Key down event
*/
OO.ui.Dialog.prototype.onDocumentKeyDown = function ( e ) {
@@ -130,6 +145,7 @@
/**
* Handle action resized events.
*
+ * @private
* @param {OO.ui.ActionWidget} action Action that was resized
*/
OO.ui.Dialog.prototype.onActionResize = function () {
@@ -139,6 +155,7 @@
/**
* Handle action click events.
*
+ * @private
* @param {OO.ui.ActionWidget} action Action that was clicked
*/
OO.ui.Dialog.prototype.onActionClick = function ( action ) {
@@ -149,6 +166,8 @@
/**
* Handle actions change event.
+ *
+ * @private
*/
OO.ui.Dialog.prototype.onActionsChange = function () {
this.detachActions();
@@ -158,7 +177,7 @@
};
/**
- * Get set of actions.
+ * Get the set of actions used by the dialog.
*
* @return {OO.ui.ActionSet}
*/
@@ -169,8 +188,9 @@
/**
* Get a process for taking action.
*
- * When you override this method, you can add additional accept steps to the
process the parent
- * method provides using the 'first' and 'next' methods.
+ * When you override this method, you can create a new OO.ui.Process and
return it, or add additional
+ * accept steps to the process the parent method provides using the {@link
OO.ui.Process#first 'first'}
+ * and {@link OO.ui.Process#next 'next'} methods of OO.ui.Process.
*
* @abstract
* @param {string} [action] Symbolic name of action
@@ -255,6 +275,8 @@
/**
* Attach action actions.
+ *
+ * @protected
*/
OO.ui.Dialog.prototype.attachActions = function () {
// Remember the list of potentially attached actions
@@ -264,6 +286,7 @@
/**
* Detach action actions.
*
+ * @protected
* @chainable
*/
OO.ui.Dialog.prototype.detachActions = function () {
--
To view, visit https://gerrit.wikimedia.org/r/194906
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: Ia9fcfd46aaac97809c54173a6823abdd53d3ef3c
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] ProcessDialog: Add description and example and mark private ... - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/194923
Change subject: ProcessDialog: Add description and example and mark private
methods
..
ProcessDialog: Add description and example and mark private methods
Change-Id: I3edcb29cf4f228435290fc2f6806b8a1fbe040f1
---
M src/dialogs/ProcessDialog.js
1 file changed, 56 insertions(+), 14 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/23/194923/1
diff --git a/src/dialogs/ProcessDialog.js b/src/dialogs/ProcessDialog.js
index 9b0566f..2863e19 100644
--- a/src/dialogs/ProcessDialog.js
+++ b/src/dialogs/ProcessDialog.js
@@ -1,21 +1,55 @@
/**
- * Navigation dialog window.
+ * ProcessDialog windows encapsulate a {@link OO.ui.Process process} and all
of the code necessary
+ * to complete it. If the process terminates with an error, a customizable
{@link OO.ui.Error error
+ * interface} alerts users to the trouble, permitting the user to dismiss the
error and try again when
+ * relevant. The ProcessDialog class is always extended and customized with
the actions and content
+ * required for each process.
*
- * Logic:
- * - Show and hide errors.
- * - Retry an action.
+ * The process dialog box consists of a header that visually represents the
‘working’ state of long
+ * processes with an animation. The header contains the dialog title as well as
+ * two {@link OO.ui.ActionWidget action widgets}: a ‘safe’ action on the left
(e.g., ‘Cancel’) and
+ * a ‘primary’ action on the right (e.g., ‘Done’).
*
- * User interface:
- * - Renders header with dialog title and one action widget on either side
- * (a 'safe' button on the left, and a 'primary' button on the right, both of
- * which close the dialog).
- * - Displays any action widgets in the footer (none by default).
- * - Ability to dismiss errors.
+ * Like other windows, the process dialog is managed by a {@link
OO.ui.WindowManager window manager}.
+ * Please see the [OOjs UI documentation on MediaWiki][1] for more information
and examples.
*
- * Subclass responsibilities:
- * - Register a 'safe' action.
- * - Register a 'primary' action.
- * - Add content to the dialog.
+ * @example
+ * // Example: Creating and opening a process dialog window.
+ * function ProcessDialog( config ) {
+ * ProcessDialog.super.call( this, config );
+ * }
+ * OO.inheritClass( ProcessDialog, OO.ui.ProcessDialog );
+ *
+ * ProcessDialog.static.title = 'Process dialog';
+ * ProcessDialog.static.actions = [
+ * { action: 'save', label: 'Done', flags: 'primary' },
+ * { label: 'Cancel', flags: 'safe' }
+ * ];
+ *
+ * ProcessDialog.prototype.initialize = function () {
+ * ProcessDialog.super.prototype.initialize.apply( this, arguments );
+ * this.content = new OO.ui.PanelLayout( { $: this.$, padded: true,
expanded: false } );
+ * this.content.$element.append( 'pThis is a process dialog window.
The header contains the title and two buttons: \'Cancel\' (a safe action) on
the left and \'Done\' (a primary action) on the right. /p' );
+ * this.$body.append( this.content.$element );
+ * };
+ * ProcessDialog.prototype.getActionProcess = function ( action ) {
+ * var dialog = this;
+ * if ( action ) {
+ * return new OO.ui.Process( function () {
+ * dialog.close( { action: action } );
+ * } );
+ * }
+ * return ProcessDialog.super.prototype.getActionProcess.call( this,
action );
+ * };
+ *
+ * var windowManager = new OO.ui.WindowManager();
+ * $( 'body' ).append( windowManager.$element );
+ *
+ * var processDialog = new ProcessDialog();
+ * windowManager.addWindows( [ processDialog ] );
+ * windowManager.openWindow( processDialog );
+ *
+ * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Windows/Process_Dialogs
*
* @abstract
* @class
@@ -42,6 +76,8 @@
* Handle dismiss button click events.
*
* Hides errors.
+ *
+ * @private
*/
OO.ui.ProcessDialog.prototype.onDismissErrorButtonClick = function () {
this.hideErrors();
@@ -51,6 +87,8 @@
* Handle retry button click events.
*
* Hides errors and then tries again.
+ *
+ * @private
*/
OO.ui.ProcessDialog.prototype.onRetryButtonClick = function () {
this.hideErrors();
@@ -155,6 +193,7 @@
/**
* Fit label between actions.
*
+ * @private
* @chainable
*/
OO.ui.ProcessDialog.prototype.fitLabel = function () {
@@ -170,6 +209,7 @@
/**
* Handle errors that occurred during accept or reject processes.
*
+ * @private
* @param {OO.ui.Error[]} errors Errors to be handled
*/
OO.ui.ProcessDialog.prototype.showErrors = function ( errors ) {
@@ -215,6 +255,8 @@
/**
* Hide errors.
+ *
+ * @private
*/
OO.ui.ProcessDialog.prototype.hideErrors = function () {
this.$errors.addClass( 'oo-ui-element-hidden' );
--
To view, visit
[MediaWiki-commits] [Gerrit] MessageDialog: Add description, example, and mark private me... - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/194942
Change subject: MessageDialog: Add description, example, and mark private
methods
..
MessageDialog: Add description, example, and mark private methods
Change-Id: Iecc7f4f77eeb560229a208bcad8ec425c167895c
---
M src/dialogs/MessageDialog.js
1 file changed, 46 insertions(+), 10 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/42/194942/1
diff --git a/src/dialogs/MessageDialog.js b/src/dialogs/MessageDialog.js
index 0f24aeb..4ec1261 100644
--- a/src/dialogs/MessageDialog.js
+++ b/src/dialogs/MessageDialog.js
@@ -1,9 +1,37 @@
/**
- * Dialog for showing a message.
+ * MessageDialogs display a confirmation or alert message. By default, the
rendered dialog box
+ * consists of a header that contains the dialog title, a body with the
message, and a footer that
+ * contains any {@link OO.ui.ActionWidget action widgets}. The MessageDialog
class is the only type
+ * of {@link OO.ui.Dialog dialog} that is usually instantiated directly.
*
- * User interface:
- * - Registers two actions by default (safe and primary).
- * - Renders action widgets in the footer.
+ * There are two basic types of message dialogs, confirmation and alert:
+ *
+ * - **confirmation**: the dialog title describes what a progressive action
will do and the message provides
+ * more details about the consequences.
+ * - **alert**: the dialog title describes which event occurred and the
message provides more information
+ * about why the event occurred.
+ *
+ * The MessageDialog class specifies two actions: ‘accept’, the primary
+ * action (e.g., ‘ok’) and ‘reject,’ the safe action (e.g., ‘cancel’). Both
will close the window,
+ * passing along the selected action.
+ *
+ * For more information and examples, please see the [OOjs UI documentation on
MediaWiki][1].
+ *
+ * @example
+ * // Example: Creating and opening a message dialog window.
+ * var messageDialog = new OO.ui.MessageDialog();
+ *
+ * // Create and append a window manager.
+ * var windowManager = new OO.ui.WindowManager();
+ * $( 'body' ).append( windowManager.$element );
+ * windowManager.addWindows( [ messageDialog ] );
+ * // Open the window.
+ * windowManager.openWindow( messageDialog, {
+ * title: 'Basic message dialog',
+ * message: 'This is the message'
+ * } );
+ *
+ * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Windows/Message_Dialogs
*
* @class
* @extends OO.ui.Dialog
@@ -37,21 +65,23 @@
/**
* Dialog title.
*
- * A confirmation dialog's title should describe what the progressive action
will do. An alert
- * dialog's title should describe what event occurred.
+ * The title of a confirmation dialog describes what a progressive action will
do. The
+ * title of an alert dialog describes which event occurred.
*
* @static
- * inheritable
+ * @inheritable
* @property {jQuery|string|Function|null}
*/
OO.ui.MessageDialog.static.title = null;
/**
- * A confirmation dialog's message should describe the consequences of the
progressive action. An
- * alert dialog's message should describe why the event occurred.
+ * The message displayed in the dialog body.
+ *
+ * A confirmation message describes the consequences of a progressive action.
An alert
+ * message describes why an event occurred.
*
* @static
- * inheritable
+ * @inheritable
* @property {jQuery|string|Function|null}
*/
OO.ui.MessageDialog.static.message = null;
@@ -87,6 +117,8 @@
/**
* Handle window resized events.
+ *
+ * @private
*/
OO.ui.MessageDialog.prototype.onResize = function () {
var dialog = this;
@@ -100,6 +132,8 @@
/**
* Toggle action layout between vertical and horizontal.
*
+ *
+ * @private
* @param {boolean} [value] Layout actions vertically, omit to toggle
* @chainable
*/
@@ -263,6 +297,8 @@
* Fit action actions into columns or rows.
*
* Columns will be used if all labels can fit without overflow, otherwise rows
will be used.
+ *
+ * @private
*/
OO.ui.MessageDialog.prototype.fitActions = function () {
var i, len, action,
--
To view, visit https://gerrit.wikimedia.org/r/194942
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: Iecc7f4f77eeb560229a208bcad8ec425c167895c
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] ComboBoxWidget: Add description, example, and mark private m... - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/194372
Change subject: ComboBoxWidget: Add description, example, and mark private
methods
..
ComboBoxWidget: Add description, example, and mark private methods
Change-Id: I3eaada60137aa790d50e63daf7a6daf58bd91a4f
---
M src/widgets/ComboBoxWidget.js
1 file changed, 54 insertions(+), 4 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/72/194372/1
diff --git a/src/widgets/ComboBoxWidget.js b/src/widgets/ComboBoxWidget.js
index 3c9b555..f9920b3 100644
--- a/src/widgets/ComboBoxWidget.js
+++ b/src/widgets/ComboBoxWidget.js
@@ -1,5 +1,43 @@
/**
- * Text input with a menu of optional values.
+ * ComboBoxWidgets combine a {@link OO.ui.TextInputWidget text input} (where a
value
+ * can be entered manually) and a {@link OO.ui.MenuSelectWidget menu of
options} (from which
+ * a value can be chosen instead). Users can choose options from the combo box
in one of two ways:
+ *
+ * - by typing a value in the text input field. If the value exactly matches
the value of a menu
+ * option, that option will appear to be selected.
+ * - by choosing a value from the menu. The value of the chosen option will
then appear in the text
+ * input field.
+ *
+ * For more information about menus and options, please see the [OOjs UI
documentation on MediaWiki][1].
+ *
+ * @example
+ * // Example: A ComboBoxWidget.
+ * var comboBox=new OO.ui.ComboBoxWidget( {
+ * label: 'ComboBoxWidget',
+ * input: { value: 'Option One' },
+ * menu: {
+ * items: [
+ * new OO.ui.MenuOptionWidget( {
+ * data: 'Option 1',
+ * label: 'Option One' } ),
+ * new OO.ui.MenuOptionWidget( {
+ * data: 'Option 2',
+ * label: 'Option Two' } ),
+ * new OO.ui.MenuOptionWidget( {
+ * data: 'Option 3',
+ * label: 'Option Three'} ),
+ * new OO.ui.MenuOptionWidget( {
+ * data: 'Option 4',
+ * label: 'Option Four' } ),
+ * new OO.ui.MenuOptionWidget( {
+ * data: 'Option 5',
+ * label: 'Option Five' } )
+ * ]
+ * }
+ * } );
+ * $('body').append(comboBox.$element);
+ *
+ * [1]:
https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Menu_selects_and_options
*
* @class
* @extends OO.ui.Widget
@@ -7,9 +45,11 @@
*
* @constructor
* @param {Object} [config] Configuration options
- * @cfg {Object} [menu] Configuration options to pass to menu widget
- * @cfg {Object} [input] Configuration options to pass to input widget
- * @cfg {jQuery} [$overlay] Overlay layer; defaults to relative positioning
+ * @cfg {Object} [menu] Configuration options to pass to the {@link
OO.ui.MenuSelectWidget menu select widget}.
+ * @cfg {Object} [input] Configuration options to pass to the {@link
OO.ui.TextInputWidget text input widget}.
+ * @cfg {jQuery} [$overlay] Render the menu into a separate layer. This
configuration is useful in cases where
+ * the expanded menu is larger than its containing `div`. The specified
overlay layer is usually on top of the
+ * containing `div` and has a larger area. By default, the menu uses
relative positioning.
*/
OO.ui.ComboBoxWidget = function OoUiComboBoxWidget( config ) {
// Configuration initialization
@@ -86,6 +126,7 @@
/**
* Handle input change events.
*
+ * @private
* @param {string} value New value
*/
OO.ui.ComboBoxWidget.prototype.onInputChange = function ( value ) {
@@ -104,6 +145,8 @@
/**
* Handle mouse click events.
*
+ *
+ * @private
* @param {jQuery.Event} e Mouse click event
*/
OO.ui.ComboBoxWidget.prototype.onClick = function ( e ) {
@@ -117,6 +160,8 @@
/**
* Handle key press events.
*
+ *
+ * @private
* @param {jQuery.Event} e Key press event
*/
OO.ui.ComboBoxWidget.prototype.onKeyPress = function ( e ) {
@@ -129,6 +174,8 @@
/**
* Handle input enter events.
+ *
+ * @private
*/
OO.ui.ComboBoxWidget.prototype.onInputEnter = function () {
if ( !this.isDisabled() ) {
@@ -139,6 +186,7 @@
/**
* Handle menu choose events.
*
+ * @private
* @param {OO.ui.OptionWidget} item Chosen item
*/
OO.ui.ComboBoxWidget.prototype.onMenuChoose = function ( item ) {
@@ -149,6 +197,8 @@
/**
* Handle menu item change events.
+ *
+ * @private
*/
OO.ui.ComboBoxWidget.prototype.onMenuItemsChange = function () {
var match = this.menu.getItemFromData( this.input.getValue() );
--
To view, visit https://gerrit.wikimedia.org/r/194372
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I3eaada60137aa790d50e63daf7a6daf58bd91a4f
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
[MediaWiki-commits] [Gerrit] DecoratedOptionWidget: Add description and example - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/194381
Change subject: DecoratedOptionWidget: Add description and example
..
DecoratedOptionWidget: Add description and example
Change-Id: I58784524c0be7853140c6245e8f685ecf4d1612c
---
M src/widgets/DecoratedOptionWidget.js
1 file changed, 24 insertions(+), 2 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/81/194381/1
diff --git a/src/widgets/DecoratedOptionWidget.js
b/src/widgets/DecoratedOptionWidget.js
index 9fd8ee8..ca5acb6 100644
--- a/src/widgets/DecoratedOptionWidget.js
+++ b/src/widgets/DecoratedOptionWidget.js
@@ -1,7 +1,29 @@
/**
- * Option widget with an option icon and indicator.
+ * DecoratedOptionWidgets are {@link OO.ui.OptionWidget options} that can be
configured
+ * with an {@link OO.ui.IconElement icon} and/or {@link OO.ui.IndicatorElement
indicator}.
+ * This class is used with OO.ui.SelectWidget to create a selection of
mutually exclusive
+ * options. For more information about options and selects, please see the
+ * [OOjs UI documentation on MediaWiki][1].
*
- * Use together with OO.ui.SelectWidget.
+ * @example
+ * // Decorated options in a select widget
+ * var select=new OO.ui.SelectWidget( {
+ * items: [
+ * new OO.ui.DecoratedOptionWidget( {
+ * data: 'a',
+ * label: 'Option with icon',
+ * icon: 'help'
+ * } ),
+ * new OO.ui.DecoratedOptionWidget( {
+ * data: 'b',
+ * label: 'Option with indicator',
+ * indicator: 'next'
+ * } )
+ * ]
+ * } );
+ * $('body').append(select.$element);
+ *
+ * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
*
* @class
* @extends OO.ui.OptionWidget
--
To view, visit https://gerrit.wikimedia.org/r/194381
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I58784524c0be7853140c6245e8f685ecf4d1612c
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] DropdownInputWidget: Add description, example, and mark priv... - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/194363
Change subject: DropdownInputWidget: Add description, example, and mark private
method
..
DropdownInputWidget: Add description, example, and mark private method
Change-Id: I6376a7f22346b67b74d412a42addec84ea7970dd
---
M src/widgets/DropdownInputWidget.js
1 file changed, 19 insertions(+), 2 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/63/194363/1
diff --git a/src/widgets/DropdownInputWidget.js
b/src/widgets/DropdownInputWidget.js
index 793d866..3ed83ed 100644
--- a/src/widgets/DropdownInputWidget.js
+++ b/src/widgets/DropdownInputWidget.js
@@ -1,6 +1,22 @@
/**
- * A OO.ui.DropdownWidget synchronized with a `input type=hidden` for form
submission. Intended to
- * be used within a OO.ui.FormLayout.
+ * DropdownInputWidget is a {@link OO.ui.DropdownWidget DropdownWidget}
intended to be used
+ * within a {@link OO.ui.FormLayout form}. The selected value is synchronized
with the value
+ * of a hidden HTML `input` tag. Please see the [OOjs UI documentation on
MediaWiki][1] for
+ * more information about input widgets.
+ *
+ * @example
+ * // Example: A DropdownInputWidget with three options
+ * var dropDown=new OO.ui.DropdownInputWidget( {
+ * label: 'Dropdown menu: Select a menu option',
+ * options: [
+ * { data: 'a', label: 'First' } ,
+ * { data: 'b', label: 'Second'} ,
+ * { data: 'c', label: 'Third' }
+ * ]
+ * } );
+ * $('body').append(dropDown.$element);
+ *
+ * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
*
* @class
* @extends OO.ui.InputWidget
@@ -46,6 +62,7 @@
/**
* Handles menu select events.
*
+ * @private
* @param {OO.ui.MenuOptionWidget} item Selected menu item
*/
OO.ui.DropdownInputWidget.prototype.onMenuSelect = function ( item ) {
--
To view, visit https://gerrit.wikimedia.org/r/194363
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I6376a7f22346b67b74d412a42addec84ea7970dd
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] SelectWidget: Add example and link to decorated option widget - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/194384
Change subject: SelectWidget: Add example and link to decorated option widget
..
SelectWidget: Add example and link to decorated option widget
Change-Id: Id527cd226696cc13a764c7bf8bdcb1d74f337e7b
---
M src/widgets/SelectWidget.js
1 file changed, 21 insertions(+), 2 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/84/194384/1
diff --git a/src/widgets/SelectWidget.js b/src/widgets/SelectWidget.js
index de74326..4238089 100644
--- a/src/widgets/SelectWidget.js
+++ b/src/widgets/SelectWidget.js
@@ -4,9 +4,28 @@
* {@link OO.ui.RadioSelectWidget radio selects}, and {@link
OO.ui.MenuSelectWidget
* menu selects}.
*
- * This class should be used together with OO.ui.OptionWidget.
+ * This class should be used together with OO.ui.OptionWidget or
OO.ui.DecoratedOptionWidget. For more
+ * information, please see the [OOjs UI documentation on MediaWiki][1].
*
- * For more information, please see the [OOjs UI documentation on
MediaWiki][1].
+ * @example
+ * // Example of a select widget with three options
+ * var select=new OO.ui.SelectWidget( {
+ * items: [
+ * new OO.ui.OptionWidget( {
+ * data: 'a',
+ * label: 'Option One',
+ * } ),
+ * new OO.ui.OptionWidget( {
+ * data: 'b',
+ * label: 'Option Two',
+ * } ),
+ * new OO.ui.OptionWidget( {
+ * data: 'c',
+ * label: 'Option Three',
+ * } ),
+ * ]
+ * } );
+ * $('body').append(select.$element);
*
* [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
*
--
To view, visit https://gerrit.wikimedia.org/r/194384
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: Id527cd226696cc13a764c7bf8bdcb1d74f337e7b
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] GroupWidget and ItemWidget: Mark private - change (oojs/ui)
Kmenger has uploaded a new change for review. https://gerrit.wikimedia.org/r/194387 Change subject: GroupWidget and ItemWidget: Mark private .. GroupWidget and ItemWidget: Mark private Change-Id: Iec0c0162aa213014cc91724866948d5cdfd1004b --- M src/widgets/GroupWidget.js M src/widgets/ItemWidget.js 2 files changed, 2 insertions(+), 0 deletions(-) git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/87/194387/1 diff --git a/src/widgets/GroupWidget.js b/src/widgets/GroupWidget.js index d8eb541..7d9be90 100644 --- a/src/widgets/GroupWidget.js +++ b/src/widgets/GroupWidget.js @@ -3,6 +3,7 @@ * * Use together with OO.ui.ItemWidget to make disabled state inheritable. * + * @private * @abstract * @class * @extends OO.ui.GroupElement diff --git a/src/widgets/ItemWidget.js b/src/widgets/ItemWidget.js index d53331f..292514f 100644 --- a/src/widgets/ItemWidget.js +++ b/src/widgets/ItemWidget.js @@ -6,6 +6,7 @@ * * Use together with OO.ui.GroupWidget to make disabled state inheritable. * + * @private * @abstract * @class * -- To view, visit https://gerrit.wikimedia.org/r/194387 To unsubscribe, visit https://gerrit.wikimedia.org/r/settings Gerrit-MessageType: newchange Gerrit-Change-Id: Iec0c0162aa213014cc91724866948d5cdfd1004b Gerrit-PatchSet: 1 Gerrit-Project: oojs/ui Gerrit-Branch: master Gerrit-Owner: Kmenger kmen...@wikimedia.org ___ MediaWiki-commits mailing list MediaWiki-commits@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] LabelWidget: Add description, example, and mark private method - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/194405
Change subject: LabelWidget: Add description, example, and mark private method
..
LabelWidget: Add description, example, and mark private method
Change-Id: I4f5d25b26b1294b0f0da58a86b16de017499c46a
---
M src/widgets/LabelWidget.js
1 file changed, 31 insertions(+), 2 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/05/194405/1
diff --git a/src/widgets/LabelWidget.js b/src/widgets/LabelWidget.js
index 684eb47..7844a65 100644
--- a/src/widgets/LabelWidget.js
+++ b/src/widgets/LabelWidget.js
@@ -1,5 +1,32 @@
/**
- * Label widget.
+ * LabelWidgets help identify the function of interface elements. Each
LabelWidget can
+ * be configured with a `label` option that is set to a string, a label node,
or a function:
+ *
+ * - String: a plaintext string
+ * - jQuery selection: a jQuery selection, used for anything other than a
plaintext label, e.g., a
+ * label that includes a link or special styling, such as a gray color or
additional graphical elements.
+ * - Function: a function that will produce a string in the future. Functions
are used
+ * in cases where the value of the label is not currently defined.
+ *
+ * In addition, the LabelWidget can be associated with an {@link
OO.ui.InputWidget input widget}, which
+ * will come into focus when the label is clicked.
+ *
+ * @example
+ * // Examples of LabelWidgets
+ * var label1 = new OO.ui.LabelWidget({
+ * label: 'plaintext label'
+ * });
+ * var label2 = new OO.ui.LabelWidget({
+ * label: $( 'a href=default.htmljQuery label/a' )
+ * });
+ * // Create a fieldset layout with fields for each example
+ * var fieldset = new OO.ui.FieldsetLayout( );
+ * fieldset.addItems( [
+ * new OO.ui.FieldLayout( label1 ),
+ * new OO.ui.FieldLayout( label2 )
+ * ] );
+ * $( 'body' ).append( fieldset.$element );
+ *
*
* @class
* @extends OO.ui.Widget
@@ -7,7 +34,8 @@
*
* @constructor
* @param {Object} [config] Configuration options
- * @cfg {OO.ui.InputWidget} [input] Input widget this label is for
+ * @cfg {OO.ui.InputWidget} [input] {@link OO.ui.InputWidget Input widget}
that uses the label.
+ * Clicking the label will focus the specified input field.
*/
OO.ui.LabelWidget = function OoUiLabelWidget( config ) {
// Configuration initialization
@@ -47,6 +75,7 @@
/**
* Handles label mouse click events.
*
+ * @private
* @param {jQuery.Event} e Mouse click event
*/
OO.ui.LabelWidget.prototype.onClick = function () {
--
To view, visit https://gerrit.wikimedia.org/r/194405
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I4f5d25b26b1294b0f0da58a86b16de017499c46a
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] IndicatorWidget: Add description and example - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/194410
Change subject: IndicatorWidget: Add description and example
..
IndicatorWidget: Add description and example
Change-Id: I7d2209d644b6aa8c8785a485409c459248978187
---
M src/widgets/IndicatorWidget.js
1 file changed, 17 insertions(+), 2 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/10/194410/1
diff --git a/src/widgets/IndicatorWidget.js b/src/widgets/IndicatorWidget.js
index d2c7c62..265f8dd 100644
--- a/src/widgets/IndicatorWidget.js
+++ b/src/widgets/IndicatorWidget.js
@@ -1,7 +1,22 @@
/**
- * Indicator widget.
+ * IndicatorWidgets create indicators, which are small graphics that are
generally used to draw
+ * attention to the status of an item or to clarify the function of a control.
For a list of
+ * indicators included in the library, please see the [OOjs UI documentation
on MediaWiki][1].
*
- * See OO.ui.IndicatorElement for more information.
+ * @example
+ * // Example of an indicator widget
+ * var indicator1 = new OO.ui.IndicatorWidget( {
+ * indicator: 'alert'
+ * });
+ *
+ * // Create a fieldset layout to add a label
+ * var fieldset = new OO.ui.FieldsetLayout( );
+ * fieldset.addItems( [
+ * new OO.ui.FieldLayout( indicator1, {label: 'An alert indicator:'} )
+ * ] );
+ * $( 'body' ).append( fieldset.$element );
+ *
+ * [1]:
https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Indicators
*
* @class
* @extends OO.ui.Widget
--
To view, visit https://gerrit.wikimedia.org/r/194410
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I7d2209d644b6aa8c8785a485409c459248978187
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] TextInputWidget: Add description, example, and mark private ... - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/194239
Change subject: TextInputWidget: Add description, example, and mark private
methods
..
TextInputWidget: Add description, example, and mark private methods
Change-Id: I6798228354c7b910f245ee7b3777b868d577ee9b
---
M src/widgets/TextInputWidget.js
1 file changed, 59 insertions(+), 28 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/39/194239/1
diff --git a/src/widgets/TextInputWidget.js b/src/widgets/TextInputWidget.js
index 4d1df34..30570e0 100644
--- a/src/widgets/TextInputWidget.js
+++ b/src/widgets/TextInputWidget.js
@@ -1,5 +1,19 @@
/**
- * Input widget with a text field.
+ * TextInputWidgets, like HTML text inputs, can be configured with options
that customize the
+ * size of the field as well as its presentation. In addition, these widgets
can be configured
+ * with {@link OO.ui.IconElement icons}, {@link OO.ui.IndicatorElement
indicators}, an optional
+ * validation-pattern (used to determine if an input value is valid or not)
and an input filter,
+ * which modifies incoming values rather than validating them.
+ * Please see the [OOjs UI documentation on MediaWiki] [1] for more
information and examples.
+ *
+ * @example
+ * // Example of a text input widget
+ * var textInput=new OO.ui.TextInputWidget( {
+ * value: 'Text input'
+ * } )
+ * $('body').append(textInput.$element);
+ *
+ * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
*
* @class
* @extends OO.ui.InputWidget
@@ -10,19 +24,22 @@
*
* @constructor
* @param {Object} [config] Configuration options
- * @cfg {string} [type='text'] HTML tag `type` attribute
+ * @cfg {string} [type='text'] The value of the HTML `type` attribute
* @cfg {string} [placeholder] Placeholder text
- * @cfg {boolean} [autofocus=false] Ask the browser to focus this widget,
using the 'autofocus' HTML
- * attribute
- * @cfg {boolean} [readOnly=false] Prevent changes
- * @cfg {number} [maxLength] Maximum allowed number of characters to input
+ * @cfg {boolean} [autofocus=false] Use an HTML `autofocus` attribute to
+ * instruct the browser to focus this widget.
+ * @cfg {boolean} [readOnly=false] Prevent changes to the value of the text
input.
+ * @cfg {number} [maxLength] Maximum number of characters allowed in the input.
* @cfg {boolean} [multiline=false] Allow multiple lines of text
- * @cfg {boolean} [autosize=false] Automatically resize to fit content
- * @cfg {boolean} [maxRows=10] Maximum number of rows to make visible when
autosizing
- * @cfg {string} [labelPosition='after'] Label position, 'before' or 'after'
+ * @cfg {boolean} [autosize=false] Automatically resize the text input to fit
its content.
+ * Use the #maxRows config to specify a maximum number of displayed rows.
+ * @cfg {boolean} [maxRows=10] Maximum number of rows to display when
#autosize is set to true.
+ * @cfg {string} [labelPosition='after'] The position of the inline label
relative to that of
+ * the value or placeholder text: `'before'` or `'after'`
* @cfg {boolean} [required=false] Mark the field as required
- * @cfg {RegExp|string} [validate] Regular expression to validate against (or
symbolic name referencing
- * one, see #static-validationPatterns)
+ * @cfg {RegExp|string} [validate] Validation pattern, either a regular
expression or the
+ * symbolic name of a pattern defined by the class: 'non-empty' (the value
cannot be an empty string)
+ * or 'integer' (the value must contain only numbers).
*/
OO.ui.TextInputWidget = function OoUiTextInputWidget( config ) {
// Configuration initialization
@@ -107,9 +124,9 @@
/* Events */
/**
- * User presses enter inside the text box.
+ * An `enter` event is emitted when the user presses 'enter' inside the text
box.
*
- * Not called if input is multiline.
+ * Not emitted if the input is multiline.
*
* @event enter
*/
@@ -119,6 +136,7 @@
/**
* Handle icon mouse down events.
*
+ * @private
* @param {jQuery.Event} e Mouse down event
* @fires icon
*/
@@ -132,6 +150,7 @@
/**
* Handle indicator mouse down events.
*
+ * @private
* @param {jQuery.Event} e Mouse down event
* @fires indicator
*/
@@ -145,6 +164,7 @@
/**
* Handle key press events.
*
+ * @private
* @param {jQuery.Event} e Key press event
* @fires enter If enter key is pressed and input is not multiline
*/
@@ -157,6 +177,7 @@
/**
* Handle element attach events.
*
+ * @private
* @param {jQuery.Event} e Element attach event
*/
OO.ui.TextInputWidget.prototype.onElementAttach = function () {
@@ -189,7 +210,7 @@
};
/**
- * Check if the widget is read-only.
+ * Check if the input is {@link #readOnly read-only}.
*
* @return {boolean}
*/
@@ -198,9 +219,7 @@
};
/**
- * Set the read-only state of the widget.
- *
- * This should probably change the widget's appearance and
[MediaWiki-commits] [Gerrit] RadioInputWidget: Add description and example - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/193895
Change subject: RadioInputWidget: Add description and example
..
RadioInputWidget: Add description and example
Change-Id: I9e5bd0c3e47ca54b17aacd0678303bbfbb7bff93
---
M src/widgets/RadioInputWidget.js
1 file changed, 31 insertions(+), 5 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/95/193895/1
diff --git a/src/widgets/RadioInputWidget.js b/src/widgets/RadioInputWidget.js
index 17a47ac..7ce5dd2 100644
--- a/src/widgets/RadioInputWidget.js
+++ b/src/widgets/RadioInputWidget.js
@@ -1,15 +1,41 @@
/**
- * Radio input widget.
+ * RadioInputWidget creates a single radio button. Because radio buttons are
usually used as a set,
+ * in most cases you will want to use a {@link OO.ui.RadioSelectWidget radio
select}
+ * with {@link OO.ui.RadioOptionWidget radio options} instead of this class.
For more information,
+ * please see the [OOjs UI documentation on MediaWiki][1].
*
- * Radio buttons only make sense as a set, and you probably want to use the
OO.ui.RadioSelectWidget
- * class instead of using this class directly.
+ * @example
+ * // An example of selected, unselected, and disabled radio inputs
+ * var radio1=new OO.ui.RadioInputWidget({
+ * value: 'a',
+ * selected: true
+ * });
+ * var radio2=new OO.ui.RadioInputWidget({
+ * value: 'b'
+ * });
+ * var radio3=new OO.ui.RadioInputWidget( {
+ * value:'c',
+ * disabled: true
+ * } );
+ * // Create a fieldset layout with fields for each radio button.
+ * var fieldset = new OO.ui.FieldsetLayout( {
+ * label: 'Radio inputs'
+ * } );
+ * fieldset.addItems( [
+ * new OO.ui.FieldLayout( radio1, {label : 'Selected', align :
'inline'}),
+ * new OO.ui.FieldLayout( radio2, {label : 'Unselected', align :
'inline'}),
+ * new OO.ui.FieldLayout( radio3, {label : 'Disabled', align :
'inline'}),
+ * ] );
+ * $( 'body' ).append( fieldset.$element );
+ *
+ * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
*
* @class
* @extends OO.ui.InputWidget
*
* @constructor
* @param {Object} [config] Configuration options
- * @cfg {boolean} [selected=false] Whether the radio button is initially
selected
+ * @cfg {boolean} [selected=false] Select the radio button initially. By
default, the radio button is not selected.
*/
OO.ui.RadioInputWidget = function OoUiRadioInputWidget( config ) {
// Configuration initialization
@@ -47,7 +73,7 @@
/**
* Set selection state of this radio button.
*
- * @param {boolean} state Whether the button is selected
+ * @param {boolean} state `true` for selected
* @chainable
*/
OO.ui.RadioInputWidget.prototype.setSelected = function ( state ) {
--
To view, visit https://gerrit.wikimedia.org/r/193895
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I9e5bd0c3e47ca54b17aacd0678303bbfbb7bff93
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] ProgressBar: Add description and example - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/193869
Change subject: ProgressBar: Add description and example
..
ProgressBar: Add description and example
Change-Id: Icf9596d9076ff49e8a16375b971d2b25a15def30
---
M src/widgets/ProgressBarWidget.js
1 file changed, 34 insertions(+), 6 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/69/193869/1
diff --git a/src/widgets/ProgressBarWidget.js b/src/widgets/ProgressBarWidget.js
index 2a208aa..d800c66 100644
--- a/src/widgets/ProgressBarWidget.js
+++ b/src/widgets/ProgressBarWidget.js
@@ -1,12 +1,40 @@
/**
- * Progress bar widget.
+ * Progress bars visually display the status of an operation, such as a
download,
+ * and can be either determinate or indeterminate:
+ *
+ * - **determinate** process bars show the percent of an operation that is
complete.
+ *
+ * - **indeterminate** process bars use a visual display of motion to indicate
that an operation
+ * is taking place. Because the extent of an indeterminate operation is
unknown, the bar does
+ * not use percentages.
+ *
+ * The value of the `progress` configuration determines whether the bar is
determinate or indeterminate.
+ *
+ * @example
+ * // Examples of determinate and indeterminate progress bars.
+ * var progressBar1=new OO.ui.ProgressBarWidget( {
+ * progress: 33
+ * } );
+ *
+ * var progressBar2=new OO.ui.ProgressBarWidget( {
+ * progress: false
+ * } );
+ * // Create a FieldsetLayout to layout progress bars
+ * var fieldset = new OO.ui.FieldsetLayout;
+ * fieldset.addItems( [
+ *new OO.ui.FieldLayout( progressBar1, {label : 'Determinate', align :
'top'}),
+ *new OO.ui.FieldLayout( progressBar2, {label : 'Indeterminate', align
: 'top'})
+ * ] );
+ * $( 'body' ).append( fieldset.$element );
*
* @class
* @extends OO.ui.Widget
*
* @constructor
* @param {Object} [config] Configuration options
- * @cfg {number|boolean} [progress=false] Initial progress percent or false
for indeterminate
+ * @cfg {number|boolean} [progress=false] The type of progress bar
(determinate or indeterminate).
+ * To create a determinate progress bar, specify a number that reflects the
initial percent complete.
+ * By default, the progress bar is indeterminate.
*/
OO.ui.ProgressBarWidget = function OoUiProgressBarWidget( config ) {
// Configuration initialization
@@ -43,18 +71,18 @@
/* Methods */
/**
- * Get progress percent
+ * Get the percent of the progress that has been completed. Indeterminate
progresses will return `false`.
*
- * @return {number} Progress percent
+ * @return {number|boolean} Progress percent
*/
OO.ui.ProgressBarWidget.prototype.getProgress = function () {
return this.progress;
};
/**
- * Set progress percent
+ * Set the percent of the process completed or `false` for an indeterminate
process.
*
- * @param {number|boolean} progress Progress percent or false for indeterminate
+ * @param {number|boolean} progress Progress percent or `false` for
indeterminate
*/
OO.ui.ProgressBarWidget.prototype.setProgress = function ( progress ) {
this.progress = progress;
--
To view, visit https://gerrit.wikimedia.org/r/193869
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: Icf9596d9076ff49e8a16375b971d2b25a15def30
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] CheckboxInputWidget: Add description and example - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/193880
Change subject: CheckboxInputWidget: Add description and example
..
CheckboxInputWidget: Add description and example
Change-Id: I5e44046f1811a4458c4a811c9a1c3b1dd29254df
---
M src/widgets/CheckboxInputWidget.js
1 file changed, 32 insertions(+), 3 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/80/193880/1
diff --git a/src/widgets/CheckboxInputWidget.js
b/src/widgets/CheckboxInputWidget.js
index f1a4add..176083a 100644
--- a/src/widgets/CheckboxInputWidget.js
+++ b/src/widgets/CheckboxInputWidget.js
@@ -1,12 +1,41 @@
/**
- * Checkbox input widget.
+ * CheckboxInputWidgets, like HTML checkboxes, can be selected and/or
configured with a value.
+ * Note that these {@link OO.ui.InputWidget input widgets} are best laid out
+ * in {@link OO.ui.FieldLayout field layouts} that use the {@link
OO.ui.FieldLayout#align inline}
+ * alignment. For more information, please see the [OOjs UI documentation on
MediaWiki][1].
+ *
+ * @example
+ * // An example of selected, unselected, and disabled checkbox inputs
+ * var checkbox1=new OO.ui.CheckboxInputWidget({
+ * value: 'a',
+ * selected: true
+ * });
+ * var checkbox2=new OO.ui.CheckboxInputWidget({
+ * value: 'b'
+ * });
+ * var checkbox3=new OO.ui.CheckboxInputWidget( {
+ * value:'c',
+ * disabled: true
+ * } );
+ * // Create a fieldset layout with fields for each checkbox.
+ * var fieldset = new OO.ui.FieldsetLayout( {
+ * label: 'Checkboxes'
+ * } );
+ * fieldset.addItems( [
+ * new OO.ui.FieldLayout( checkbox1, {label : 'Selected checkbox',
align : 'inline'}),
+ * new OO.ui.FieldLayout( checkbox2, {label : 'Unselected checkbox',
align : 'inline'}),
+ * new OO.ui.FieldLayout( checkbox3, {label : 'Disabled checkbox',
align : 'inline'}),
+ * ] );
+ * $( 'body' ).append( fieldset.$element );
+ *
+ * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
*
* @class
* @extends OO.ui.InputWidget
*
* @constructor
* @param {Object} [config] Configuration options
- * @cfg {boolean} [selected=false] Whether the checkbox is initially selected
+ * @cfg {boolean} [selected=false] Select the checkbox initially. By default,
the checkbox is not selected.
*/
OO.ui.CheckboxInputWidget = function OoUiCheckboxInputWidget( config ) {
// Configuration initialization
@@ -50,7 +79,7 @@
/**
* Set selection state of this checkbox.
*
- * @param {boolean} state Whether the checkbox is selected
+ * @param {boolean} state `true` for selected
* @chainable
*/
OO.ui.CheckboxInputWidget.prototype.setSelected = function ( state ) {
--
To view, visit https://gerrit.wikimedia.org/r/193880
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I5e44046f1811a4458c4a811c9a1c3b1dd29254df
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] FieldLayout: Fix display of bulleted list - change (oojs/ui)
Kmenger has uploaded a new change for review. https://gerrit.wikimedia.org/r/193885 Change subject: FieldLayout: Fix display of bulleted list .. FieldLayout: Fix display of bulleted list The extra spaces at the start of the multi-line-items seem to be causing the list to render incorrectly on the live site. For some reason, the list looks fine locally; I'm not sure what is different between the two setups that would make this the case. I'm also not certain that removing the spaces will indeed fix the problem, but I suspect it will. Change-Id: I42eb1ad769b6128dcf2b35f13e13cb0ad2a4963c --- M src/layouts/FieldLayout.js 1 file changed, 5 insertions(+), 5 deletions(-) git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/85/193885/1 diff --git a/src/layouts/FieldLayout.js b/src/layouts/FieldLayout.js index c7a34e1..9e5b5aa 100644 --- a/src/layouts/FieldLayout.js +++ b/src/layouts/FieldLayout.js @@ -5,14 +5,14 @@ * Field layouts can be configured with help text and/or labels. Labels are aligned in one of four ways: * * - **left**: The label is placed before the field-widget and aligned with the left margin. - * A left-alignment is used for forms with many fields. + * A left-alignment is used for forms with many fields. * - **right**: The label is placed before the field-widget and aligned to the right margin. - * A right-alignment is used for long but familiar forms which users tab through, - * verifying the current field with a quick glance at the label. + * A right-alignment is used for long but familiar forms which users tab through, + * verifying the current field with a quick glance at the label. * - **top**: The label is placed above the field-widget. A top-alignment is used for brief forms - *that users fill out from top to bottom. + * that users fill out from top to bottom. * - **inline**: The label is placed after the field-widget and aligned to the left. - An inline-alignment is best used with checkboxes or radio buttons. + * An inline-alignment is best used with checkboxes or radio buttons. * * Help text is accessed via a help icon that appears in the upper right corner of the rendered field layout. * Please see the [OOjs UI documentation on MediaWiki] [1] for examples and more information. -- To view, visit https://gerrit.wikimedia.org/r/193885 To unsubscribe, visit https://gerrit.wikimedia.org/r/settings Gerrit-MessageType: newchange Gerrit-Change-Id: I42eb1ad769b6128dcf2b35f13e13cb0ad2a4963c Gerrit-PatchSet: 1 Gerrit-Project: oojs/ui Gerrit-Branch: master Gerrit-Owner: Kmenger kmen...@wikimedia.org ___ MediaWiki-commits mailing list MediaWiki-commits@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] SelectWidget: Marked protected methods and clarified choose/... - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/193413
Change subject: SelectWidget: Marked protected methods and clarified
choose/press descriptions
..
SelectWidget: Marked protected methods and clarified choose/press descriptions
Change-Id: I9cbf76293cb1fb2dc3832bb1c865c47df302bdc7
---
M src/widgets/SelectWidget.js
1 file changed, 16 insertions(+), 5 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/13/193413/1
diff --git a/src/widgets/SelectWidget.js b/src/widgets/SelectWidget.js
index a905b61..b5374ba 100644
--- a/src/widgets/SelectWidget.js
+++ b/src/widgets/SelectWidget.js
@@ -91,6 +91,7 @@
/**
* @event choose
+ * A `choose` event is emitted when an item is chosen with the #chooseItem
method.
* @param {OO.ui.OptionWidget|null} item Chosen item
*/
@@ -288,6 +289,8 @@
/**
* Bind key down listener.
+ *
+ * @protected
*/
OO.ui.SelectWidget.prototype.bindKeyDownListener = function () {
this.getElementWindow().addEventListener( 'keydown',
this.onKeyDownHandler, true );
@@ -295,6 +298,8 @@
/**
* Unbind key down listener.
+ *
+ * @protected
*/
OO.ui.SelectWidget.prototype.unbindKeyDownListener = function () {
this.getElementWindow().removeEventListener( 'keydown',
this.onKeyDownHandler, true );
@@ -348,7 +353,9 @@
};
/**
- * Toggle pressed state.
+ * Toggle pressed state. Press is a state that occurs when a user mouses down
on an item, but
+ * has not yet let go of the mouse. The item may appear selected, but it will
not be selected
+ * until the user releases the mouse.
*
* @param {boolean} pressed An option is being pressed
*/
@@ -417,7 +424,9 @@
};
/**
- * Press an item.
+ * Press an item. Press is a state that occurs when a user mouses down on an
item, but has not
+ * yet let go of the mouse. The item may appear selected, but it will not be
selected until the user
+ * releases the mouse.
*
* @param {OO.ui.OptionWidget} [item] Item to press, omit to depress all
* @fires press
@@ -442,10 +451,12 @@
};
/**
- * Choose an item.
+ * Choose an item. Note that ‘choose’ should never be modified
programmatically. A user can choose
+ * an option with the keyboard or mouse and it becomes selected. To select an
item programmatically,
+ * use the #selectItem method.
*
- * Identical to #selectItem, but may vary in subclasses that want to take
additional action when
- * an item is selected using the keyboard or mouse.
+ * This method is identical to #selectItem, but may vary in subclasses that
take additional action
+ * when users choose an item with the keyboard or mouse.
*
* @param {OO.ui.OptionWidget} item Item to choose
* @fires choose
--
To view, visit https://gerrit.wikimedia.org/r/193413
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I9cbf76293cb1fb2dc3832bb1c865c47df302bdc7
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] PopupElement: Add description - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/193405
Change subject: PopupElement: Add description
..
PopupElement: Add description
Change-Id: I09ce9a7ed7ae8d6885cf2f13a683e45c7e30d5c1
---
M src/elements/PopupElement.js
1 file changed, 4 insertions(+), 1 deletion(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/05/193405/1
diff --git a/src/elements/PopupElement.js b/src/elements/PopupElement.js
index ea4cb50..099e94b 100644
--- a/src/elements/PopupElement.js
+++ b/src/elements/PopupElement.js
@@ -1,5 +1,8 @@
/**
- * Element containing an OO.ui.PopupWidget object.
+ * PopupElement is mixed into other classes to generate a {@link
OO.ui.PopupWidget popup widget}.
+ * A popup is a container for content. It is overlaid and positioned
absolutely. By default, each
+ * popup has an anchor, which is an arrow-like protrusion that points toward
the popup’s origin.
+ * See {@link OO.ui.PopupWidget PopupWidget} for an example.
*
* @abstract
* @class
--
To view, visit https://gerrit.wikimedia.org/r/193405
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I09ce9a7ed7ae8d6885cf2f13a683e45c7e30d5c1
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] PopupWidget: Add description, example, and mark private methods - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/193490
Change subject: PopupWidget: Add description, example, and mark private methods
..
PopupWidget: Add description, example, and mark private methods
Change-Id: I0769f04ddd003e8cec851c361f3b98d89eb52ce5
---
M src/widgets/PopupWidget.js
1 file changed, 45 insertions(+), 14 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/90/193490/1
diff --git a/src/widgets/PopupWidget.js b/src/widgets/PopupWidget.js
index a7432ac..ccf3f70 100644
--- a/src/widgets/PopupWidget.js
+++ b/src/widgets/PopupWidget.js
@@ -1,5 +1,21 @@
/**
- * Container for content that is overlaid and positioned absolutely.
+ * PopupWidget is a container for content. The popup is overlaid and
positioned absolutely.
+ * By default, each popup has an anchor that points toward its origin.
+ * Please see the [OOjs UI documentation on Mediawiki] [1] for more
information and examples.
+ *
+ * @example
+ * // A popup widget.
+ * var popup=new OO.ui.PopupWidget({
+ * $content: $( 'pHi there!/p' ),
+ * padded: true,
+ * width: 300
+ * } );
+ *
+ * $('body').append(popup.$element);
+ * // To display the popup, toggle the visibility to 'true'.
+ * popup.toggle(true);
+ *
+ * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Popups
*
* @class
* @extends OO.ui.Widget
@@ -8,16 +24,24 @@
* @constructor
* @param {Object} [config] Configuration options
* @cfg {number} [width=320] Width of popup in pixels
- * @cfg {number} [height] Height of popup, omit to use automatic height
+ * @cfg {number} [height] Height of popup in pixels. Omit to use the automatic
height.
* @cfg {boolean} [anchor=true] Show anchor pointing to origin of popup
- * @cfg {string} [align='center'] Alignment of popup to origin
- * @cfg {jQuery} [$container] Container to prevent popup from rendering
outside of
- * @cfg {number} [containerPadding=10] How much padding to keep between popup
and container
+ * @cfg {string} [align='center'] Alignment of the popup: `center`, `left`, or
`right`.
+ * If the popup is right-aligned, the right edge of the popup is aligned to
the anchor.
+ * For left-aligned popups, the left edge is aligned to the anchor.
+ * @cfg {jQuery} [$container] Constrain the popup to the boundaries of the
specified container.
+ * See the [OOjs UI docs on MediaWiki][3] for an example.
+ * [3]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Popups#containerExample
+ * @cfg {number} [containerPadding=10] Padding between the popup and its
container, specified as a number of pixels.
* @cfg {jQuery} [$content] Content to append to the popup's body
- * @cfg {boolean} [autoClose=false] Popup auto-closes when it loses focus
- * @cfg {jQuery} [$autoCloseIgnore] Elements to not auto close when clicked
- * @cfg {boolean} [head] Show label and close button at the top
- * @cfg {boolean} [padded] Add padding to the body
+ * @cfg {boolean} [autoClose=false] Automatically close the popup when it
loses focus.
+ * @cfg {jQuery} [$autoCloseIgnore] Elements that will not close the popup
when clicked.
+ * This config option is only relevant if #autoClose is set to `true`. See
the [OOjs UI docs on MediaWiki][2]
+ * for an example.
+ * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Popups#autocloseExample
+ * @cfg {boolean} [head] Show a popup header that contains a #label (if
specified) and close
+ * button.
+ * @cfg {boolean} [padded] Add padding to the popup's body
*/
OO.ui.PopupWidget = function OoUiPopupWidget( config ) {
// Configuration initialization
@@ -95,6 +119,7 @@
/**
* Handles mouse down events.
*
+ * @private
* @param {jQuery.Event} e Mouse down event
*/
OO.ui.PopupWidget.prototype.onMouseDown = function ( e ) {
@@ -109,6 +134,8 @@
/**
* Bind mouse down listener.
+ *
+ * @private
*/
OO.ui.PopupWidget.prototype.bindMouseDownListener = function () {
// Capture clicks outside popup
@@ -117,6 +144,8 @@
/**
* Handles close button click events.
+ *
+ * @private
*/
OO.ui.PopupWidget.prototype.onCloseButtonClick = function () {
if ( this.isVisible() ) {
@@ -126,13 +155,15 @@
/**
* Unbind mouse down listener.
+ *
+ * @private
*/
OO.ui.PopupWidget.prototype.unbindMouseDownListener = function () {
this.getElementWindow().removeEventListener( 'mousedown',
this.onMouseDownHandler, true );
};
/**
- * Set whether to show a anchor.
+ * Show, hide, or toggle the visibility of the anchor.
*
* @param {boolean} [show] Show anchor, omit to toggle
*/
@@ -150,9 +181,9 @@
};
/**
- * Check if showing a anchor.
+ * Check if the anchor is visible.
*
- * @return {boolean} anchor is visible
+ * @return {boolean} Anchor is visible
*/
OO.ui.PopupWidget.prototype.hasAnchor = function () {
return this.anchor;
@@ -192,8 +223,8 @@
*
* Changing the
[MediaWiki-commits] [Gerrit] ToggleWidget: Add description - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/193521
Change subject: ToggleWidget: Add description
..
ToggleWidget: Add description
Change-Id: Ibe3ed957b0c2505dccb51a98bbd73bda857f0d46
---
M src/widgets/ToggleWidget.js
1 file changed, 12 insertions(+), 7 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/21/193521/1
diff --git a/src/widgets/ToggleWidget.js b/src/widgets/ToggleWidget.js
index c89e652..96ace53 100644
--- a/src/widgets/ToggleWidget.js
+++ b/src/widgets/ToggleWidget.js
@@ -1,12 +1,14 @@
/**
- * Mixin for widgets with a boolean on/off state.
+ * ToggleWidget is mixed into other classes to create widgets with an on/off
state.
+ * Please see OO.ui.ToggleButtonWidget and OO.ui.ToggleSwitchWidget for
examples.
*
* @abstract
* @class
*
* @constructor
* @param {Object} [config] Configuration options
- * @cfg {boolean} [value=false] Initial value
+ * @cfg {boolean} [value=false] The toggle’s initial on/off state.
+ * By default, the toggle is in the 'off' state.
*/
OO.ui.ToggleWidget = function OoUiToggleWidget( config ) {
// Configuration initialization
@@ -24,24 +26,27 @@
/**
* @event change
- * @param {boolean} value Changed value
+ *
+ * A change event is emitted when the on/off state of the toggle changes.
+ *
+ * @param {boolean} value Value representing the new state of the toggle
*/
/* Methods */
/**
- * Get the value of the toggle.
+ * Get the value representing the toggle’s state.
*
- * @return {boolean}
+ * @return {boolean} The on/off state of the toggle
*/
OO.ui.ToggleWidget.prototype.getValue = function () {
return this.value;
};
/**
- * Set the value of the toggle.
+ * Set the state of the toggle: `true` for 'on', `false' for 'off'.
*
- * @param {boolean} value New value
+ * @param {boolean} value The state of the toggle
* @fires change
* @chainable
*/
--
To view, visit https://gerrit.wikimedia.org/r/193521
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: Ibe3ed957b0c2505dccb51a98bbd73bda857f0d46
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] ToggleSwitchWidget: Add description, example, and mark priva... - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/193528
Change subject: ToggleSwitchWidget: Add description, example, and mark private
methods
..
ToggleSwitchWidget: Add description, example, and mark private methods
Change-Id: Id1dada8491ca03ded9e2cc058ac0ca99fb403e56
---
M src/widgets/ToggleSwitchWidget.js
1 file changed, 26 insertions(+), 2 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/28/193528/1
diff --git a/src/widgets/ToggleSwitchWidget.js
b/src/widgets/ToggleSwitchWidget.js
index 9305876..3995897 100644
--- a/src/widgets/ToggleSwitchWidget.js
+++ b/src/widgets/ToggleSwitchWidget.js
@@ -1,5 +1,26 @@
/**
- * Switch that slides on and off.
+ * ToggleSwitches are switches that slide on and off. Their state is
represented by a Boolean
+ * value (`true` for ‘on’, and `false` otherwise, the default). The ‘off’
state is represented
+ * visually by a slider in the leftmost position.
+ *
+ * @example
+ * // Toggle switches in the 'off' and 'on' position.
+ * var toggleSwitch1 = new OO.ui.ToggleSwitchWidget({
+ * value: false
+ * } );
+ * var toggleSwitch2 = new OO.ui.ToggleSwitchWidget({
+ * value: true
+ * } );
+ *
+ * // Create a FieldsetLayout to layout and label switches
+ * var fieldset = new OO.ui.FieldsetLayout( {
+ *label: 'Toggle switches'
+ * } );
+ * fieldset.addItems( [
+ * new OO.ui.FieldLayout( toggleSwitch1, {label : 'Off', align :
'top'}),
+ * new OO.ui.FieldLayout( toggleSwitch2, {label : 'On', align : 'top'})
+ * ] );
+ * $( 'body' ).append( fieldset.$element );
*
* @class
* @extends OO.ui.Widget
@@ -8,7 +29,8 @@
*
* @constructor
* @param {Object} [config] Configuration options
- * @cfg {boolean} [value=false] Initial value
+ * @cfg {boolean} [value=false] The toggle switch’s initial on/off state.
+ * By default, the toggle switch is in the 'off' position.
*/
OO.ui.ToggleSwitchWidget = function OoUiToggleSwitchWidget( config ) {
// Parent constructor
@@ -51,6 +73,7 @@
/**
* Handle mouse click events.
*
+ * @private
* @param {jQuery.Event} e Mouse click event
*/
OO.ui.ToggleSwitchWidget.prototype.onClick = function ( e ) {
@@ -63,6 +86,7 @@
/**
* Handle key press events.
*
+ * @private
* @param {jQuery.Event} e Key press event
*/
OO.ui.ToggleSwitchWidget.prototype.onKeyPress = function ( e ) {
--
To view, visit https://gerrit.wikimedia.org/r/193528
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: Id1dada8491ca03ded9e2cc058ac0ca99fb403e56
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] ToggleButtonWidget: Add description, example, and mark priva... - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/193508
Change subject: ToggleButtonWidget: Add description, example, and mark private
method
..
ToggleButtonWidget: Add description, example, and mark private method
Change-Id: Ic7beb8724cb4c2666db6257019f58d80f819f223
---
M src/widgets/ToggleButtonWidget.js
1 file changed, 24 insertions(+), 2 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/08/193508/1
diff --git a/src/widgets/ToggleButtonWidget.js
b/src/widgets/ToggleButtonWidget.js
index 154d126..0500f2a 100644
--- a/src/widgets/ToggleButtonWidget.js
+++ b/src/widgets/ToggleButtonWidget.js
@@ -1,5 +1,24 @@
/**
- * Button that toggles on and off.
+ * ToggleButtons are buttons that have a state (‘on’ or ‘off’) that is
represented by a
+ * Boolean value. Like other {@link OO.ui.ButtonWidget buttons}, toggle
buttons can be
+ * configured with {@link OO.ui.IconElement icons}, {@link
OO.ui.IndicatorElement indicators},
+ * {@link OO.ui.TitledElement titles}, {@link OO.ui.FlaggedElement styling
flags},
+ * and {@link OO.ui.LabelElement labels}. Please see
+ * the [OOjs UI documentation][1] on MediaWiki for more information.
+ *
+ * @example
+ * // Toggle buttons in the 'off' and 'on' state.
+ * var toggleButton1 = new OO.ui.ToggleButtonWidget( {
+ * label: 'Toggle Button off'
+ * } );
+ * var toggleButton2 = new OO.ui.ToggleButtonWidget( {
+ * label: 'Toggle Button on',
+ * value: true
+ * } );
+ * // Append the buttons to the DOM.
+ * $( 'body' ).append( toggleButton1.$element, toggleButton2.$element );
+ *
+ * [1]:
https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Buttons_and_Switches#Toggle_buttons
*
* @class
* @extends OO.ui.ButtonWidget
@@ -7,7 +26,8 @@
*
* @constructor
* @param {Object} [config] Configuration options
- * @cfg {boolean} [value=false] Initial value
+ * @cfg {boolean} [value=false] The toggle button’s initial on/off
+ * state. By default, the button is in the 'off' state.
*/
OO.ui.ToggleButtonWidget = function OoUiToggleButtonWidget( config ) {
// Configuration initialization
@@ -34,6 +54,8 @@
/* Methods */
/**
+ *
+ * @private
* Handle the button action being triggered.
*/
OO.ui.ToggleButtonWidget.prototype.onAction = function () {
--
To view, visit https://gerrit.wikimedia.org/r/193508
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: Ic7beb8724cb4c2666db6257019f58d80f819f223
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] OptionWidget: Add description and descriptions of methods - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/192869
Change subject: OptionWidget: Add description and descriptions of methods
..
OptionWidget: Add description and descriptions of methods
Change-Id: I51e630df96b443224e1601a7d839d77b81bb6add
---
M src/widgets/OptionWidget.js
1 file changed, 29 insertions(+), 10 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/69/192869/1
diff --git a/src/widgets/OptionWidget.js b/src/widgets/OptionWidget.js
index 8ef0efa..0bc2486 100644
--- a/src/widgets/OptionWidget.js
+++ b/src/widgets/OptionWidget.js
@@ -1,5 +1,10 @@
/**
- * Generic option widget for use with OO.ui.SelectWidget.
+ * OptionWidgets are special elements that can be selected and configured with
data. The
+ * data is often unique for each option, but it does not have to be.
OptionWidgets are used
+ * with OO.ui.SelectWidget to create a selection of mutually exclusive
options. For more information
+ * and examples, please see the [OOjs UI documentation on MediaWiki][1].
+ *
+ * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
*
* @class
* @extends OO.ui.Widget
@@ -54,7 +59,7 @@
/* Methods */
/**
- * Check if option can be selected.
+ * Check if the option can be selected.
*
* @return {boolean} Item is selectable
*/
@@ -63,7 +68,9 @@
};
/**
- * Check if option can be highlighted.
+ * Check if the option can be highlighted. A highlight indicates that the
option
+ * may be selected when a user presses enter or clicks. Disabled items cannot
+ * be highlighted.
*
* @return {boolean} Item is highlightable
*/
@@ -72,7 +79,8 @@
};
/**
- * Check if option can be pressed.
+ * Check if the option can be pressed. The pressed state occurs when a user
mouses
+ * down on an item, but has not yet let go of the mouse.
*
* @return {boolean} Item is pressable
*/
@@ -81,7 +89,7 @@
};
/**
- * Check if option is selected.
+ * Check if the option is selected.
*
* @return {boolean} Item is selected
*/
@@ -90,7 +98,8 @@
};
/**
- * Check if option is highlighted.
+ * Check if the option is highlighted. A highlight indicates that the
+ * item may be selected when a user presses enter or clicks.
*
* @return {boolean} Item is highlighted
*/
@@ -99,7 +108,9 @@
};
/**
- * Check if option is pressed.
+ * Check if the option is pressed. The pressed state occurs when a user mouses
+ * down on an item, but has not yet let go of the mouse. The item may appear
+ * selected, but it will not be selected until the user releases the mouse.
*
* @return {boolean} Item is pressed
*/
@@ -108,7 +119,9 @@
};
/**
- * Set selected state.
+ * Set the option’s selected state. In general, all modifications to the
selection
+ * should be handled by the SelectWidget’s {@link
OO.ui.SelectWidget#selectItem selectItem( [item] )}
+ * method instead of this method.
*
* @param {boolean} [state=false] Select option
* @chainable
@@ -128,7 +141,10 @@
};
/**
- * Set highlighted state.
+ * Set the option’s highlighted state. In general, all programmatic
+ * modifications to the highlight should be handled by the
+ * SelectWidget’s {@link OO.ui.SelectWidget#highlightItem highlightItem(
[item] )}
+ * method instead of this method.
*
* @param {boolean} [state=false] Highlight option
* @chainable
@@ -143,7 +159,10 @@
};
/**
- * Set pressed state.
+ * Set the option’s pressed state. In general, all
+ * programmatic modifications to the pressed state should be handled by the
+ * SelectWidget’s {@link OO.ui.SelectWidget#pressItem pressItem( [item] )}
+ * method instead of this method.
*
* @param {boolean} [state=false] Press option
* @chainable
--
To view, visit https://gerrit.wikimedia.org/r/192869
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I51e630df96b443224e1601a7d839d77b81bb6add
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] ButtonOptionWidget: Add description - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/192851
Change subject: ButtonOptionWidget: Add description
..
ButtonOptionWidget: Add description
Change-Id: I9b77da5e08016642e8f66a3010939ba188300055
---
M src/widgets/ButtonOptionWidget.js
1 file changed, 5 insertions(+), 2 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/51/192851/1
diff --git a/src/widgets/ButtonOptionWidget.js
b/src/widgets/ButtonOptionWidget.js
index d138764..025aea0 100644
--- a/src/widgets/ButtonOptionWidget.js
+++ b/src/widgets/ButtonOptionWidget.js
@@ -1,7 +1,10 @@
/**
- * Option widget that looks like a button.
+ * ButtonOptionWidget is a special type of {@link OO.ui.ButtonElement button
element} that
+ * can be selected and configured with data. The class is
+ * used with OO.ui.ButtonSelectWidget to create a selection of button
options. Please see the
+ * [OOjs UI documentation on MediaWiki] [1] for more information.
*
- * Use together with OO.ui.ButtonSelectWidget.
+ * [1]:
https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Button_selects_and_options
*
* @class
* @extends OO.ui.DecoratedOptionWidget
--
To view, visit https://gerrit.wikimedia.org/r/192851
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I9b77da5e08016642e8f66a3010939ba188300055
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] ButtonSelectwidget: Add description and example - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/192846
Change subject: ButtonSelectwidget: Add description and example
..
ButtonSelectwidget: Add description and example
Change-Id: I8ca7f4bb435a1c62a21d06ef1c8cdf0edd952fd5
---
M src/widgets/ButtonSelectWidget.js
1 file changed, 31 insertions(+), 2 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/46/192846/1
diff --git a/src/widgets/ButtonSelectWidget.js
b/src/widgets/ButtonSelectWidget.js
index 553d055..6c1a2e6 100644
--- a/src/widgets/ButtonSelectWidget.js
+++ b/src/widgets/ButtonSelectWidget.js
@@ -1,7 +1,36 @@
/**
- * Select widget containing button options.
+ * ButtonSelectWidget is a {@link OO.ui.SelectWidget select widget} that
contains
+ * button options and is used together with
+ * OO.ui.ButtonOptionWidget. The ButtonSelectWidget provides an interface for
+ * highlighting, choosing, and selecting mutually exclusive options. Please see
+ * the [OOjs UI documentation on MediaWiki] [1] for more information.
*
- * Use together with OO.ui.ButtonOptionWidget.
+ * @example
+ * // Example: A ButtonSelectWidget that contains three ButtonOptionWidgets
+ * var option1 = new OO.ui.ButtonOptionWidget( {
+ * data: 1,
+ * label: 'Option 1',
+ * title:'Button option 1'
+ * } );
+ *
+ * var option2 = new OO.ui.ButtonOptionWidget( {
+ * data: 2,
+ * label: 'Option 2',
+ * title:'Button option 2'
+ * } );
+ *
+ * var option3 = new OO.ui.ButtonOptionWidget( {
+ * data: 3,
+ * label: 'Option 3',
+ * title:'Button option 3'
+ * } );
+ *
+ * var buttonSelect=new OO.ui.ButtonSelectWidget( {
+ * items: [option1, option2, option3]
+ * } );
+ * $('body').append(buttonSelect.$element);
+ *
+ * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
*
* @class
* @extends OO.ui.SelectWidget
--
To view, visit https://gerrit.wikimedia.org/r/192846
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I8ca7f4bb435a1c62a21d06ef1c8cdf0edd952fd5
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] SelectWidget: Add description for config, methods, events - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/192890
Change subject: SelectWidget: Add description for config, methods, events
..
SelectWidget: Add description for config, methods, events
Change-Id: I94c43ae6366055c0ff148d4e21ea287b96683049
---
M src/widgets/SelectWidget.js
1 file changed, 45 insertions(+), 19 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/90/192890/1
diff --git a/src/widgets/SelectWidget.js b/src/widgets/SelectWidget.js
index 38e406e..a905b61 100644
--- a/src/widgets/SelectWidget.js
+++ b/src/widgets/SelectWidget.js
@@ -16,7 +16,10 @@
*
* @constructor
* @param {Object} [config] Configuration options
- * @cfg {OO.ui.OptionWidget[]} [items] Options to add
+ * @cfg {OO.ui.OptionWidget[]} [items] An array of options to add to the
select.
+ * Options are created with {@link OO.ui.OptionWidget OptionWidget} classes.
See
+ * the [OOjs UI documentation on MediaWiki] [2] for examples.
+ * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
*/
OO.ui.SelectWidget = function OoUiSelectWidget( config ) {
// Configuration initialization
@@ -63,16 +66,26 @@
/**
* @event highlight
+ *
+ * A `highlight` event is emitted when the highlight is changed with the
#highlightItem method.
+ *
* @param {OO.ui.OptionWidget|null} item Highlighted item
*/
/**
* @event press
+ *
+ * A `press` event is emitted when the #pressItem method is used to
programmatically modify the
+ * pressed state of an option.
+ *
* @param {OO.ui.OptionWidget|null} item Pressed item
*/
/**
* @event select
+ *
+ * A `select` event is emitted when the selection is modified programmatically
with the #selectItem method.
+ *
* @param {OO.ui.OptionWidget|null} item Selected item
*/
@@ -83,12 +96,19 @@
/**
* @event add
+ *
+ * An `add` event is emitted when options are added to the select with the
#addItems method.
+ *
* @param {OO.ui.OptionWidget[]} items Added items
- * @param {number} index Index items were added at
+ * @param {number} index Index of insertion point
*/
/**
* @event remove
+ *
+ * A `remove` event is emitted when options are removed from the select with
the #clearItems
+ * or #removeItems methods.
+ *
* @param {OO.ui.OptionWidget[]} items Removed items
*/
@@ -211,6 +231,7 @@
/**
* Handle key down events.
*
+ * @protected
* @param {jQuery.Event} e Key down event
*/
OO.ui.SelectWidget.prototype.onKeyDown = function ( e ) {
@@ -344,11 +365,10 @@
};
/**
- * Highlight an item.
+ * Highlight an option. If the `item` param is omitted, no options will be
highlighted
+ * and any existing highlight will be removed. The highlight is mutually
exclusive.
*
- * Highlighting is mutually exclusive.
- *
- * @param {OO.ui.OptionWidget} [item] Item to highlight, omit to deselect all
+ * @param {OO.ui.OptionWidget} [item] Item to highlight, omit for no highlight
* @fires highlight
* @chainable
*/
@@ -371,7 +391,8 @@
};
/**
- * Select an item.
+ * Programmatically select an option by its reference. If the `item` parameter
is omitted,
+ * all options will be deselected.
*
* @param {OO.ui.OptionWidget} [item] Item to select, omit to deselect all
* @fires select
@@ -438,11 +459,14 @@
};
/**
- * Get an item relative to another one.
+ * Get an option by its position relative to the specified item (or to the
start of the option array,
+ * if item is `null`). The direction in which to search through the option
array is specified with a
+ * number: -1 for reverse (the default) or 1 for forward. The method will
return an option, or
+ * `null` if there are no options in the array.
*
- * @param {OO.ui.OptionWidget|null} item Item to start at, null to get
relative to list start
- * @param {number} direction Direction to move in, -1 to move backward, 1 to
move forward
- * @return {OO.ui.OptionWidget|null} Item at position, `null` if there are no
items in the menu
+ * @param {OO.ui.OptionWidget|null} item Item to describe the start position,
or `null` to start at the beginning of the array.
+ * @param {number} direction Direction to move in: -1 to move backward, 1 to
move forward
+ * @return {OO.ui.OptionWidget|null} Item at position, `null` if there are no
items in the select
*/
OO.ui.SelectWidget.prototype.getRelativeSelectableItem = function ( item,
direction ) {
var currentIndex, nextIndex, i,
@@ -469,7 +493,8 @@
};
/**
- * Get the next selectable item.
+ * Get the next selectable item or `null` if there are no selectable items.
+ * Disabled options and menu-section markers and breaks are not selectable.
*
* @return {OO.ui.OptionWidget|null} Item, `null` if there aren't any
selectable items
*/
@@ -487,7 +512,8 @@
};
/**
- * Add items.
+ * Add an array of options to the select. Optionally, an index number can be
used to
+ * specify an insertion point.
[MediaWiki-commits] [Gerrit] RadioOptionWidget: Add description - change (oojs/ui)
Kmenger has uploaded a new change for review. https://gerrit.wikimedia.org/r/192970 Change subject: RadioOptionWidget: Add description .. RadioOptionWidget: Add description Change-Id: I84e99e459d97def23fb2571b6939b0310a235067 --- M src/widgets/RadioOptionWidget.js 1 file changed, 4 insertions(+), 2 deletions(-) git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/70/192970/1 diff --git a/src/widgets/RadioOptionWidget.js b/src/widgets/RadioOptionWidget.js index 3663e8f..1cfe8af 100644 --- a/src/widgets/RadioOptionWidget.js +++ b/src/widgets/RadioOptionWidget.js @@ -1,7 +1,9 @@ /** - * Option widget that looks like a radio button. + * RadioOptionWidget is an option widget that looks like a radio button. + * The class is used with OO.ui.RadioSelectWidget to create a selection of radio options. + * Please see the [OOjs UI documentation on MediaWiki] [1] for more information. * - * Use together with OO.ui.RadioSelectWidget. + * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Button_selects_and_option * * @class * @extends OO.ui.OptionWidget -- To view, visit https://gerrit.wikimedia.org/r/192970 To unsubscribe, visit https://gerrit.wikimedia.org/r/settings Gerrit-MessageType: newchange Gerrit-Change-Id: I84e99e459d97def23fb2571b6939b0310a235067 Gerrit-PatchSet: 1 Gerrit-Project: oojs/ui Gerrit-Branch: master Gerrit-Owner: Kmenger kmen...@wikimedia.org ___ MediaWiki-commits mailing list MediaWiki-commits@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] MenuSelectWidget: Add description and mark protected method - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/193004
Change subject: MenuSelectWidget: Add description and mark protected method
..
MenuSelectWidget: Add description and mark protected method
Change-Id: I9f9b7d6475500329adaa08ea8aa320aae355380b
---
M src/widgets/MenuSelectWidget.js
1 file changed, 17 insertions(+), 4 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/04/193004/1
diff --git a/src/widgets/MenuSelectWidget.js b/src/widgets/MenuSelectWidget.js
index 2ec1f00..24d7e97 100644
--- a/src/widgets/MenuSelectWidget.js
+++ b/src/widgets/MenuSelectWidget.js
@@ -1,10 +1,22 @@
/**
- * Overlaid menu of options.
+ * MenuSelectWidget is a {@link OO.ui.SelectWidget select widget} that
contains options and
+ * is used together with OO.ui.MenuOptionWidget. See {@link
OO.ui.DropdownWidget DropdownWidget} and
+ * {@link OO.ui.ComboBoxWidget ComboBoxWidget} for examples of interfaces that
contain menus.
+ * MenuSelectWidgets themselves are not designed to be instantiated directly,
rather subclassed
+ * and customized to be opened, closed, and displayed as needed.
*
- * Menus are clipped to the visible viewport. They do not provide a control
for opening or closing
- * the menu.
+ * By default, menus are clipped to the visible viewport and are not visible
when a user presses the
+ * mouse outside the menu.
*
- * Use together with OO.ui.MenuOptionWidget.
+ * Menus also have support for keyboard interaction:
+ *
+ * - Enter/Return key: choose and select a menu option
+ * - Up-arrow key: highlight the previous menu option
+ * - Down-arrow key: highlight the next menu option
+ * - Esc key: hide the menu
+ *
+ * Please see the [OOjs UI documentation on MediaWiki][1] for more information.
+ * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
*
* @class
* @extends OO.ui.SelectWidget
@@ -55,6 +67,7 @@
/**
* Handles document mouse down events.
*
+ * @protected
* @param {jQuery.Event} e Key down event
*/
OO.ui.MenuSelectWidget.prototype.onDocumentMouseDown = function ( e ) {
--
To view, visit https://gerrit.wikimedia.org/r/193004
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I9f9b7d6475500329adaa08ea8aa320aae355380b
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] TabIndexelement: Add description, example, and mark private ... - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/193019
Change subject: TabIndexelement: Add description, example, and mark private
method
..
TabIndexelement: Add description, example, and mark private method
Change-Id: Ie8e247d71148457531e0cfce9885ec33932d0ba1
---
M src/elements/TabIndexedElement.js
1 file changed, 25 insertions(+), 1 deletion(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/19/193019/1
diff --git a/src/elements/TabIndexedElement.js
b/src/elements/TabIndexedElement.js
index fa1954f..70b3ef9 100644
--- a/src/elements/TabIndexedElement.js
+++ b/src/elements/TabIndexedElement.js
@@ -1,5 +1,28 @@
/**
- * Element supporting sequential focus navigation using the 'tabindex'
attribute.
+ * The TabIndexedElement class is an attribute mixin used to add additional
functionality to an
+ * element created by another class. The mixin provides a ‘tabIndex’ property,
which specifies the
+ * order in which users will navigate through the focusable elements via the
tab key.
+ *
+ * @example
+ * // TabIndexedElement is mixed into the ButtonWidget class
+ * // to provide a tabIndex property.
+ * var button1 = new OO.ui.ButtonWidget( {
+ * label : 'fourth',
+ * tabIndex : 4
+ * } );
+ * var button2 = new OO.ui.ButtonWidget( {
+ * label : 'second',
+ * tabIndex : 2
+ * } );
+ * var button3 = new OO.ui.ButtonWidget( {
+ * label : 'third',
+ * tabIndex : 3
+ * } );
+ * var button4 = new OO.ui.ButtonWidget( {
+ * label : 'first',
+ * tabIndex : 1
+ * } );
+ * $( 'body' ).append( button1.$element, button2.$element,
button3.$element, button4.$element );
*
* @abstract
* @class
@@ -92,6 +115,7 @@
/**
* Handle disable events.
*
+ * @private
* @param {boolean} disabled Element is disabled
*/
OO.ui.TabIndexedElement.prototype.onDisable = function () {
--
To view, visit https://gerrit.wikimedia.org/r/193019
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: Ie8e247d71148457531e0cfce9885ec33932d0ba1
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] RadioSelectWidget: Add description and example - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/192979
Change subject: RadioSelectWidget: Add description and example
..
RadioSelectWidget: Add description and example
Change-Id: I74aa4c7a7f45b31075807fa8b18f69eb55de3b78
---
M src/widgets/RadioSelectWidget.js
1 file changed, 27 insertions(+), 2 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/79/192979/1
diff --git a/src/widgets/RadioSelectWidget.js b/src/widgets/RadioSelectWidget.js
index 2f405dc..e6cab86 100644
--- a/src/widgets/RadioSelectWidget.js
+++ b/src/widgets/RadioSelectWidget.js
@@ -1,7 +1,32 @@
/**
- * Select widget containing radio button options.
+ * RadioSelectWidget is a {@link OO.ui.SelectWidget select widget} that
contains radio
+ * options and is used together with OO.ui.RadioOptionWidget. The
RadioSelectWidget provides
+ * an interface for adding, removing and selecting options.
+ * Please see the [OOjs UI documentation on MediaWiki][1] for more information.
*
- * Use together with OO.ui.RadioOptionWidget.
+ * @example
+ * // A RadioSelectWidget with RadioOptions.
+ * var option1 = new OO.ui.RadioOptionWidget( {
+ * data: 'a',
+ * label: 'Selected radio option'
+ * } );
+ *
+ * var option2 = new OO.ui.RadioOptionWidget( {
+ * data: 'b',
+ * label: 'Unselected radio option'
+ * } );
+ *
+ * var radioSelect=new OO.ui.RadioSelectWidget( {
+ * items: [option1, option2]
+ * } );
+ *
+ * // Select 'option 1' using the RadioSelectWidget's selectItem() method.
+ * radioSelect.selectItem( option1 );
+ *
+ * $('body').append(radioSelect.$element);
+ *
+ * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
+
*
* @class
* @extends OO.ui.SelectWidget
--
To view, visit https://gerrit.wikimedia.org/r/192979
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I74aa4c7a7f45b31075807fa8b18f69eb55de3b78
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] MenuOptionWidget: Add description - change (oojs/ui)
Kmenger has uploaded a new change for review. https://gerrit.wikimedia.org/r/192991 Change subject: MenuOptionWidget: Add description .. MenuOptionWidget: Add description Change-Id: Ib7832ab103ba5e2b3adb2c92e9d6be9a04cc3c8f --- M src/widgets/MenuOptionWidget.js 1 file changed, 5 insertions(+), 1 deletion(-) git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/91/192991/1 diff --git a/src/widgets/MenuOptionWidget.js b/src/widgets/MenuOptionWidget.js index e58d913..cc620d9 100644 --- a/src/widgets/MenuOptionWidget.js +++ b/src/widgets/MenuOptionWidget.js @@ -1,5 +1,9 @@ /** - * Item of an OO.ui.MenuSelectWidget. + * MenuOptionWidget is an option widget that looks like a menu item. The class is used with + * OO.ui.MenuSelectWidget to create a menu of mutually exclusive options. Please see + * the [OOjs UI documentation on MediaWiki] [1] for more information. + * + * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Menu_selects_and_options * * @class * @extends OO.ui.DecoratedOptionWidget -- To view, visit https://gerrit.wikimedia.org/r/192991 To unsubscribe, visit https://gerrit.wikimedia.org/r/settings Gerrit-MessageType: newchange Gerrit-Change-Id: Ib7832ab103ba5e2b3adb2c92e9d6be9a04cc3c8f Gerrit-PatchSet: 1 Gerrit-Project: oojs/ui Gerrit-Branch: master Gerrit-Owner: Kmenger kmen...@wikimedia.org ___ MediaWiki-commits mailing list MediaWiki-commits@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] IconElement: Add description for config options - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/192348
Change subject: IconElement: Add description for config options
..
IconElement: Add description for config options
Change-Id: I21d1532d382562d84f74706975807b16dc822b8c
---
M src/elements/IconElement.js
1 file changed, 23 insertions(+), 5 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/48/192348/1
diff --git a/src/elements/IconElement.js b/src/elements/IconElement.js
index e5ba688..8634815 100644
--- a/src/elements/IconElement.js
+++ b/src/elements/IconElement.js
@@ -12,11 +12,29 @@
*
* @constructor
* @param {Object} [config] Configuration options
- * @cfg {jQuery} [$icon] Icon node, assigned to #$icon, omit to use a
generated `span`
- * @cfg {Object|string} [icon=''] Symbolic icon name, or map of icon names
keyed by language ID;
- * use the 'default' key to specify the icon to be used when there is no icon
in the user's
- * language
- * @cfg {string} [iconTitle] Icon title text or a function that returns text
+ * @cfg {jQuery} [$icon] The icon element created by the class. If this
configuration is omitted,
+ * the icon element will use a generated `span`. To use a different HTML
tag, or to specify that
+ * the icon element be set to an existing icon instead of the one generated
by this class, set a
+ * value using a jQuery selection. For example:
+ *
+ * // Use a div tag instead of a span
+ * $icon: $(div)
+ * // Use an existing icon element instead of the one generated by the
class
+ * $icon: this.$element
+ * // Use an icon element from a child widget
+ * $icon: this.childwidget.$element
+ * @cfg {Object|string} [icon=''] The symbolic name of the icon (e.g.,
‘remove’ or ‘menu’), or a map of
+ * symbolic names. A map is used for i18n purposes and contains a `default`
icon
+ * name and additional names keyed by language code. The `default` name is
used when no icon is keyed
+ * by the user's language.
+ *
+ * Example of an i18n map:
+ *
+ * { default: 'bold-a', en: 'bold-b', de: 'bold-f' }
+ * See the [OOjs UI documentation on MediaWiki] [2] for a list of icons
included in the library.
+ * [2]:
https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Icons
+ * @cfg {string|Function} [iconTitle] A text string used as the icon title, or
a function that returns title
+ * text. The icon title is displayed when users move the mouse over the icon.
*/
OO.ui.IconElement = function OoUiIconElement( config ) {
// Configuration initialization
--
To view, visit https://gerrit.wikimedia.org/r/192348
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I21d1532d382562d84f74706975807b16dc822b8c
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] IconElement: Add description of methods - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/192361
Change subject: IconElement: Add description of methods
..
IconElement: Add description of methods
Change-Id: I5e16ffdf31f1be7a715903c01216dc5f4ed0a1c1
---
M src/elements/IconElement.js
1 file changed, 14 insertions(+), 12 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/61/192361/1
diff --git a/src/elements/IconElement.js b/src/elements/IconElement.js
index e5ba688..676b503 100644
--- a/src/elements/IconElement.js
+++ b/src/elements/IconElement.js
@@ -71,9 +71,10 @@
/* Methods */
/**
- * Set the icon element.
- *
- * If an element is already set, it will be cleaned up before setting up the
new element.
+ * Set the icon element. This method is used to retarget an icon mixin so that
its functionality
+ * applies to the specified icon element instead of the one created by the
class. If an icon
+ * element is already set, the mixin’s effect on that element is removed.
Generated CSS classes
+ * and mixin methods will no longer affect the element.
*
* @param {jQuery} $icon Element to use as icon
*/
@@ -93,11 +94,12 @@
};
/**
- * Set icon name.
+ * Set icon by symbolic name (e.g., ‘remove’ or ‘menu’). Use `null` to remove
an icon.
+ * The icon parameter can also be set to a map of icon names. See the #icon
config setting
+ * for an example.
*
- * @param {Object|string|null} icon Symbolic icon name, or map of icon names
keyed by language ID;
- * use the 'default' key to specify the icon to be used when there is no icon
in the user's
- * language, use null to remove icon
+ * @param {Object|string|null} icon A symbolic icon name, a {@link #icon map
of icon names} keyed
+ * by language code, or `null` to remove the icon.
* @chainable
*/
OO.ui.IconElement.prototype.setIcon = function ( icon ) {
@@ -123,10 +125,10 @@
};
/**
- * Set icon title.
+ * Set the icon title. Use `null` to remove the title.
*
- * @param {string|Function|null} icon Icon title text, a function that returns
text or null
- * for no icon title
+ * @param {string|Function|null} iconTitle A text string used as the icon
title,
+ * a function that returns title text, or `null` for no title.
* @chainable
*/
OO.ui.IconElement.prototype.setIconTitle = function ( iconTitle ) {
@@ -149,7 +151,7 @@
};
/**
- * Get icon name.
+ * Get the symbolic name of the icon.
*
* @return {string} Icon name
*/
@@ -158,7 +160,7 @@
};
/**
- * Get icon title.
+ * Get the icon title. The title text is displayed when a user moves the mouse
over the icon.
*
* @return {string} Icon title text
*/
--
To view, visit https://gerrit.wikimedia.org/r/192361
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I5e16ffdf31f1be7a715903c01216dc5f4ed0a1c1
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] DraggableElement: Mark private methods and add description t... - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/192379
Change subject: DraggableElement: Mark private methods and add description to
events
..
DraggableElement: Mark private methods and add description to events
Change-Id: I0263f0face3cc70d5f5d1bf77bdc4abf7bb85e9a
---
M src/elements/DraggableElement.js
1 file changed, 19 insertions(+), 1 deletion(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/79/192379/1
diff --git a/src/elements/DraggableElement.js b/src/elements/DraggableElement.js
index 5ad79f9..9ae4d5b 100644
--- a/src/elements/DraggableElement.js
+++ b/src/elements/DraggableElement.js
@@ -31,15 +31,21 @@
/**
* @event dragstart
- * @param {OO.ui.DraggableElement} item Dragging item
+ *
+ * A dragstart event is emitted when the user clicks and begins dragging an
item.
+ * @param {OO.ui.DraggableElement} item The item the user has clicked and is
dragging with the mouse.
*/
/**
* @event dragend
+ * A dragend event is emitted when the user drags an item and releases the
mouse,
+ * thus terminating the drag operation.
*/
/**
* @event drop
+ * A drop event is emitted when the user drags an item and then releases the
mouse button
+ * over a valid target.
*/
/* Static Properties */
@@ -53,6 +59,8 @@
/**
* Respond to dragstart event.
+ *
+ * @private
* @param {jQuery.Event} event jQuery event
* @fires dragstart
*/
@@ -78,6 +86,8 @@
/**
* Respond to dragend event.
+ *
+ * @private
* @fires dragend
*/
OO.ui.DraggableElement.prototype.onDragEnd = function () {
@@ -87,6 +97,8 @@
/**
* Handle drop event.
+ *
+ * @private
* @param {jQuery.Event} event jQuery event
* @fires drop
*/
@@ -98,6 +110,8 @@
/**
* In order for drag/drop to work, the dragover event must
* return false and stop propogation.
+ *
+ * @private
*/
OO.ui.DraggableElement.prototype.onDragOver = function ( e ) {
e.preventDefault();
@@ -106,6 +120,8 @@
/**
* Set item index.
* Store it in the DOM so we can access from the widget drag event
+ *
+ * @private
* @param {number} Item index
*/
OO.ui.DraggableElement.prototype.setIndex = function ( index ) {
@@ -117,6 +133,8 @@
/**
* Get item index
+ *
+ * @private
* @return {number} Item index
*/
OO.ui.DraggableElement.prototype.getIndex = function () {
--
To view, visit https://gerrit.wikimedia.org/r/192379
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I0263f0face3cc70d5f5d1bf77bdc4abf7bb85e9a
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] Element: Add description for configs and static property - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/192390
Change subject: Element: Add description for configs and static property
..
Element: Add description for configs and static property
Change-Id: I61a64c5d11c1fdb2870e8e04ebdec634745cdd5a
---
M src/Element.js
1 file changed, 10 insertions(+), 6 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/90/192390/1
diff --git a/src/Element.js b/src/Element.js
index 1693929..0bc5e14 100644
--- a/src/Element.js
+++ b/src/Element.js
@@ -8,11 +8,15 @@
*
* @constructor
* @param {Object} [config] Configuration options
- * @cfg {string[]} [classes] CSS class names to add
- * @cfg {string} [id] HTML id attribute
+ * @cfg {string[]} [classes] The names of the CSS classes to apply to the
element. CSS styles are added
+ * to the top level (e.g., the outermost div) of the element. See the [OOjs
UI documentation on MediaWiki][2]
+ * for an example.
+ * [2]:
https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Buttons_and_Switches#cssExample
+ * @cfg {string} [id] The HTML id attribute used in the rendered tag.
* @cfg {string} [text] Text to insert
- * @cfg {jQuery} [$content] Content elements to append (after text)
- * @cfg {Mixed} [data] Element data
+ * @cfg {jQuery} [$content] Content elements to append (after #text)
+ * @cfg {Mixed} [data] Custom data of any type or combination of types (e.g.,
string, number, array, object).
+ * Data can also be specified with the #setData method.
*/
OO.ui.Element = function OoUiElement( config ) {
// Configuration initialization
@@ -49,9 +53,9 @@
/* Static Properties */
/**
- * HTML tag name.
+ * The name of the HTML tag used by the element.
*
- * This may be ignored if #getTagName is overridden.
+ * The static value may be ignored if the #getTagName method is overridden.
*
* @static
* @inheritable
--
To view, visit https://gerrit.wikimedia.org/r/192390
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I61a64c5d11c1fdb2870e8e04ebdec634745cdd5a
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] Window: Add description - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/191363
Change subject: Window: Add description
..
Window: Add description
Change-Id: I859cf21f42743af2b5cb09389b8a222a1e094299
---
M src/Window.js
1 file changed, 32 insertions(+), 27 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/63/191363/1
diff --git a/src/Window.js b/src/Window.js
index f457ea6..9e8334f 100644
--- a/src/Window.js
+++ b/src/Window.js
@@ -1,37 +1,42 @@
/**
- * Encapsulation of an user interface.
+ * A window is a container for elements that are in a child frame. They are
used with
+ * a window manager (OO.ui.WindowManager), which is used to open and close the
window and control
+ * its presentation. The size of a window is specified using a symbolic name
(e.g., ‘small’, ‘medium’,
+ * ‘large’), which is interpreted by the window manager. If the requested size
is not recognized,
+ * the window manager will choose a sensible fallback.
*
- * Use together with OO.ui.WindowManager.
+ * The lifecycle of a window has three primary stages (opening, opened, and
closing) in which
+ * different processes are executed:
+ *
+ * **opening**: The opening stage begins when the window manager's {@link
OO.ui.WindowManager#openWindow
+ * openWindow} or the window's {@link #open open} methods are used, and the
window manager begins to open
+ * the window.
+ *
+ * - {@link #getSetupProcess} method is called and its result executed
+ * - {@link #getReadyProcess} method is called and its result executed
+ *
+ * **opened**: The window is now open
+ *
+ * **closing**: The closing stage begins when the window manager's
+ * {@link OO.ui.WindowManager#closeWindow closeWindow}
+ * or the window's {@link #close} methods are used, and the window manager
begins to close the window.
+ *
+ * - {@link #getHoldProcess} method is called and its result executed
+ * - {@link #getTeardownProcess} method is called and its result executed. The
window is now closed
+ *
+ * Each of the window's processes (setup, ready, hold, and teardown) can be
extended in subclasses
+ * by overriding the window's #getSetupProcess, #getReadyProcess,
#getHoldProcess and #getTeardownProcess
+ * methods. Note that each {@link OO.ui.Process process} is executed in
series, so asynchronous
+ * processing can complete. Always assume window processes are executed
asynchronously.
+ *
+ * For more information, please see the [OOjs UI documentation on MediaWiki]
[1].
+ *
+ * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Windows
*
* @abstract
* @class
* @extends OO.ui.Element
* @mixins OO.EventEmitter
- *
- * When a window is opened, the setup and ready processes are executed.
Similarly, the hold and
- * teardown processes are executed when the window is closed.
- *
- * - {@link OO.ui.WindowManager#openWindow} or {@link #open} methods are used
to start opening
- * - Window manager begins opening window
- * - {@link #getSetupProcess} method is called and its result executed
- * - {@link #getReadyProcess} method is called and its result executed
- * - Window is now open
- *
- * - {@link OO.ui.WindowManager#closeWindow} or {@link #close} methods are
used to start closing
- * - Window manager begins closing window
- * - {@link #getHoldProcess} method is called and its result executed
- * - {@link #getTeardownProcess} method is called and its result executed
- * - Window is now closed
- *
- * Each process (setup, ready, hold and teardown) can be extended in
subclasses by overriding
- * {@link #getSetupProcess}, {@link #getReadyProcess}, {@link #getHoldProcess}
and
- * {@link #getTeardownProcess} respectively. Each process is executed in
series, so asynchronous
- * processing can complete. Always assume window processes are executed
asynchronously. See
- * OO.ui.Process for more details about how to work with processes. Some
events, as well as the
- * #open and #close methods, provide promises which are resolved when the
window enters a new state.
- *
- * Sizing of windows is specified using symbolic names which are interpreted
by the window manager.
- * If the requested size is not recognized, the window manager will choose a
sensible fallback.
*
* @constructor
* @param {Object} [config] Configuration options
--
To view, visit https://gerrit.wikimedia.org/r/191363
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I859cf21f42743af2b5cb09389b8a222a1e094299
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] WindowManager: Add description - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/191371
Change subject: WindowManager: Add description
..
WindowManager: Add description
Change-Id: I250098985bda020d2526c580e049cbb71d37cd3a
---
M src/WindowManager.js
1 file changed, 43 insertions(+), 32 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/71/191371/1
diff --git a/src/WindowManager.js b/src/WindowManager.js
index 6e74df1..28ebb11 100644
--- a/src/WindowManager.js
+++ b/src/WindowManager.js
@@ -1,40 +1,51 @@
/**
- * Collection of windows.
+ * Window managers are used to open and close {@link OO.ui.Window windows} and
control their presentation.
+ * Managed windows are mutually exclusive. If a new window is opened while a
current window is opening
+ * or is opened, the current window will be closed and any ongoing {@link
OO.ui.Process process} will be cancelled. Windows
+ * themselves are persistent and—rather than being torn down when closed—can
be repopulated with the
+ * pertinent data and reused.
+ *
+ * Over the lifecycle of a window, the window manager makes available three
promises: `opening`,
+ * `opened`, and `closing`, which represent the primary stages of the cycle:
+ *
+ * **Opening**: the opening stage begins when the window manager’s #openWindow
or a window’s
+ * {@link OO.ui.Window#open open} method is used, and the window manager
begins to open the window.
+ *
+ * - an `opening` event is emitted with an `opening` promise
+ * - the #getSetupDelay method is called and the returned value is used to
time a pause in execution before
+ * the window’s {@link OO.ui.Window#getSetupProcess getSetupProcess} method
is called on the
+ * window and its result executed
+ * - a `setup` progress notification is emitted from the `opening` promise
+ * - the #getReadyDelay method is called the returned value is used to time a
pause in execution before
+ * the window’s {@link OO.ui.Window#getReadyProcess getReadyProcess} method
is called on the
+ * window and its result executed
+ * - a `ready` progress notification is emitted from the `opening` promise
+ * - the `opening` promise is resolved with an `opened` promise
+ *
+ * **Opened**: the window is now open.
+ *
+ * **Closing**: the closing stage begins when the window manager's
#closeWindow or the
+ * window's {@link OO.ui.Window#close close} methods is used, and the window
manager begins
+ * to close the window.
+ *
+ * - the `opened` promise is resolved with `closing` promise and a `closing`
event is emitted
+ * - the #getHoldDelay method is called and the returned value is used to time
a pause in execution before
+ * the window's {@link OO.ui.Window#getHoldProcess getHoldProces} method is
called on the
+ * window and its result executed
+ * - a `hold` progress notification is emitted from the `closing` promise
+ * - the #getTeardownDelay() method is called and the returned value is used
to time a pause in execution before
+ * the window's {@link OO.ui.Window#getTeardownProcess getTeardownProcess}
method is called on the
+ * window and its result executed
+ * - a `teardown` progress notification is emitted from the `closing` promise
+ * - the `closing` promise is resolved. The window is now closed
+ *
+ * See the [OOjs UI documentation on MediaWiki][1] for more information.
+ *
+ * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Windows/Window_managers
*
* @class
* @extends OO.ui.Element
* @mixins OO.EventEmitter
- *
- * Managed windows are mutually exclusive. If a window is opened while there
is a current window
- * already opening or opened, the current window will be closed without data.
Empty closing data
- * should always result in the window being closed without causing
constructive or destructive
- * action.
- *
- * As a window is opened and closed, it passes through several stages and the
manager emits several
- * corresponding events.
- *
- * - {@link #openWindow} or {@link OO.ui.Window#open} methods are used to
start opening
- * - {@link #event-opening} is emitted with `opening` promise
- * - {@link #getSetupDelay} is called the returned value is used to time a
pause in execution
- * - {@link OO.ui.Window#getSetupProcess} method is called on the window and
its result executed
- * - `setup` progress notification is emitted from opening promise
- * - {@link #getReadyDelay} is called the returned value is used to time a
pause in execution
- * - {@link OO.ui.Window#getReadyProcess} method is called on the window and
its result executed
- * - `ready` progress notification is emitted from opening promise
- * - `opening` promise is resolved with `opened` promise
- * - Window is now open
- *
- * - {@link #closeWindow} or {@link OO.ui.Window#close} methods are used to
start closing
- * - `opened` promise is resolved with `closing` promise
- * - {@link #event-closing} is emitted with `closing` promise
- * - {@link
[MediaWiki-commits] [Gerrit] DropdownWidget: Add description and example - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/191477
Change subject: DropdownWidget: Add description and example
..
DropdownWidget: Add description and example
Change-Id: I347f67a8aa32b456b444206335e1b55a1e82a731
---
M src/widgets/DropdownWidget.js
1 file changed, 29 insertions(+), 4 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/77/191477/1
diff --git a/src/widgets/DropdownWidget.js b/src/widgets/DropdownWidget.js
index b5e7708..bc10e7c 100644
--- a/src/widgets/DropdownWidget.js
+++ b/src/widgets/DropdownWidget.js
@@ -1,10 +1,35 @@
/**
- * Dropdown menu of options.
+ * DropdownWidgets are not menus themselves, rather they contain a menu of
options created with
+ * OO.ui.MenuOptionWidget. The DropdownWidget takes care of opening and
displaying the menu so that
+ * users can interact with it.
*
- * Dropdown menus provide a control for accessing a menu and compose a menu
within the widget, which
- * can be accessed using the #getMenu method.
+ * @example
+ * // Example: A DropdownWidget with a menu that contains three options
+ * var dropDown=new OO.ui.DropdownWidget( {
+ * label: 'Dropdown menu: Select a menu option',
+ * menu: {
+ * items: [
+ * new OO.ui.MenuOptionWidget( {
+ * data: 'a',
+ * label: 'First'
+ * } ),
+ * new OO.ui.MenuOptionWidget( {
+ * data: 'b',
+ * label: 'Second'
+ * } ),
+ * new OO.ui.MenuOptionWidget( {
+ * data: 'c',
+ * label: 'Third'
+ * } )
+ * ]
+ * }
+ * } );
*
- * Use with OO.ui.MenuOptionWidget.
+ * $('body').append(dropDown.$element);
+
+For more information, please see the [OOjs UI documentation on MediaWiki] [1].
+
+[1]:
https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Menu_selects_and_options
*
* @class
* @extends OO.ui.Widget
--
To view, visit https://gerrit.wikimedia.org/r/191477
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I347f67a8aa32b456b444206335e1b55a1e82a731
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] DropdownWidget: Add @private to private methods - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/191397
Change subject: DropdownWidget: Add @private to private methods
..
DropdownWidget: Add @private to private methods
Change-Id: Iab13bbce9efc45ae9d3e5a24d74e99988f4b691f
---
M src/widgets/DropdownWidget.js
1 file changed, 3 insertions(+), 0 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/97/191397/1
diff --git a/src/widgets/DropdownWidget.js b/src/widgets/DropdownWidget.js
index 03c1c84..b5e7708 100644
--- a/src/widgets/DropdownWidget.js
+++ b/src/widgets/DropdownWidget.js
@@ -77,6 +77,7 @@
/**
* Handles menu select events.
*
+ * @private
* @param {OO.ui.MenuOptionWidget} item Selected menu item
*/
OO.ui.DropdownWidget.prototype.onMenuSelect = function ( item ) {
@@ -99,6 +100,7 @@
/**
* Handle mouse click events.
*
+ * @private
* @param {jQuery.Event} e Mouse click event
*/
OO.ui.DropdownWidget.prototype.onClick = function ( e ) {
@@ -111,6 +113,7 @@
/**
* Handle key press events.
*
+ * @private
* @param {jQuery.Event} e Key press event
*/
OO.ui.DropdownWidget.prototype.onKeyPress = function ( e ) {
--
To view, visit https://gerrit.wikimedia.org/r/191397
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: Iab13bbce9efc45ae9d3e5a24d74e99988f4b691f
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] ButtonGroupWidget: Add description and example - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/191391
Change subject: ButtonGroupWidget: Add description and example
..
ButtonGroupWidget: Add description and example
Change-Id: Ie81db7e740045ff84f08bd7e916408c48b704990
---
M src/widgets/ButtonGroupWidget.js
1 file changed, 21 insertions(+), 2 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/91/191391/1
diff --git a/src/widgets/ButtonGroupWidget.js b/src/widgets/ButtonGroupWidget.js
index 2fd95f6..eda2541 100644
--- a/src/widgets/ButtonGroupWidget.js
+++ b/src/widgets/ButtonGroupWidget.js
@@ -1,7 +1,26 @@
/**
- * Group widget for multiple related buttons.
+ * A ButtonGroupWidget groups related buttons and is used together with
OO.ui.ButtonWidget and
+ * its subclasses. Each button in a group is addressed by a unique reference.
Buttons can be added,
+ * removed, and cleared from the group.
*
- * Use together with OO.ui.ButtonWidget.
+ * @example
+ * // Example: A ButtonGroupWidget with two buttons
+ * var button1 = new OO.ui.PopupButtonWidget( {
+ * label : 'Select a category',
+ * icon : 'menu',
+ * popup : {
+ * $content: $( 'pList of categories.../p' ),
+ * padded: true,
+ * align: 'left'
+ * }
+ * } );
+ * var button2 = new OO.ui.ButtonWidget( {
+ * label : 'Add item'
+ * });
+ * var buttonGroup = new OO.ui.ButtonGroupWidget( {
+ * items: [button1, button2]
+ * } );
+ * $('body').append(buttonGroup.$element);
*
* @class
* @extends OO.ui.Widget
--
To view, visit https://gerrit.wikimedia.org/r/191391
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: Ie81db7e740045ff84f08bd7e916408c48b704990
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] ActionSet: Add description and example - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/191493
Change subject: ActionSet: Add description and example
..
ActionSet: Add description and example
Change-Id: Ifa65609cb7eaf4e2dfab311db9e68750bba9650c
---
M src/ActionSet.js
1 file changed, 62 insertions(+), 1 deletion(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/93/191493/1
diff --git a/src/ActionSet.js b/src/ActionSet.js
index 7feac3a..2093c12 100644
--- a/src/ActionSet.js
+++ b/src/ActionSet.js
@@ -1,5 +1,66 @@
/**
- * List of actions.
+ * ActionSets manage the behavior of the {@link OO.ui.ActionWidget Action
widgets} that comprise them.
+ * Actions can be made available for specific contexts (modes) and
circumstances
+ * (abilities). Please see the [OOjs UI documentation on MediaWiki][1] for
more information.
+ *
+ * @example
+ * // Example: An action set used in a process dialog
+ * function ProcessDialog( config ) {
+ * ProcessDialog.super.call( this, config );
+ * }
+ * OO.inheritClass( ProcessDialog, OO.ui.ProcessDialog );
+ * ProcessDialog.static.title = 'An action set in a process dialog';
+ * // An action set that uses modes ('edit' and 'help' mode, in this
example).
+ * ProcessDialog.static.actions = [
+ *{ action: 'continue', modes: 'edit', label: 'Continue', flags: [
'primary', 'constructive' ] },
+ *{ action: 'help', modes: 'edit', label: 'Help' },
+ *{ modes: 'edit', label: 'Cancel', flags: 'safe' },
+ *{ action: 'back', modes: 'help', label: 'Back', flags: 'safe' }
+ * ];
+ *
+ * ProcessDialog.prototype.initialize = function () {
+ * ProcessDialog.super.prototype.initialize.apply( this, arguments );
+ * this.panel1 = new OO.ui.PanelLayout( { $: this.$, padded: true,
expanded: false } );
+ * this.panel1.$element.append( 'pThis dialog uses an action set
(continue, help, cancel, back) configured with modes. This is edit mode. Click
\'help\' to see help mode. /p' );
+ * this.panel2 = new OO.ui.PanelLayout( { $: this.$, padded: true,
expanded: false } );
+ * this.panel2.$element.append( 'pThis is help mode. Only the
\'back\' action widget is configured to be visible here. Click \'back\' to
return to \'edit\' mode/p' );
+ * this.stackLayout= new OO.ui.StackLayout( {
+ * items: [ this.panel1, this.panel2 ]
+ * });
+ * this.$body.append( this.stackLayout.$element );
+ * };
+ * ProcessDialog.prototype.getSetupProcess = function ( data ) {
+ * return ProcessDialog.super.prototype.getSetupProcess.call( this,
data )
+ * .next( function () {
+ * this.actions.setMode('edit');
+ * }, this );
+ * };
+ * ProcessDialog.prototype.getActionProcess = function ( action ) {
+ * if ( action === 'help' ) {
+ * this.actions.setMode( 'help' );
+ * this.stackLayout.setItem( this.panel2 );
+ * } else if ( action === 'back' ) {
+ * this.actions.setMode( 'edit' );
+ * this.stackLayout.setItem( this.panel1 );
+ * } else if ( action === 'continue' ) {
+ * var dialog = this;
+ * return new OO.ui.Process( function () {
+ * dialog.close();
+ * } );
+ * }
+ * return ProcessDialog.super.prototype.getActionProcess.call( this,
action );
+ * };
+ * ProcessDialog.prototype.getBodyHeight = function () {
+ * return this.panel1.$element.outerHeight( true );
+ * };
+ * var windowManager = new OO.ui.WindowManager();
+ * $( 'body' ).append( windowManager.$element );
+ * var processDialog = new ProcessDialog({
+ *size: 'medium'});
+ * windowManager.addWindows( [ processDialog ] );
+ * windowManager.openWindow( processDialog );
+ *
+ * [1]:
https://www.mediawiki.org/wiki/OOjs_UI/Windows/Process_Dialogs#Action_sets
*
* @abstract
* @class
--
To view, visit https://gerrit.wikimedia.org/r/191493
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: Ifa65609cb7eaf4e2dfab311db9e68750bba9650c
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] ActionWidget: Add description - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/191507
Change subject: ActionWidget: Add description
..
ActionWidget: Add description
Change-Id: I1ec485e143269a52d51c0e1b501ca532e6de6531
---
M src/widgets/ActionWidget.js
1 file changed, 6 insertions(+), 1 deletion(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/07/191507/1
diff --git a/src/widgets/ActionWidget.js b/src/widgets/ActionWidget.js
index bbbae27..57f1a5c 100644
--- a/src/widgets/ActionWidget.js
+++ b/src/widgets/ActionWidget.js
@@ -1,5 +1,10 @@
/**
- * Button widget that executes an action and is managed by an OO.ui.ActionSet.
+ * An ActionWidget is a {@link OO.ui.ButtonWidget button widget} that executes
an action.
+ * Action widgets are used with OO.ui.ActionSet, which manages the behavior
and availability
+ * of the actions. Please see the [OOjs UI documentation on MediaWiki] [1] for
more information
+ * and examples.
+ *
+ * [1]:
https://www.mediawiki.org/wiki/OOjs_UI/Windows/Process_Dialogs#Action_sets
*
* @class
* @extends OO.ui.ButtonWidget
--
To view, visit https://gerrit.wikimedia.org/r/191507
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I1ec485e143269a52d51c0e1b501ca532e6de6531
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] IconElement: Add description and fix display of static prope... - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/191519
Change subject: IconElement: Add description and fix display of static
properties
..
IconElement: Add description and fix display of static properties
Change-Id: Ida72827810397f2c5991e33d008928f55bb43dc7
---
M src/elements/IconElement.js
1 file changed, 12 insertions(+), 12 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/19/191519/1
diff --git a/src/elements/IconElement.js b/src/elements/IconElement.js
index beed804..c742d2b 100644
--- a/src/elements/IconElement.js
+++ b/src/elements/IconElement.js
@@ -39,31 +39,31 @@
/* Static Properties */
/**
- * Icon.
+ * The symbolic name of the icon (e.g., ‘remove’ or ‘menu’), or a map of
symbolic names. A map is used
+ * for i18n purposes and contains a `default` icon name and additional names
keyed by
+ * language code. The `default` name is used when no icon is keyed by the
user's language.
*
- * Value should be the unique portion of an icon CSS class name, such as 'up'
for 'oo-ui-icon-up'.
+ * Example of an i18n map:
*
- * For i18n purposes, this property can be an object containing a `default`
icon name property and
- * additional icon names keyed by language code.
- *
- * Example of i18n icon definition:
* { default: 'bold-a', en: 'bold-b', de: 'bold-f' }
+ *
+ * Note: the static property will be overridden if the #icon configuration is
used.
*
* @static
* @inheritable
- * @property {Object|string} Symbolic icon name, or map of icon names keyed by
language ID;
- * use the 'default' key to specify the icon to be used when there is no icon
in the user's
- * language
+ * @property {Object|string}
*/
OO.ui.IconElement.static.icon = null;
/**
- * Icon title.
+ * The icon title, displayed when users move the mouse over the icon. The
value can be text, a
+ * function that returns title text, or `null` for no title.
+ *
+ * The static property will be overridden if the #iconTitle configuration is
used.
*
* @static
* @inheritable
- * @property {string|Function|null} Icon title text, a function that returns
text or null for no
- * icon title
+ * @property {string|Function|null}
*/
OO.ui.IconElement.static.iconTitle = null;
--
To view, visit https://gerrit.wikimedia.org/r/191519
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: Ida72827810397f2c5991e33d008928f55bb43dc7
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] ActionSet: Add description for specialFlags property - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/191500
Change subject: ActionSet: Add description for specialFlags property
..
ActionSet: Add description for specialFlags property
Change-Id: I7ac92b71191adac6004ff6ae018cccd915fad503
---
M src/ActionSet.js
1 file changed, 5 insertions(+), 1 deletion(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/00/191500/1
diff --git a/src/ActionSet.js b/src/ActionSet.js
index 4dbc4c2..0221236 100644
--- a/src/ActionSet.js
+++ b/src/ActionSet.js
@@ -98,7 +98,11 @@
/* Static Properties */
/**
- * Symbolic name of dialog.
+ * Symbolic name of the flags used to identify special actions. Special
actions are displayed in the
+ * header of a {@link OO.ui.ProcessDialog process dialog}.
+ * See the [OOjs UI documentation on MediaWiki][2] for more information and
examples.
+ *
+ * [2]:https://www.mediawiki.org/wiki/OOjs_UI/Windows/Process_Dialogs
*
* @abstract
* @static
--
To view, visit https://gerrit.wikimedia.org/r/191500
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I7ac92b71191adac6004ff6ae018cccd915fad503
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] ActionSet: Add @private to onActionChange method - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/191495
Change subject: ActionSet: Add @private to onActionChange method
..
ActionSet: Add @private to onActionChange method
Change-Id: I2c58abf38f4bb2b44615142a8322b3fa6dc6e2e8
---
M src/ActionSet.js
1 file changed, 1 insertion(+), 0 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/95/191495/1
diff --git a/src/ActionSet.js b/src/ActionSet.js
index 2093c12..4dbc4c2 100644
--- a/src/ActionSet.js
+++ b/src/ActionSet.js
@@ -138,6 +138,7 @@
/**
* Handle action change events.
*
+ * @private
* @fires change
*/
OO.ui.ActionSet.prototype.onActionChange = function () {
--
To view, visit https://gerrit.wikimedia.org/r/191495
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I2c58abf38f4bb2b44615142a8322b3fa6dc6e2e8
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] IconElement: Add description - change (oojs/ui)
Kmenger has uploaded a new change for review. https://gerrit.wikimedia.org/r/191205 Change subject: IconElement: Add description .. IconElement: Add description Change-Id: I9b1c86743567e72eed607186816e025de30538ae --- M src/elements/IconElement.js 1 file changed, 6 insertions(+), 5 deletions(-) git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/05/191205/1 diff --git a/src/elements/IconElement.js b/src/elements/IconElement.js index beed804..f90d2eb 100644 --- a/src/elements/IconElement.js +++ b/src/elements/IconElement.js @@ -1,10 +1,11 @@ /** - * Element containing an icon. + * IconElement is often mixed into other classes to generate an icon. + * Icons are graphics, about the size of normal text. They are used to aid the user + * in locating a control or to convey information in a space-efficient way. See the + * [OOjs UI documentation on MediaWiki] [1] for a list of icons + * included in the library. * - * Icons are graphics, about the size of normal text. They can be used to aid the user in locating - * a control or convey information in a more space efficient way. Icons should rarely be used - * without labels; such as in a toolbar where space is at a premium or within a context where the - * meaning is very clear to the user. + * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Icons * * @abstract * @class -- To view, visit https://gerrit.wikimedia.org/r/191205 To unsubscribe, visit https://gerrit.wikimedia.org/r/settings Gerrit-MessageType: newchange Gerrit-Change-Id: I9b1c86743567e72eed607186816e025de30538ae Gerrit-PatchSet: 1 Gerrit-Project: oojs/ui Gerrit-Branch: master Gerrit-Owner: Kmenger kmen...@wikimedia.org ___ MediaWiki-commits mailing list MediaWiki-commits@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] IndicatorElement: Add description - change (oojs/ui)
Kmenger has uploaded a new change for review. https://gerrit.wikimedia.org/r/191208 Change subject: IndicatorElement: Add description .. IndicatorElement: Add description Change-Id: Iac55ac0229e99ec4fa06a8f5f8470c6ca04d047a --- M src/elements/IndicatorElement.js 1 file changed, 11 insertions(+), 5 deletions(-) git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/08/191208/1 diff --git a/src/elements/IndicatorElement.js b/src/elements/IndicatorElement.js index f299a98..5e1bf99 100644 --- a/src/elements/IndicatorElement.js +++ b/src/elements/IndicatorElement.js @@ -1,10 +1,16 @@ /** - * Element containing an indicator. + * IndicatorElement is often mixed into other classes to generate an indicator. + * Indicators are small graphics that are generally used in two ways: * - * Indicators are graphics, smaller than normal text. They can be used to describe unique status or - * behavior. Indicators should only be used in exceptional cases; such as a button that opens a menu - * instead of performing an action directly, or an item in a list which has errors that need to be - * resolved. + * - To draw attention to the status of an item. For example, an indicator might be + * used to show that an item in a list has errors that need to be resolved. + * - To clarify the function of a control that acts in an exceptional way (a button + * that opens a menu instead of performing an action directly, for example). + * + * For a list of indicators included in the library, please see the + * [OOjs UI documentation on MediaWiki] [1]. + * + * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Indicators * * @abstract * @class -- To view, visit https://gerrit.wikimedia.org/r/191208 To unsubscribe, visit https://gerrit.wikimedia.org/r/settings Gerrit-MessageType: newchange Gerrit-Change-Id: Iac55ac0229e99ec4fa06a8f5f8470c6ca04d047a Gerrit-PatchSet: 1 Gerrit-Project: oojs/ui Gerrit-Branch: master Gerrit-Owner: Kmenger kmen...@wikimedia.org ___ MediaWiki-commits mailing list MediaWiki-commits@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] InputWidget: Add description - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/191210
Change subject: InputWidget: Add description
..
InputWidget: Add description
Change-Id: I81a31f28c1d39d1a644d8041dd7ab19be0e6
---
M src/widgets/InputWidget.js
1 file changed, 6 insertions(+), 1 deletion(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/10/191210/1
diff --git a/src/widgets/InputWidget.js b/src/widgets/InputWidget.js
index 0e2470e..acf9ed2 100644
--- a/src/widgets/InputWidget.js
+++ b/src/widgets/InputWidget.js
@@ -1,5 +1,10 @@
/**
- * Base class for input widgets.
+ * InputWidget is the base class for all input widgets, which
+ * include {@link OO.ui.TextInputWidget text inputs}, {@link
OO.ui.CheckboxInputWidget checkbox inputs},
+ * {@link OO.ui.RadioInputWidget radio inputs}, and {@link
OO.ui.ButtonInputWidget button inputs}.
+ * See the [OOjs UI documentation on MediaWiki] [1] for more information and
examples.
+ *
+ * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
*
* @abstract
* @class
--
To view, visit https://gerrit.wikimedia.org/r/191210
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I81a31f28c1d39d1a644d8041dd7ab19be0e6
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] SelectWidget: Add description - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/191216
Change subject: SelectWidget: Add description
..
SelectWidget: Add description
Change-Id: Ic0274c6e5485960891cc2209713b6ef032f02707
---
M src/widgets/SelectWidget.js
1 file changed, 8 insertions(+), 4 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/16/191216/1
diff --git a/src/widgets/SelectWidget.js b/src/widgets/SelectWidget.js
index 7cd40d3..fbf6d9c 100644
--- a/src/widgets/SelectWidget.js
+++ b/src/widgets/SelectWidget.js
@@ -1,10 +1,14 @@
/**
- * Generic selection of options.
+ * A SelectWidget is of a generic selection of options. The OOjs UI library
contains several types of
+ * select widgets, including {@link OO.ui.ButtonSelectWidget button selects},
+ * {@link OO.ui.RadioSelectWidget radio selects}, and {@link
OO.ui.MenuSelectWidget
+ * menu selects}.
*
- * Items can contain any rendering. Any widget that provides options, from
which the user must
- * choose one, should be built on this class.
+ * This class should be used together with OO.ui.OptionWidget.
*
- * Use together with OO.ui.OptionWidget.
+ * For more information, please see the [OOjs UI documentation on
MediaWiki][1].
+ *
+ * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
*
* @class
* @extends OO.ui.Widget
--
To view, visit https://gerrit.wikimedia.org/r/191216
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: Ic0274c6e5485960891cc2209713b6ef032f02707
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
[MediaWiki-commits] [Gerrit] IconWidget: Add description and example - change (oojs/ui)
Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/191207
Change subject: IconWidget: Add description and example
..
IconWidget: Add description and example
Change-Id: I0b3e58b381c90e98b76c7f0b3a36593db31bf54a
---
M src/widgets/IconWidget.js
1 file changed, 16 insertions(+), 2 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/07/191207/1
diff --git a/src/widgets/IconWidget.js b/src/widgets/IconWidget.js
index b444d43..359edc7 100644
--- a/src/widgets/IconWidget.js
+++ b/src/widgets/IconWidget.js
@@ -1,7 +1,21 @@
/**
- * Icon widget.
+ * IconWidget is a generic widget for {@link OO.ui.IconElement icons}. In
general, IconWidgets should be used with OO.ui.LabelWidget,
+ * which creates a label that identifies the icon’s function. See the [OOjs UI
documentation on MediaWiki] [1]
+ * for a list of icons included in the library.
*
- * See OO.ui.IconElement for more information.
+ * @example
+ * // An icon widget with a label
+ * var myIcon = new OO.ui.IconWidget({
+ * icon: 'help',
+ * iconTitle: 'Help'
+ * });
+ * // Create a label.
+ * var iconLabel = new OO.ui.LabelWidget({
+ * label: 'Help'
+ * });
+ * $('body').append(myIcon.$element, iconLabel.$element);
+ *
+ * [1]:
https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Icons
*
* @class
* @extends OO.ui.Widget
--
To view, visit https://gerrit.wikimedia.org/r/191207
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I0b3e58b381c90e98b76c7f0b3a36593db31bf54a
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger kmen...@wikimedia.org
___
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
