3 * https://www.mediawiki.org/wiki/OOUI
5 * Copyright 2011–2018 OOUI Team and other contributors.
6 * Released under the MIT license
7 * http://oojs.mit-license.org
9 * Date: 2018-12-05T00:15:55Z
16 * Toolbars are complex interface components that permit users to easily access a variety
17 * of {@link OO.ui.Tool tools} (e.g., formatting commands) and actions, which are additional commands that are
18 * part of the toolbar, but not configured as tools.
20 * Individual tools are customized and then registered with a {@link OO.ui.ToolFactory tool factory}, which creates
21 * the tools on demand. Each tool has a symbolic name (used when registering the tool), a title (e.g., ‘Insert
22 * image’), and an icon.
24 * Individual tools are organized in {@link OO.ui.ToolGroup toolgroups}, which can be {@link OO.ui.MenuToolGroup menus}
25 * of tools, {@link OO.ui.ListToolGroup lists} of tools, or a single {@link OO.ui.BarToolGroup bar} of tools.
26 * The arrangement and order of the toolgroups is customized when the toolbar is set up. Tools can be presented in
27 * any order, but each can only appear once in the toolbar.
29 * The toolbar can be synchronized with the state of the external "application", like a text
30 * editor's editing area, marking tools as active/inactive (e.g. a 'bold' tool would be shown as
31 * active when the text cursor was inside bolded text) or enabled/disabled (e.g. a table caption
32 * tool would be disabled while the user is not editing a table). A state change is signalled by
33 * emitting the {@link #event-updateState 'updateState' event}, which calls Tools'
34 * {@link OO.ui.Tool#onUpdateState onUpdateState method}.
36 * The following is an example of a basic toolbar.
39 * // Example of a toolbar
40 * // Create the toolbar
41 * var toolFactory = new OO.ui.ToolFactory();
42 * var toolGroupFactory = new OO.ui.ToolGroupFactory();
43 * var toolbar = new OO.ui.Toolbar( toolFactory, toolGroupFactory );
45 * // We will be placing status text in this element when tools are used
46 * var $area = $( '<p>' ).text( 'Toolbar example' );
48 * // Define the tools that we're going to place in our toolbar
50 * // Create a class inheriting from OO.ui.Tool
51 * function SearchTool() {
52 * SearchTool.parent.apply( this, arguments );
54 * OO.inheritClass( SearchTool, OO.ui.Tool );
55 * // Each tool must have a 'name' (used as an internal identifier, see later) and at least one
56 * // of 'icon' and 'title' (displayed icon and text).
57 * SearchTool.static.name = 'search';
58 * SearchTool.static.icon = 'search';
59 * SearchTool.static.title = 'Search...';
60 * // Defines the action that will happen when this tool is selected (clicked).
61 * SearchTool.prototype.onSelect = function () {
62 * $area.text( 'Search tool clicked!' );
63 * // Never display this tool as "active" (selected).
64 * this.setActive( false );
66 * SearchTool.prototype.onUpdateState = function () {};
67 * // Make this tool available in our toolFactory and thus our toolbar
68 * toolFactory.register( SearchTool );
70 * // Register two more tools, nothing interesting here
71 * function SettingsTool() {
72 * SettingsTool.parent.apply( this, arguments );
74 * OO.inheritClass( SettingsTool, OO.ui.Tool );
75 * SettingsTool.static.name = 'settings';
76 * SettingsTool.static.icon = 'settings';
77 * SettingsTool.static.title = 'Change settings';
78 * SettingsTool.prototype.onSelect = function () {
79 * $area.text( 'Settings tool clicked!' );
80 * this.setActive( false );
82 * SettingsTool.prototype.onUpdateState = function () {};
83 * toolFactory.register( SettingsTool );
85 * // Register two more tools, nothing interesting here
86 * function StuffTool() {
87 * StuffTool.parent.apply( this, arguments );
89 * OO.inheritClass( StuffTool, OO.ui.Tool );
90 * StuffTool.static.name = 'stuff';
91 * StuffTool.static.icon = 'ellipsis';
92 * StuffTool.static.title = 'More stuff';
93 * StuffTool.prototype.onSelect = function () {
94 * $area.text( 'More stuff tool clicked!' );
95 * this.setActive( false );
97 * StuffTool.prototype.onUpdateState = function () {};
98 * toolFactory.register( StuffTool );
100 * // This is a PopupTool. Rather than having a custom 'onSelect' action, it will display a
101 * // little popup window (a PopupWidget).
102 * function HelpTool( toolGroup, config ) {
103 * OO.ui.PopupTool.call( this, toolGroup, $.extend( { popup: {
108 * this.popup.$body.append( '<p>I am helpful!</p>' );
110 * OO.inheritClass( HelpTool, OO.ui.PopupTool );
111 * HelpTool.static.name = 'help';
112 * HelpTool.static.icon = 'help';
113 * HelpTool.static.title = 'Help';
114 * toolFactory.register( HelpTool );
116 * // Finally define which tools and in what order appear in the toolbar. Each tool may only be
117 * // used once (but not all defined tools must be used).
120 * // 'bar' tool groups display tools' icons only, side-by-side.
122 * include: [ 'search', 'help' ]
125 * // 'list' tool groups display both the titles and icons, in a dropdown list.
129 * include: [ 'settings', 'stuff' ]
131 * // Note how the tools themselves are toolgroup-agnostic - the same tool can be displayed
132 * // either in a 'list' or a 'bar'. There is a 'menu' tool group too, not showcased here,
133 * // since it's more complicated to use. (See the next example snippet on this page.)
136 * // Create some UI around the toolbar and place it in the document
137 * var frame = new OO.ui.PanelLayout( {
141 * var contentFrame = new OO.ui.PanelLayout( {
145 * frame.$element.append(
147 * contentFrame.$element.append( $area )
149 * $( 'body' ).append( frame.$element );
151 * // Here is where the toolbar is actually built. This must be done after inserting it into the
153 * toolbar.initialize();
154 * toolbar.emit( 'updateState' );
156 * The following example extends the previous one to illustrate 'menu' toolgroups and the usage of
157 * {@link #event-updateState 'updateState' event}.
160 * // Create the toolbar
161 * var toolFactory = new OO.ui.ToolFactory();
162 * var toolGroupFactory = new OO.ui.ToolGroupFactory();
163 * var toolbar = new OO.ui.Toolbar( toolFactory, toolGroupFactory );
165 * // We will be placing status text in this element when tools are used
166 * var $area = $( '<p>' ).text( 'Toolbar example' );
168 * // Define the tools that we're going to place in our toolbar
170 * // Create a class inheriting from OO.ui.Tool
171 * function SearchTool() {
172 * SearchTool.parent.apply( this, arguments );
174 * OO.inheritClass( SearchTool, OO.ui.Tool );
175 * // Each tool must have a 'name' (used as an internal identifier, see later) and at least one
176 * // of 'icon' and 'title' (displayed icon and text).
177 * SearchTool.static.name = 'search';
178 * SearchTool.static.icon = 'search';
179 * SearchTool.static.title = 'Search...';
180 * // Defines the action that will happen when this tool is selected (clicked).
181 * SearchTool.prototype.onSelect = function () {
182 * $area.text( 'Search tool clicked!' );
183 * // Never display this tool as "active" (selected).
184 * this.setActive( false );
186 * SearchTool.prototype.onUpdateState = function () {};
187 * // Make this tool available in our toolFactory and thus our toolbar
188 * toolFactory.register( SearchTool );
190 * // Register two more tools, nothing interesting here
191 * function SettingsTool() {
192 * SettingsTool.parent.apply( this, arguments );
193 * this.reallyActive = false;
195 * OO.inheritClass( SettingsTool, OO.ui.Tool );
196 * SettingsTool.static.name = 'settings';
197 * SettingsTool.static.icon = 'settings';
198 * SettingsTool.static.title = 'Change settings';
199 * SettingsTool.prototype.onSelect = function () {
200 * $area.text( 'Settings tool clicked!' );
201 * // Toggle the active state on each click
202 * this.reallyActive = !this.reallyActive;
203 * this.setActive( this.reallyActive );
204 * // To update the menu label
205 * this.toolbar.emit( 'updateState' );
207 * SettingsTool.prototype.onUpdateState = function () {};
208 * toolFactory.register( SettingsTool );
210 * // Register two more tools, nothing interesting here
211 * function StuffTool() {
212 * StuffTool.parent.apply( this, arguments );
213 * this.reallyActive = false;
215 * OO.inheritClass( StuffTool, OO.ui.Tool );
216 * StuffTool.static.name = 'stuff';
217 * StuffTool.static.icon = 'ellipsis';
218 * StuffTool.static.title = 'More stuff';
219 * StuffTool.prototype.onSelect = function () {
220 * $area.text( 'More stuff tool clicked!' );
221 * // Toggle the active state on each click
222 * this.reallyActive = !this.reallyActive;
223 * this.setActive( this.reallyActive );
224 * // To update the menu label
225 * this.toolbar.emit( 'updateState' );
227 * StuffTool.prototype.onUpdateState = function () {};
228 * toolFactory.register( StuffTool );
230 * // This is a PopupTool. Rather than having a custom 'onSelect' action, it will display a
231 * // little popup window (a PopupWidget). 'onUpdateState' is also already implemented.
232 * function HelpTool( toolGroup, config ) {
233 * OO.ui.PopupTool.call( this, toolGroup, $.extend( { popup: {
238 * this.popup.$body.append( '<p>I am helpful!</p>' );
240 * OO.inheritClass( HelpTool, OO.ui.PopupTool );
241 * HelpTool.static.name = 'help';
242 * HelpTool.static.icon = 'help';
243 * HelpTool.static.title = 'Help';
244 * toolFactory.register( HelpTool );
246 * // Finally define which tools and in what order appear in the toolbar. Each tool may only be
247 * // used once (but not all defined tools must be used).
250 * // 'bar' tool groups display tools' icons only, side-by-side.
252 * include: [ 'search', 'help' ]
255 * // 'menu' tool groups display both the titles and icons, in a dropdown menu.
256 * // Menu label indicates which items are selected.
259 * include: [ 'settings', 'stuff' ]
263 * // Create some UI around the toolbar and place it in the document
264 * var frame = new OO.ui.PanelLayout( {
268 * var contentFrame = new OO.ui.PanelLayout( {
272 * frame.$element.append(
274 * contentFrame.$element.append( $area )
276 * $( 'body' ).append( frame.$element );
278 * // Here is where the toolbar is actually built. This must be done after inserting it into the
280 * toolbar.initialize();
281 * toolbar.emit( 'updateState' );
284 * @extends OO.ui.Element
285 * @mixins OO.EventEmitter
286 * @mixins OO.ui.mixin.GroupElement
289 * @param {OO.ui.ToolFactory} toolFactory Factory for creating tools
290 * @param {OO.ui.ToolGroupFactory} toolGroupFactory Factory for creating toolgroups
291 * @param {Object} [config] Configuration options
292 * @cfg {boolean} [actions] Add an actions section to the toolbar. Actions are commands that are included
293 * in the toolbar, but are not configured as tools. By default, actions are displayed on the right side of
295 * @cfg {string} [position='top'] Whether the toolbar is positioned above ('top') or below ('bottom') content.
296 * @cfg {jQuery} [$overlay] An overlay for the popup.
297 * See <https://www.mediawiki.org/wiki/OOUI/Concepts#Overlays>.
299 OO
.ui
.Toolbar
= function OoUiToolbar( toolFactory
, toolGroupFactory
, config
) {
300 // Allow passing positional parameters inside the config object
301 if ( OO
.isPlainObject( toolFactory
) && config
=== undefined ) {
302 config
= toolFactory
;
303 toolFactory
= config
.toolFactory
;
304 toolGroupFactory
= config
.toolGroupFactory
;
307 // Configuration initialization
308 config
= config
|| {};
310 // Parent constructor
311 OO
.ui
.Toolbar
.parent
.call( this, config
);
313 // Mixin constructors
314 OO
.EventEmitter
.call( this );
315 OO
.ui
.mixin
.GroupElement
.call( this, config
);
318 this.toolFactory
= toolFactory
;
319 this.toolGroupFactory
= toolGroupFactory
;
320 this.groupsByName
= {};
321 this.activeToolGroups
= 0;
323 this.position
= config
.position
|| 'top';
324 this.$bar
= $( '<div>' );
325 this.$actions
= $( '<div>' );
326 this.$popups
= $( '<div>' );
327 this.initialized
= false;
328 this.narrowThreshold
= null;
329 this.onWindowResizeHandler
= this.onWindowResize
.bind( this );
330 this.$overlay
= ( config
.$overlay
=== true ? OO
.ui
.getDefaultOverlay() : config
.$overlay
) || this.$element
;
334 .add( this.$bar
).add( this.$group
).add( this.$actions
)
335 .on( 'mousedown keydown', this.onPointerDown
.bind( this ) );
338 this.$group
.addClass( 'oo-ui-toolbar-tools' );
339 if ( config
.actions
) {
340 this.$bar
.append( this.$actions
.addClass( 'oo-ui-toolbar-actions' ) );
342 this.$popups
.addClass( 'oo-ui-toolbar-popups' );
344 .addClass( 'oo-ui-toolbar-bar' )
345 .append( this.$group
, '<div style="clear:both"></div>' );
346 // Possible classes: oo-ui-toolbar-position-top, oo-ui-toolbar-position-bottom
347 this.$element
.addClass( 'oo-ui-toolbar oo-ui-toolbar-position-' + this.position
).append( this.$bar
);
348 this.$overlay
.append( this.$popups
);
353 OO
.inheritClass( OO
.ui
.Toolbar
, OO
.ui
.Element
);
354 OO
.mixinClass( OO
.ui
.Toolbar
, OO
.EventEmitter
);
355 OO
.mixinClass( OO
.ui
.Toolbar
, OO
.ui
.mixin
.GroupElement
);
362 * An 'updateState' event must be emitted on the Toolbar (by calling `toolbar.emit( 'updateState' )`)
363 * every time the state of the application using the toolbar changes, and an update to the state of
366 * @param {...Mixed} data Application-defined parameters
372 * An 'active' event is emitted when the number of active toolgroups increases from 0, or
375 * @param {boolean} There are active toolgroups in this toolbar
381 * Get the tool factory.
383 * @return {OO.ui.ToolFactory} Tool factory
385 OO
.ui
.Toolbar
.prototype.getToolFactory = function () {
386 return this.toolFactory
;
390 * Get the toolgroup factory.
392 * @return {OO.Factory} Toolgroup factory
394 OO
.ui
.Toolbar
.prototype.getToolGroupFactory = function () {
395 return this.toolGroupFactory
;
399 * Handles mouse down events.
402 * @param {jQuery.Event} e Mouse down event
403 * @return {undefined/boolean} False to prevent default if event is handled
405 OO
.ui
.Toolbar
.prototype.onPointerDown = function ( e
) {
406 var $closestWidgetToEvent
= $( e
.target
).closest( '.oo-ui-widget' ),
407 $closestWidgetToToolbar
= this.$element
.closest( '.oo-ui-widget' );
408 if ( !$closestWidgetToEvent
.length
|| $closestWidgetToEvent
[ 0 ] === $closestWidgetToToolbar
[ 0 ] ) {
414 * Handle window resize event.
417 * @param {jQuery.Event} e Window resize event
419 OO
.ui
.Toolbar
.prototype.onWindowResize = function () {
420 this.$element
.add( this.$popups
).toggleClass(
421 'oo-ui-toolbar-narrow',
422 this.$bar
[ 0 ].clientWidth
<= this.getNarrowThreshold()
427 * Get the (lazily-computed) width threshold for applying the oo-ui-toolbar-narrow
431 * @return {number} Width threshold in pixels
433 OO
.ui
.Toolbar
.prototype.getNarrowThreshold = function () {
434 if ( this.narrowThreshold
=== null ) {
435 this.narrowThreshold
= this.$group
[ 0 ].offsetWidth
+ this.$actions
[ 0 ].offsetWidth
;
437 return this.narrowThreshold
;
441 * Sets up handles and preloads required information for the toolbar to work.
442 * This must be called after it is attached to a visible document and before doing anything else.
444 OO
.ui
.Toolbar
.prototype.initialize = function () {
445 if ( !this.initialized
) {
446 this.initialized
= true;
447 $( this.getElementWindow() ).on( 'resize', this.onWindowResizeHandler
);
448 this.onWindowResize();
453 * Set up the toolbar.
455 * The toolbar is set up with a list of toolgroup configurations that specify the type of
456 * toolgroup ({@link OO.ui.BarToolGroup bar}, {@link OO.ui.MenuToolGroup menu}, or {@link OO.ui.ListToolGroup list})
457 * to add and which tools to include, exclude, promote, or demote within that toolgroup. Please
458 * see {@link OO.ui.ToolGroup toolgroups} for more information about including tools in toolgroups.
460 * @param {Object.<string,Array>} groups List of toolgroup configurations
461 * @param {string} [groups.name] Symbolic name for this toolgroup
462 * @param {string} [groups.type] Toolgroup type, should exist in the toolgroup factory
463 * @param {Array|string} [groups.include] Tools to include in the toolgroup
464 * @param {Array|string} [groups.exclude] Tools to exclude from the toolgroup
465 * @param {Array|string} [groups.promote] Tools to promote to the beginning of the toolgroup
466 * @param {Array|string} [groups.demote] Tools to demote to the end of the toolgroup
468 OO
.ui
.Toolbar
.prototype.setup = function ( groups
) {
469 var i
, len
, type
, toolGroup
, groupConfig
,
473 // Cleanup previous groups
476 // Build out new groups
477 for ( i
= 0, len
= groups
.length
; i
< len
; i
++ ) {
478 groupConfig
= groups
[ i
];
479 if ( groupConfig
.include
=== '*' ) {
480 // Apply defaults to catch-all groups
481 if ( groupConfig
.type
=== undefined ) {
482 groupConfig
.type
= 'list';
484 if ( groupConfig
.label
=== undefined ) {
485 groupConfig
.label
= OO
.ui
.msg( 'ooui-toolbar-more' );
488 // Check type has been registered
489 type
= this.getToolGroupFactory().lookup( groupConfig
.type
) ? groupConfig
.type
: defaultType
;
490 toolGroup
= this.getToolGroupFactory().create( type
, this, groupConfig
);
491 items
.push( toolGroup
);
492 if ( groupConfig
.name
) {
493 this.groupsByName
[ groupConfig
.name
] = toolGroup
;
495 // Groups without name are deprecated
496 OO
.ui
.warnDeprecation( 'Toolgroups must have a \'name\' property' );
498 toolGroup
.connect( this, { active
: 'onToolGroupActive' } );
500 this.addItems( items
);
504 * Handle active events from tool groups
506 * @param {boolean} active Tool group has become active, inactive if false
509 OO
.ui
.Toolbar
.prototype.onToolGroupActive = function ( active
) {
511 this.activeToolGroups
++;
512 if ( this.activeToolGroups
=== 1 ) {
513 this.emit( 'active', true );
516 this.activeToolGroups
--;
517 if ( this.activeToolGroups
=== 0 ) {
518 this.emit( 'active', false );
524 * Get a toolgroup by name
526 * @param {string} name Group name
527 * @return {OO.ui.ToolGroup|null} Tool group, or null if none found by that name
529 OO
.ui
.Toolbar
.prototype.getToolGroupByName = function ( name
) {
530 return this.groupsByName
[ name
] || null;
534 * Remove all tools and toolgroups from the toolbar.
536 OO
.ui
.Toolbar
.prototype.reset = function () {
539 this.groupsByName
= {};
541 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
542 this.items
[ i
].destroy();
548 * Destroy the toolbar.
550 * Destroying the toolbar removes all event handlers and DOM elements that constitute the toolbar. Call
551 * this method whenever you are done using a toolbar.
553 OO
.ui
.Toolbar
.prototype.destroy = function () {
554 $( this.getElementWindow() ).off( 'resize', this.onWindowResizeHandler
);
556 this.$element
.remove();
560 * Check if the tool is available.
562 * Available tools are ones that have not yet been added to the toolbar.
564 * @param {string} name Symbolic name of tool
565 * @return {boolean} Tool is available
567 OO
.ui
.Toolbar
.prototype.isToolAvailable = function ( name
) {
568 return !this.tools
[ name
];
572 * Prevent tool from being used again.
574 * @param {OO.ui.Tool} tool Tool to reserve
576 OO
.ui
.Toolbar
.prototype.reserveTool = function ( tool
) {
577 this.tools
[ tool
.getName() ] = tool
;
581 * Allow tool to be used again.
583 * @param {OO.ui.Tool} tool Tool to release
585 OO
.ui
.Toolbar
.prototype.releaseTool = function ( tool
) {
586 delete this.tools
[ tool
.getName() ];
590 * Get accelerator label for tool.
592 * The OOUI library does not contain an accelerator system, but this is the hook for one. To
593 * use an accelerator system, subclass the toolbar and override this method, which is meant to return a label
594 * that describes the accelerator keys for the tool passed (by symbolic name) to the method.
596 * @param {string} name Symbolic name of tool
597 * @return {string|undefined} Tool accelerator label if available
599 OO
.ui
.Toolbar
.prototype.getToolAccelerator = function () {
604 * Tools, together with {@link OO.ui.ToolGroup toolgroups}, constitute {@link OO.ui.Toolbar toolbars}.
605 * Each tool is configured with a static name, title, and icon and is customized with the command to carry
606 * out when the tool is selected. Tools must also be registered with a {@link OO.ui.ToolFactory tool factory},
607 * which creates the tools on demand.
609 * Every Tool subclass must implement two methods:
611 * - {@link #onUpdateState}
612 * - {@link #onSelect}
614 * Tools are added to toolgroups ({@link OO.ui.ListToolGroup ListToolGroup},
615 * {@link OO.ui.BarToolGroup BarToolGroup}, or {@link OO.ui.MenuToolGroup MenuToolGroup}), which determine how
616 * the tool is displayed in the toolbar. See {@link OO.ui.Toolbar toolbars} for an example.
618 * For more information, please see the [OOUI documentation on MediaWiki][1].
619 * [1]: https://www.mediawiki.org/wiki/OOUI/Toolbars
623 * @extends OO.ui.Widget
624 * @mixins OO.ui.mixin.IconElement
625 * @mixins OO.ui.mixin.FlaggedElement
626 * @mixins OO.ui.mixin.TabIndexedElement
629 * @param {OO.ui.ToolGroup} toolGroup
630 * @param {Object} [config] Configuration options
631 * @cfg {string|Function} [title] Title text or a function that returns text. If this config is omitted, the value of
632 * the {@link #static-title static title} property is used.
634 * The title is used in different ways depending on the type of toolgroup that contains the tool. The
635 * 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
636 * part of a {@link OO.ui.ListToolGroup list} or {@link OO.ui.MenuToolGroup menu} toolgroup.
638 * For bar toolgroups, a description of the accelerator key is appended to the title if an accelerator key
639 * is associated with an action by the same name as the tool and accelerator functionality has been added to the application.
640 * To add accelerator key functionality, you must subclass OO.ui.Toolbar and override the {@link OO.ui.Toolbar#getToolAccelerator getToolAccelerator} method.
642 OO
.ui
.Tool
= function OoUiTool( toolGroup
, config
) {
643 // Allow passing positional parameters inside the config object
644 if ( OO
.isPlainObject( toolGroup
) && config
=== undefined ) {
646 toolGroup
= config
.toolGroup
;
649 // Configuration initialization
650 config
= config
|| {};
652 // Parent constructor
653 OO
.ui
.Tool
.parent
.call( this, config
);
656 this.toolGroup
= toolGroup
;
657 this.toolbar
= this.toolGroup
.getToolbar();
659 this.$title
= $( '<span>' );
660 this.$accel
= $( '<span>' );
661 this.$link
= $( '<a>' );
663 this.checkIcon
= new OO
.ui
.IconWidget( {
665 classes
: [ 'oo-ui-tool-checkIcon' ]
668 // Mixin constructors
669 OO
.ui
.mixin
.IconElement
.call( this, config
);
670 OO
.ui
.mixin
.FlaggedElement
.call( this, config
);
671 OO
.ui
.mixin
.TabIndexedElement
.call( this, $.extend( {}, config
, { $tabIndexed
: this.$link
} ) );
674 this.toolbar
.connect( this, { updateState
: 'onUpdateState' } );
677 this.$title
.addClass( 'oo-ui-tool-title' );
679 .addClass( 'oo-ui-tool-accel' )
681 // This may need to be changed if the key names are ever localized,
682 // but for now they are essentially written in English
687 .addClass( 'oo-ui-tool-link' )
688 .append( this.checkIcon
.$element
, this.$icon
, this.$title
, this.$accel
)
689 .attr( 'role', 'button' );
691 .data( 'oo-ui-tool', this )
692 .addClass( 'oo-ui-tool' )
693 .addClass( 'oo-ui-tool-name-' + this.constructor.static.name
.replace( /^([^/]+)\/([^/]+).*$/, '$1-$2' ) )
694 .toggleClass( 'oo-ui-tool-with-label', this.constructor.static.displayBothIconAndLabel
)
695 .append( this.$link
);
696 this.setTitle( config
.title
|| this.constructor.static.title
);
701 OO
.inheritClass( OO
.ui
.Tool
, OO
.ui
.Widget
);
702 OO
.mixinClass( OO
.ui
.Tool
, OO
.ui
.mixin
.IconElement
);
703 OO
.mixinClass( OO
.ui
.Tool
, OO
.ui
.mixin
.FlaggedElement
);
704 OO
.mixinClass( OO
.ui
.Tool
, OO
.ui
.mixin
.TabIndexedElement
);
706 /* Static Properties */
712 OO
.ui
.Tool
.static.tagName
= 'span';
715 * Symbolic name of tool.
717 * The symbolic name is used internally to register the tool with a {@link OO.ui.ToolFactory ToolFactory}. It can
718 * also be used when adding tools to toolgroups.
725 OO
.ui
.Tool
.static.name
= '';
728 * Symbolic name of the group.
730 * The group name is used to associate tools with each other so that they can be selected later by
731 * a {@link OO.ui.ToolGroup toolgroup}.
738 OO
.ui
.Tool
.static.group
= '';
741 * 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.
746 * @property {string|Function}
748 OO
.ui
.Tool
.static.title
= '';
751 * Display both icon and label when the tool is used in a {@link OO.ui.BarToolGroup bar} toolgroup.
752 * Normally only the icon is displayed, or only the label if no icon is given.
756 * @property {boolean}
758 OO
.ui
.Tool
.static.displayBothIconAndLabel
= false;
761 * Add tool to catch-all groups automatically.
763 * A catch-all group, which contains all tools that do not currently belong to a toolgroup,
764 * can be included in a toolgroup using the wildcard selector, an asterisk (*).
768 * @property {boolean}
770 OO
.ui
.Tool
.static.autoAddToCatchall
= true;
773 * Add tool to named groups automatically.
775 * By default, tools that are configured with a static ‘group’ property are added
776 * to that group and will be selected when the symbolic name of the group is specified (e.g., when
777 * toolgroups include tools by group name).
780 * @property {boolean}
783 OO
.ui
.Tool
.static.autoAddToGroup
= true;
786 * Check if this tool is compatible with given data.
788 * This is a stub that can be overridden to provide support for filtering tools based on an
789 * arbitrary piece of information (e.g., where the cursor is in a document). The implementation
790 * must also call this method so that the compatibility check can be performed.
794 * @param {Mixed} data Data to check
795 * @return {boolean} Tool can be used with data
797 OO
.ui
.Tool
.static.isCompatibleWith = function () {
804 * Handle the toolbar state being updated. This method is called when the
805 * {@link OO.ui.Toolbar#event-updateState 'updateState' event} is emitted on the
806 * {@link OO.ui.Toolbar Toolbar} that uses this tool, and should set the state of this tool
807 * depending on application state (usually by calling #setDisabled to enable or disable the tool,
808 * or #setActive to mark is as currently in-use or not).
810 * This is an abstract method that must be overridden in a concrete subclass.
816 OO
.ui
.Tool
.prototype.onUpdateState
= null;
819 * Handle the tool being selected. This method is called when the user triggers this tool,
820 * usually by clicking on its label/icon.
822 * This is an abstract method that must be overridden in a concrete subclass.
828 OO
.ui
.Tool
.prototype.onSelect
= null;
831 * Check if the tool is active.
833 * Tools become active when their #onSelect or #onUpdateState handlers change them to appear pressed
834 * with the #setActive method. Additional CSS is applied to the tool to reflect the active state.
836 * @return {boolean} Tool is active
838 OO
.ui
.Tool
.prototype.isActive = function () {
843 * Make the tool appear active or inactive.
845 * This method should be called within #onSelect or #onUpdateState event handlers to make the tool
846 * appear pressed or not.
848 * @param {boolean} state Make tool appear active
850 OO
.ui
.Tool
.prototype.setActive = function ( state
) {
851 this.active
= !!state
;
852 this.$element
.toggleClass( 'oo-ui-tool-active', this.active
);
853 this.updateThemeClasses();
857 * Set the tool #title.
859 * @param {string|Function} title Title text or a function that returns text
861 * @return {OO.ui.Tool} The tool, for chaining
863 OO
.ui
.Tool
.prototype.setTitle = function ( title
) {
864 this.title
= OO
.ui
.resolveMsg( title
);
870 * Get the tool #title.
872 * @return {string} Title text
874 OO
.ui
.Tool
.prototype.getTitle = function () {
879 * Get the tool's symbolic name.
881 * @return {string} Symbolic name of tool
883 OO
.ui
.Tool
.prototype.getName = function () {
884 return this.constructor.static.name
;
890 OO
.ui
.Tool
.prototype.updateTitle = function () {
891 var titleTooltips
= this.toolGroup
.constructor.static.titleTooltips
,
892 accelTooltips
= this.toolGroup
.constructor.static.accelTooltips
,
893 accel
= this.toolbar
.getToolAccelerator( this.constructor.static.name
),
896 this.$title
.text( this.title
);
897 this.$accel
.text( accel
);
899 if ( titleTooltips
&& typeof this.title
=== 'string' && this.title
.length
) {
900 tooltipParts
.push( this.title
);
902 if ( accelTooltips
&& typeof accel
=== 'string' && accel
.length
) {
903 tooltipParts
.push( accel
);
905 if ( tooltipParts
.length
) {
906 this.$link
.attr( 'title', tooltipParts
.join( ' ' ) );
908 this.$link
.removeAttr( 'title' );
915 * Destroying the tool removes all event handlers and the tool’s DOM elements.
916 * Call this method whenever you are done using a tool.
918 OO
.ui
.Tool
.prototype.destroy = function () {
919 this.toolbar
.disconnect( this );
920 this.$element
.remove();
924 * ToolGroups are collections of {@link OO.ui.Tool tools} that are used in a {@link OO.ui.Toolbar toolbar}.
925 * The type of toolgroup ({@link OO.ui.ListToolGroup list}, {@link OO.ui.BarToolGroup bar}, or {@link OO.ui.MenuToolGroup menu})
926 * to which a tool belongs determines how the tool is arranged and displayed in the toolbar. Toolgroups
927 * themselves are created on demand with a {@link OO.ui.ToolGroupFactory toolgroup factory}.
929 * Toolgroups can contain individual tools, groups of tools, or all available tools, as specified
930 * using the `include` config option. See OO.ui.ToolFactory#extract on documentation of the format.
931 * The options `exclude`, `promote`, and `demote` support the same formats.
933 * See {@link OO.ui.Toolbar toolbars} for a full example. For more information about toolbars in general,
934 * please see the [OOUI documentation on MediaWiki][1].
936 * [1]: https://www.mediawiki.org/wiki/OOUI/Toolbars
940 * @extends OO.ui.Widget
941 * @mixins OO.ui.mixin.GroupElement
944 * @param {OO.ui.Toolbar} toolbar
945 * @param {Object} [config] Configuration options
946 * @cfg {Array|string} [include] List of tools to include in the toolgroup, see above.
947 * @cfg {Array|string} [exclude] List of tools to exclude from the toolgroup, see above.
948 * @cfg {Array|string} [promote] List of tools to promote to the beginning of the toolgroup, see above.
949 * @cfg {Array|string} [demote] List of tools to demote to the end of the toolgroup, see above.
950 * This setting is particularly useful when tools have been added to the toolgroup
951 * en masse (e.g., via the catch-all selector).
953 OO
.ui
.ToolGroup
= function OoUiToolGroup( toolbar
, config
) {
954 // Allow passing positional parameters inside the config object
955 if ( OO
.isPlainObject( toolbar
) && config
=== undefined ) {
957 toolbar
= config
.toolbar
;
960 // Configuration initialization
961 config
= config
|| {};
963 // Parent constructor
964 OO
.ui
.ToolGroup
.parent
.call( this, config
);
966 // Mixin constructors
967 OO
.ui
.mixin
.GroupElement
.call( this, config
);
970 this.toolbar
= toolbar
;
973 this.autoDisabled
= false;
974 this.include
= config
.include
|| [];
975 this.exclude
= config
.exclude
|| [];
976 this.promote
= config
.promote
|| [];
977 this.demote
= config
.demote
|| [];
978 this.onDocumentMouseKeyUpHandler
= this.onDocumentMouseKeyUp
.bind( this );
982 mousedown
: this.onMouseKeyDown
.bind( this ),
983 mouseup
: this.onMouseKeyUp
.bind( this ),
984 keydown
: this.onMouseKeyDown
.bind( this ),
985 keyup
: this.onMouseKeyUp
.bind( this ),
986 focus
: this.onMouseOverFocus
.bind( this ),
987 blur
: this.onMouseOutBlur
.bind( this ),
988 mouseover
: this.onMouseOverFocus
.bind( this ),
989 mouseout
: this.onMouseOutBlur
.bind( this )
991 this.toolbar
.getToolFactory().connect( this, { register
: 'onToolFactoryRegister' } );
992 this.aggregate( { disable
: 'itemDisable' } );
993 this.connect( this, {
994 itemDisable
: 'updateDisabled',
999 this.$group
.addClass( 'oo-ui-toolGroup-tools' );
1001 .addClass( 'oo-ui-toolGroup' )
1002 .append( this.$group
);
1003 this.onDisable( this.isDisabled() );
1009 OO
.inheritClass( OO
.ui
.ToolGroup
, OO
.ui
.Widget
);
1010 OO
.mixinClass( OO
.ui
.ToolGroup
, OO
.ui
.mixin
.GroupElement
);
1021 * An 'active' event is emitted when any popup is shown/hidden.
1023 * @param {boolean} The popup is visible
1026 /* Static Properties */
1029 * Show labels in tooltips.
1033 * @property {boolean}
1035 OO
.ui
.ToolGroup
.static.titleTooltips
= false;
1038 * Show acceleration labels in tooltips.
1040 * Note: The OOUI library does not include an accelerator system, but does contain
1041 * a hook for one. To use an accelerator system, subclass the {@link OO.ui.Toolbar toolbar} and
1042 * override the {@link OO.ui.Toolbar#getToolAccelerator getToolAccelerator} method, which is
1043 * meant to return a label that describes the accelerator keys for a given tool (e.g., 'Ctrl + M').
1047 * @property {boolean}
1049 OO
.ui
.ToolGroup
.static.accelTooltips
= false;
1052 * Automatically disable the toolgroup when all tools are disabled
1056 * @property {boolean}
1058 OO
.ui
.ToolGroup
.static.autoDisable
= true;
1064 * @property {string}
1066 OO
.ui
.ToolGroup
.static.name
= null;
1073 OO
.ui
.ToolGroup
.prototype.isDisabled = function () {
1074 return this.autoDisabled
|| OO
.ui
.ToolGroup
.parent
.prototype.isDisabled
.apply( this, arguments
);
1080 OO
.ui
.ToolGroup
.prototype.updateDisabled = function () {
1081 var i
, item
, allDisabled
= true;
1083 if ( this.constructor.static.autoDisable
) {
1084 for ( i
= this.items
.length
- 1; i
>= 0; i
-- ) {
1085 item
= this.items
[ i
];
1086 if ( !item
.isDisabled() ) {
1087 allDisabled
= false;
1091 this.autoDisabled
= allDisabled
;
1093 OO
.ui
.ToolGroup
.parent
.prototype.updateDisabled
.apply( this, arguments
);
1097 * Handle disable events.
1100 * @param {boolean} isDisabled
1102 OO
.ui
.ToolGroup
.prototype.onDisable = function ( isDisabled
) {
1103 this.$group
.toggleClass( 'oo-ui-toolGroup-disabled-tools', isDisabled
);
1104 this.$group
.toggleClass( 'oo-ui-toolGroup-enabled-tools', !isDisabled
);
1108 * Handle mouse down and key down events.
1111 * @param {jQuery.Event} e Mouse down or key down event
1112 * @return {undefined/boolean} False to prevent default if event is handled
1114 OO
.ui
.ToolGroup
.prototype.onMouseKeyDown = function ( e
) {
1116 !this.isDisabled() &&
1117 ( e
.which
=== OO
.ui
.MouseButtons
.LEFT
|| e
.which
=== OO
.ui
.Keys
.SPACE
|| e
.which
=== OO
.ui
.Keys
.ENTER
)
1119 this.pressed
= this.findTargetTool( e
);
1120 if ( this.pressed
) {
1121 this.pressed
.setActive( true );
1122 this.getElementDocument().addEventListener( 'mouseup', this.onDocumentMouseKeyUpHandler
, true );
1123 this.getElementDocument().addEventListener( 'keyup', this.onDocumentMouseKeyUpHandler
, true );
1130 * Handle document mouse up and key up events.
1133 * @param {MouseEvent|KeyboardEvent} e Mouse up or key up event
1135 OO
.ui
.ToolGroup
.prototype.onDocumentMouseKeyUp = function ( e
) {
1136 this.getElementDocument().removeEventListener( 'mouseup', this.onDocumentMouseKeyUpHandler
, true );
1137 this.getElementDocument().removeEventListener( 'keyup', this.onDocumentMouseKeyUpHandler
, true );
1138 // onMouseKeyUp may be called a second time, depending on where the mouse is when the button is
1139 // released, but since `this.pressed` will no longer be true, the second call will be ignored.
1140 this.onMouseKeyUp( e
);
1143 // Deprecated alias since 0.28.3
1144 OO
.ui
.ToolGroup
.prototype.onCapturedMouseKeyUp = function () {
1145 OO
.ui
.warnDeprecation( 'onCapturedMouseKeyUp is deprecated, use onDocumentMouseKeyUp instead' );
1146 this.onDocumentMouseKeyUp
.apply( this, arguments
);
1150 * Handle mouse up and key up events.
1153 * @param {MouseEvent|KeyboardEvent} e Mouse up or key up event
1155 OO
.ui
.ToolGroup
.prototype.onMouseKeyUp = function ( e
) {
1156 var tool
= this.findTargetTool( e
);
1159 !this.isDisabled() && this.pressed
&& this.pressed
=== tool
&&
1160 ( e
.which
=== OO
.ui
.MouseButtons
.LEFT
|| e
.which
=== OO
.ui
.Keys
.SPACE
|| e
.which
=== OO
.ui
.Keys
.ENTER
)
1162 this.pressed
.onSelect();
1163 this.pressed
= null;
1165 e
.stopPropagation();
1168 this.pressed
= null;
1172 * Handle mouse over and focus events.
1175 * @param {jQuery.Event} e Mouse over or focus event
1177 OO
.ui
.ToolGroup
.prototype.onMouseOverFocus = function ( e
) {
1178 var tool
= this.findTargetTool( e
);
1180 if ( this.pressed
&& this.pressed
=== tool
) {
1181 this.pressed
.setActive( true );
1186 * Handle mouse out and blur events.
1189 * @param {jQuery.Event} e Mouse out or blur event
1191 OO
.ui
.ToolGroup
.prototype.onMouseOutBlur = function ( e
) {
1192 var tool
= this.findTargetTool( e
);
1194 if ( this.pressed
&& this.pressed
=== tool
) {
1195 this.pressed
.setActive( false );
1200 * Get the closest tool to a jQuery.Event.
1202 * Only tool links are considered, which prevents other elements in the tool such as popups from
1203 * triggering tool group interactions.
1206 * @param {jQuery.Event} e
1207 * @return {OO.ui.Tool|null} Tool, `null` if none was found
1209 OO
.ui
.ToolGroup
.prototype.findTargetTool = function ( e
) {
1211 $item
= $( e
.target
).closest( '.oo-ui-tool-link' );
1213 if ( $item
.length
) {
1214 tool
= $item
.parent().data( 'oo-ui-tool' );
1217 return tool
&& !tool
.isDisabled() ? tool
: null;
1221 * Handle tool registry register events.
1223 * If a tool is registered after the group is created, we must repopulate the list to account for:
1225 * - a tool being added that may be included
1226 * - a tool already included being overridden
1229 * @param {string} name Symbolic name of tool
1231 OO
.ui
.ToolGroup
.prototype.onToolFactoryRegister = function () {
1236 * Get the toolbar that contains the toolgroup.
1238 * @return {OO.ui.Toolbar} Toolbar that contains the toolgroup
1240 OO
.ui
.ToolGroup
.prototype.getToolbar = function () {
1241 return this.toolbar
;
1245 * Add and remove tools based on configuration.
1247 OO
.ui
.ToolGroup
.prototype.populate = function () {
1248 var i
, len
, name
, tool
,
1249 toolFactory
= this.toolbar
.getToolFactory(),
1253 list
= this.toolbar
.getToolFactory().getTools(
1254 this.include
, this.exclude
, this.promote
, this.demote
1257 // Build a list of needed tools
1258 for ( i
= 0, len
= list
.length
; i
< len
; i
++ ) {
1262 toolFactory
.lookup( name
) &&
1263 // Tool is available or is already in this group
1264 ( this.toolbar
.isToolAvailable( name
) || this.tools
[ name
] )
1266 // Hack to prevent infinite recursion via ToolGroupTool. We need to reserve the tool before
1267 // creating it, but we can't call reserveTool() yet because we haven't created the tool.
1268 this.toolbar
.tools
[ name
] = true;
1269 tool
= this.tools
[ name
];
1271 // Auto-initialize tools on first use
1272 this.tools
[ name
] = tool
= toolFactory
.create( name
, this );
1275 this.toolbar
.reserveTool( tool
);
1277 names
[ name
] = true;
1280 // Remove tools that are no longer needed
1281 for ( name
in this.tools
) {
1282 if ( !names
[ name
] ) {
1283 this.tools
[ name
].destroy();
1284 this.toolbar
.releaseTool( this.tools
[ name
] );
1285 remove
.push( this.tools
[ name
] );
1286 delete this.tools
[ name
];
1289 if ( remove
.length
) {
1290 this.removeItems( remove
);
1292 // Update emptiness state
1294 this.$element
.removeClass( 'oo-ui-toolGroup-empty' );
1296 this.$element
.addClass( 'oo-ui-toolGroup-empty' );
1298 // Re-add tools (moving existing ones to new locations)
1299 this.addItems( add
);
1300 // Disabled state may depend on items
1301 this.updateDisabled();
1305 * Destroy toolgroup.
1307 OO
.ui
.ToolGroup
.prototype.destroy = function () {
1311 this.toolbar
.getToolFactory().disconnect( this );
1312 for ( name
in this.tools
) {
1313 this.toolbar
.releaseTool( this.tools
[ name
] );
1314 this.tools
[ name
].disconnect( this ).destroy();
1315 delete this.tools
[ name
];
1317 this.$element
.remove();
1321 * A ToolFactory creates tools on demand. All tools ({@link OO.ui.Tool Tools}, {@link OO.ui.PopupTool PopupTools},
1322 * and {@link OO.ui.ToolGroupTool ToolGroupTools}) must be registered with a tool factory. Tools are
1323 * registered by their symbolic name. See {@link OO.ui.Toolbar toolbars} for an example.
1325 * For more information about toolbars in general, please see the [OOUI documentation on MediaWiki][1].
1327 * [1]: https://www.mediawiki.org/wiki/OOUI/Toolbars
1330 * @extends OO.Factory
1333 OO
.ui
.ToolFactory
= function OoUiToolFactory() {
1334 // Parent constructor
1335 OO
.ui
.ToolFactory
.parent
.call( this );
1340 OO
.inheritClass( OO
.ui
.ToolFactory
, OO
.Factory
);
1345 * Get tools from the factory
1347 * @param {Array|string} [include] Included tools, see #extract for format
1348 * @param {Array|string} [exclude] Excluded tools, see #extract for format
1349 * @param {Array|string} [promote] Promoted tools, see #extract for format
1350 * @param {Array|string} [demote] Demoted tools, see #extract for format
1351 * @return {string[]} List of tools
1353 OO
.ui
.ToolFactory
.prototype.getTools = function ( include
, exclude
, promote
, demote
) {
1354 var i
, len
, included
, promoted
, demoted
,
1358 // Collect included and not excluded tools
1359 included
= OO
.simpleArrayDifference( this.extract( include
), this.extract( exclude
) );
1362 promoted
= this.extract( promote
, used
);
1363 demoted
= this.extract( demote
, used
);
1366 for ( i
= 0, len
= included
.length
; i
< len
; i
++ ) {
1367 if ( !used
[ included
[ i
] ] ) {
1368 auto
.push( included
[ i
] );
1372 return promoted
.concat( auto
).concat( demoted
);
1376 * Get a flat list of names from a list of names or groups.
1378 * Normally, `collection` is an array of tool specifications. Tools can be specified in the
1381 * - To include an individual tool, use the symbolic name: `{ name: 'tool-name' }` or `'tool-name'`.
1382 * - To include all tools in a group, use the group name: `{ group: 'group-name' }`. (To assign the
1383 * tool to a group, use OO.ui.Tool.static.group.)
1385 * Alternatively, to include all tools that are not yet assigned to any other toolgroup, use the
1386 * catch-all selector `'*'`.
1388 * If `used` is passed, tool names that appear as properties in this object will be considered
1389 * already assigned, and will not be returned even if specified otherwise. The tool names extracted
1390 * by this function call will be added as new properties in the object.
1393 * @param {Array|string} collection List of tools, see above
1394 * @param {Object} [used] Object containing information about used tools, see above
1395 * @return {string[]} List of extracted tool names
1397 OO
.ui
.ToolFactory
.prototype.extract = function ( collection
, used
) {
1398 var i
, len
, item
, name
, tool
,
1401 collection
= !Array
.isArray( collection
) ? [ collection
] : collection
;
1403 for ( i
= 0, len
= collection
.length
; i
< len
; i
++ ) {
1404 item
= collection
[ i
];
1405 if ( item
=== '*' ) {
1406 for ( name
in this.registry
) {
1407 tool
= this.registry
[ name
];
1409 // Only add tools by group name when auto-add is enabled
1410 tool
.static.autoAddToCatchall
&&
1411 // Exclude already used tools
1412 ( !used
|| !used
[ name
] )
1416 used
[ name
] = true;
1421 // Allow plain strings as shorthand for named tools
1422 if ( typeof item
=== 'string' ) {
1423 item
= { name
: item
};
1425 if ( OO
.isPlainObject( item
) ) {
1427 for ( name
in this.registry
) {
1428 tool
= this.registry
[ name
];
1430 // Include tools with matching group
1431 tool
.static.group
=== item
.group
&&
1432 // Only add tools by group name when auto-add is enabled
1433 tool
.static.autoAddToGroup
&&
1434 // Exclude already used tools
1435 ( !used
|| !used
[ name
] )
1439 used
[ name
] = true;
1443 // Include tools with matching name and exclude already used tools
1444 } else if ( item
.name
&& ( !used
|| !used
[ item
.name
] ) ) {
1445 names
.push( item
.name
);
1447 used
[ item
.name
] = true;
1457 * ToolGroupFactories create {@link OO.ui.ToolGroup toolgroups} on demand. The toolgroup classes must
1458 * specify a symbolic name and be registered with the factory. The following classes are registered by
1461 * - {@link OO.ui.BarToolGroup BarToolGroups} (‘bar’)
1462 * - {@link OO.ui.MenuToolGroup MenuToolGroups} (‘menu’)
1463 * - {@link OO.ui.ListToolGroup ListToolGroups} (‘list’)
1465 * See {@link OO.ui.Toolbar toolbars} for an example.
1467 * For more information about toolbars in general, please see the [OOUI documentation on MediaWiki][1].
1469 * [1]: https://www.mediawiki.org/wiki/OOUI/Toolbars
1472 * @extends OO.Factory
1475 OO
.ui
.ToolGroupFactory
= function OoUiToolGroupFactory() {
1476 var i
, l
, defaultClasses
;
1477 // Parent constructor
1478 OO
.Factory
.call( this );
1480 defaultClasses
= this.constructor.static.getDefaultClasses();
1482 // Register default toolgroups
1483 for ( i
= 0, l
= defaultClasses
.length
; i
< l
; i
++ ) {
1484 this.register( defaultClasses
[ i
] );
1490 OO
.inheritClass( OO
.ui
.ToolGroupFactory
, OO
.Factory
);
1492 /* Static Methods */
1495 * Get a default set of classes to be registered on construction.
1497 * @return {Function[]} Default classes
1499 OO
.ui
.ToolGroupFactory
.static.getDefaultClasses = function () {
1502 OO
.ui
.ListToolGroup
,
1508 * Popup tools open a popup window when they are selected from the {@link OO.ui.Toolbar toolbar}. Each popup tool is configured
1509 * 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
1510 * an #onSelect or #onUpdateState method, as these methods have been implemented already.
1512 * // Example of a popup tool. When selected, a popup tool displays
1513 * // a popup window.
1514 * function HelpTool( toolGroup, config ) {
1515 * OO.ui.PopupTool.call( this, toolGroup, $.extend( { popup: {
1520 * this.popup.$body.append( '<p>I am helpful!</p>' );
1522 * OO.inheritClass( HelpTool, OO.ui.PopupTool );
1523 * HelpTool.static.name = 'help';
1524 * HelpTool.static.icon = 'help';
1525 * HelpTool.static.title = 'Help';
1526 * toolFactory.register( HelpTool );
1528 * For an example of a toolbar that contains a popup tool, see {@link OO.ui.Toolbar toolbars}. For more information about
1529 * toolbars in general, please see the [OOUI documentation on MediaWiki][1].
1531 * [1]: https://www.mediawiki.org/wiki/OOUI/Toolbars
1535 * @extends OO.ui.Tool
1536 * @mixins OO.ui.mixin.PopupElement
1539 * @param {OO.ui.ToolGroup} toolGroup
1540 * @param {Object} [config] Configuration options
1542 OO
.ui
.PopupTool
= function OoUiPopupTool( toolGroup
, config
) {
1543 // Allow passing positional parameters inside the config object
1544 if ( OO
.isPlainObject( toolGroup
) && config
=== undefined ) {
1546 toolGroup
= config
.toolGroup
;
1549 // Parent constructor
1550 OO
.ui
.PopupTool
.parent
.call( this, toolGroup
, config
);
1552 // Mixin constructors
1553 OO
.ui
.mixin
.PopupElement
.call( this, config
);
1556 this.popup
.connect( this, { toggle
: 'onPopupToggle' } );
1559 this.popup
.setAutoFlip( false );
1560 this.popup
.setPosition( toolGroup
.getToolbar().position
=== 'bottom' ? 'above' : 'below' );
1561 this.$element
.addClass( 'oo-ui-popupTool' );
1562 this.popup
.$element
.addClass( 'oo-ui-popupTool-popup' );
1563 this.toolbar
.$popups
.append( this.popup
.$element
);
1568 OO
.inheritClass( OO
.ui
.PopupTool
, OO
.ui
.Tool
);
1569 OO
.mixinClass( OO
.ui
.PopupTool
, OO
.ui
.mixin
.PopupElement
);
1574 * Handle the tool being selected.
1578 OO
.ui
.PopupTool
.prototype.onSelect = function () {
1579 if ( !this.isDisabled() ) {
1580 this.popup
.toggle();
1586 * Handle the toolbar state being updated.
1590 OO
.ui
.PopupTool
.prototype.onUpdateState = function () {
1594 * Handle popup visibility being toggled.
1596 * @param {boolean} isVisible
1598 OO
.ui
.PopupTool
.prototype.onPopupToggle = function ( isVisible
) {
1599 this.setActive( isVisible
);
1600 this.toolGroup
.emit( 'active', isVisible
);
1604 * A ToolGroupTool is a special sort of tool that can contain other {@link OO.ui.Tool tools}
1605 * and {@link OO.ui.ToolGroup toolgroups}. The ToolGroupTool was specifically designed to be used
1606 * inside a {@link OO.ui.BarToolGroup bar} toolgroup to provide access to additional tools from
1607 * the bar item. Included tools will be displayed in a dropdown {@link OO.ui.ListToolGroup list}
1608 * when the ToolGroupTool is selected.
1610 * // Example: ToolGroupTool with two nested tools, 'setting1' and 'setting2', defined elsewhere.
1612 * function SettingsTool() {
1613 * SettingsTool.parent.apply( this, arguments );
1615 * OO.inheritClass( SettingsTool, OO.ui.ToolGroupTool );
1616 * SettingsTool.static.name = 'settings';
1617 * SettingsTool.static.title = 'Change settings';
1618 * SettingsTool.static.groupConfig = {
1620 * label: 'ToolGroupTool',
1621 * include: [ 'setting1', 'setting2' ]
1623 * toolFactory.register( SettingsTool );
1625 * For more information, please see the [OOUI documentation on MediaWiki][1].
1627 * Please note that this implementation is subject to change per [T74159] [2].
1629 * [1]: https://www.mediawiki.org/wiki/OOUI/Toolbars#ToolGroupTool
1630 * [2]: https://phabricator.wikimedia.org/T74159
1634 * @extends OO.ui.Tool
1637 * @param {OO.ui.ToolGroup} toolGroup
1638 * @param {Object} [config] Configuration options
1640 OO
.ui
.ToolGroupTool
= function OoUiToolGroupTool( toolGroup
, config
) {
1641 // Allow passing positional parameters inside the config object
1642 if ( OO
.isPlainObject( toolGroup
) && config
=== undefined ) {
1644 toolGroup
= config
.toolGroup
;
1647 // Parent constructor
1648 OO
.ui
.ToolGroupTool
.parent
.call( this, toolGroup
, config
);
1651 this.innerToolGroup
= this.createGroup( this.constructor.static.groupConfig
);
1654 this.innerToolGroup
.connect( this, {
1655 disable
: 'onToolGroupDisable',
1656 // Re-emit active events from the innerToolGroup on the parent toolGroup
1657 active
: this.toolGroup
.emit
.bind( this.toolGroup
, 'active' )
1661 this.$link
.remove();
1663 .addClass( 'oo-ui-toolGroupTool' )
1664 .append( this.innerToolGroup
.$element
);
1669 OO
.inheritClass( OO
.ui
.ToolGroupTool
, OO
.ui
.Tool
);
1671 /* Static Properties */
1674 * Toolgroup configuration.
1676 * The toolgroup configuration consists of the tools to include, as well as an icon and label
1677 * to use for the bar item. Tools can be included by symbolic name, group, or with the
1678 * wildcard selector. Please see {@link OO.ui.ToolGroup toolgroup} for more information.
1680 * @property {Object.<string,Array>}
1682 OO
.ui
.ToolGroupTool
.static.groupConfig
= {};
1687 * Handle the tool being selected.
1691 OO
.ui
.ToolGroupTool
.prototype.onSelect = function () {
1692 this.innerToolGroup
.setActive( !this.innerToolGroup
.active
);
1697 * Synchronize disabledness state of the tool with the inner toolgroup.
1700 * @param {boolean} disabled Element is disabled
1702 OO
.ui
.ToolGroupTool
.prototype.onToolGroupDisable = function ( disabled
) {
1703 this.setDisabled( disabled
);
1707 * Handle the toolbar state being updated.
1711 OO
.ui
.ToolGroupTool
.prototype.onUpdateState = function () {
1712 this.setActive( false );
1716 * Build a {@link OO.ui.ToolGroup toolgroup} from the specified configuration.
1718 * @param {Object.<string,Array>} group Toolgroup configuration. Please see {@link OO.ui.ToolGroup toolgroup} for
1720 * @return {OO.ui.ListToolGroup}
1722 OO
.ui
.ToolGroupTool
.prototype.createGroup = function ( group
) {
1723 if ( group
.include
=== '*' ) {
1724 // Apply defaults to catch-all groups
1725 if ( group
.label
=== undefined ) {
1726 group
.label
= OO
.ui
.msg( 'ooui-toolbar-more' );
1730 return this.toolbar
.getToolGroupFactory().create( 'list', this.toolbar
, group
);
1734 * BarToolGroups are one of three types of {@link OO.ui.ToolGroup toolgroups} that are used to
1735 * create {@link OO.ui.Toolbar toolbars} (the other types of groups are {@link OO.ui.MenuToolGroup MenuToolGroup}
1736 * and {@link OO.ui.ListToolGroup ListToolGroup}). The {@link OO.ui.Tool tools} in a BarToolGroup are
1737 * displayed by icon in a single row. The title of the tool is displayed when users move the mouse over
1740 * BarToolGroups are created by a {@link OO.ui.ToolGroupFactory tool group factory} when the toolbar is
1744 * // Example of a BarToolGroup with two tools
1745 * var toolFactory = new OO.ui.ToolFactory();
1746 * var toolGroupFactory = new OO.ui.ToolGroupFactory();
1747 * var toolbar = new OO.ui.Toolbar( toolFactory, toolGroupFactory );
1749 * // We will be placing status text in this element when tools are used
1750 * var $area = $( '<p>' ).text( 'Example of a BarToolGroup with two tools.' );
1752 * // Define the tools that we're going to place in our toolbar
1754 * // Create a class inheriting from OO.ui.Tool
1755 * function SearchTool() {
1756 * SearchTool.parent.apply( this, arguments );
1758 * OO.inheritClass( SearchTool, OO.ui.Tool );
1759 * // Each tool must have a 'name' (used as an internal identifier, see later) and at least one
1760 * // of 'icon' and 'title' (displayed icon and text).
1761 * SearchTool.static.name = 'search';
1762 * SearchTool.static.icon = 'search';
1763 * SearchTool.static.title = 'Search...';
1764 * // Defines the action that will happen when this tool is selected (clicked).
1765 * SearchTool.prototype.onSelect = function () {
1766 * $area.text( 'Search tool clicked!' );
1767 * // Never display this tool as "active" (selected).
1768 * this.setActive( false );
1770 * SearchTool.prototype.onUpdateState = function () {};
1771 * // Make this tool available in our toolFactory and thus our toolbar
1772 * toolFactory.register( SearchTool );
1774 * // This is a PopupTool. Rather than having a custom 'onSelect' action, it will display a
1775 * // little popup window (a PopupWidget).
1776 * function HelpTool( toolGroup, config ) {
1777 * OO.ui.PopupTool.call( this, toolGroup, $.extend( { popup: {
1782 * this.popup.$body.append( '<p>I am helpful!</p>' );
1784 * OO.inheritClass( HelpTool, OO.ui.PopupTool );
1785 * HelpTool.static.name = 'help';
1786 * HelpTool.static.icon = 'help';
1787 * HelpTool.static.title = 'Help';
1788 * toolFactory.register( HelpTool );
1790 * // Finally define which tools and in what order appear in the toolbar. Each tool may only be
1791 * // used once (but not all defined tools must be used).
1794 * // 'bar' tool groups display tools by icon only
1796 * include: [ 'search', 'help' ]
1800 * // Create some UI around the toolbar and place it in the document
1801 * var frame = new OO.ui.PanelLayout( {
1805 * var contentFrame = new OO.ui.PanelLayout( {
1809 * frame.$element.append(
1811 * contentFrame.$element.append( $area )
1813 * $( 'body' ).append( frame.$element );
1815 * // Here is where the toolbar is actually built. This must be done after inserting it into the
1817 * toolbar.initialize();
1819 * For more information about how to add tools to a bar tool group, please see {@link OO.ui.ToolGroup toolgroup}.
1820 * For more information about toolbars in general, please see the [OOUI documentation on MediaWiki][1].
1822 * [1]: https://www.mediawiki.org/wiki/OOUI/Toolbars
1825 * @extends OO.ui.ToolGroup
1828 * @param {OO.ui.Toolbar} toolbar
1829 * @param {Object} [config] Configuration options
1831 OO
.ui
.BarToolGroup
= function OoUiBarToolGroup( toolbar
, config
) {
1832 // Allow passing positional parameters inside the config object
1833 if ( OO
.isPlainObject( toolbar
) && config
=== undefined ) {
1835 toolbar
= config
.toolbar
;
1838 // Parent constructor
1839 OO
.ui
.BarToolGroup
.parent
.call( this, toolbar
, config
);
1842 this.$element
.addClass( 'oo-ui-barToolGroup' );
1843 this.$group
.addClass( 'oo-ui-barToolGroup-tools' );
1848 OO
.inheritClass( OO
.ui
.BarToolGroup
, OO
.ui
.ToolGroup
);
1850 /* Static Properties */
1856 OO
.ui
.BarToolGroup
.static.titleTooltips
= true;
1862 OO
.ui
.BarToolGroup
.static.accelTooltips
= true;
1868 OO
.ui
.BarToolGroup
.static.name
= 'bar';
1871 * PopupToolGroup is an abstract base class used by both {@link OO.ui.MenuToolGroup MenuToolGroup}
1872 * and {@link OO.ui.ListToolGroup ListToolGroup} to provide a popup (an overlaid menu or list of tools with an
1873 * optional icon and label). This class can be used for other base classes that also use this functionality.
1877 * @extends OO.ui.ToolGroup
1878 * @mixins OO.ui.mixin.IconElement
1879 * @mixins OO.ui.mixin.IndicatorElement
1880 * @mixins OO.ui.mixin.LabelElement
1881 * @mixins OO.ui.mixin.TitledElement
1882 * @mixins OO.ui.mixin.FlaggedElement
1883 * @mixins OO.ui.mixin.ClippableElement
1884 * @mixins OO.ui.mixin.FloatableElement
1885 * @mixins OO.ui.mixin.TabIndexedElement
1888 * @param {OO.ui.Toolbar} toolbar
1889 * @param {Object} [config] Configuration options
1890 * @cfg {string} [header] Text to display at the top of the popup
1892 OO
.ui
.PopupToolGroup
= function OoUiPopupToolGroup( toolbar
, config
) {
1893 // Allow passing positional parameters inside the config object
1894 if ( OO
.isPlainObject( toolbar
) && config
=== undefined ) {
1896 toolbar
= config
.toolbar
;
1899 // Configuration initialization
1900 config
= $.extend( {
1901 indicator
: config
.indicator
=== undefined ? ( toolbar
.position
=== 'bottom' ? 'up' : 'down' ) : config
.indicator
1904 // Parent constructor
1905 OO
.ui
.PopupToolGroup
.parent
.call( this, toolbar
, config
);
1908 this.active
= false;
1909 this.dragging
= false;
1910 // Don't conflict with parent method of the same name
1911 this.onPopupDocumentMouseKeyUpHandler
= this.onPopupDocumentMouseKeyUp
.bind( this );
1912 this.$handle
= $( '<span>' );
1914 // Mixin constructors
1915 OO
.ui
.mixin
.IconElement
.call( this, config
);
1916 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
1917 OO
.ui
.mixin
.LabelElement
.call( this, config
);
1918 OO
.ui
.mixin
.TitledElement
.call( this, config
);
1919 OO
.ui
.mixin
.FlaggedElement
.call( this, config
);
1920 OO
.ui
.mixin
.ClippableElement
.call( this, $.extend( {}, config
, { $clippable
: this.$group
} ) );
1921 OO
.ui
.mixin
.FloatableElement
.call( this, $.extend( {}, config
, {
1922 $floatable
: this.$group
,
1923 $floatableContainer
: this.$handle
,
1924 hideWhenOutOfView
: false,
1925 verticalPosition
: this.toolbar
.position
=== 'bottom' ? 'above' : 'below'
1927 OO
.ui
.mixin
.TabIndexedElement
.call( this, $.extend( {}, config
, { $tabIndexed
: this.$handle
} ) );
1931 keydown
: this.onHandleMouseKeyDown
.bind( this ),
1932 keyup
: this.onHandleMouseKeyUp
.bind( this ),
1933 mousedown
: this.onHandleMouseKeyDown
.bind( this ),
1934 mouseup
: this.onHandleMouseKeyUp
.bind( this )
1939 .addClass( 'oo-ui-popupToolGroup-handle' )
1940 .attr( 'role', 'button' )
1941 .append( this.$icon
, this.$label
, this.$indicator
);
1942 // If the pop-up should have a header, add it to the top of the toolGroup.
1943 // Note: If this feature is useful for other widgets, we could abstract it into an
1944 // OO.ui.HeaderedElement mixin constructor.
1945 if ( config
.header
!== undefined ) {
1947 .prepend( $( '<span>' )
1948 .addClass( 'oo-ui-popupToolGroup-header' )
1949 .text( config
.header
)
1953 .addClass( 'oo-ui-popupToolGroup' )
1954 .prepend( this.$handle
);
1955 this.$group
.addClass( 'oo-ui-popupToolGroup-tools' );
1956 this.toolbar
.$popups
.append( this.$group
);
1961 OO
.inheritClass( OO
.ui
.PopupToolGroup
, OO
.ui
.ToolGroup
);
1962 OO
.mixinClass( OO
.ui
.PopupToolGroup
, OO
.ui
.mixin
.IconElement
);
1963 OO
.mixinClass( OO
.ui
.PopupToolGroup
, OO
.ui
.mixin
.IndicatorElement
);
1964 OO
.mixinClass( OO
.ui
.PopupToolGroup
, OO
.ui
.mixin
.LabelElement
);
1965 OO
.mixinClass( OO
.ui
.PopupToolGroup
, OO
.ui
.mixin
.TitledElement
);
1966 OO
.mixinClass( OO
.ui
.PopupToolGroup
, OO
.ui
.mixin
.FlaggedElement
);
1967 OO
.mixinClass( OO
.ui
.PopupToolGroup
, OO
.ui
.mixin
.ClippableElement
);
1968 OO
.mixinClass( OO
.ui
.PopupToolGroup
, OO
.ui
.mixin
.FloatableElement
);
1969 OO
.mixinClass( OO
.ui
.PopupToolGroup
, OO
.ui
.mixin
.TabIndexedElement
);
1976 OO
.ui
.PopupToolGroup
.prototype.setDisabled = function () {
1978 OO
.ui
.PopupToolGroup
.parent
.prototype.setDisabled
.apply( this, arguments
);
1980 if ( this.isDisabled() && this.isElementAttached() ) {
1981 this.setActive( false );
1986 * Handle document mouse up and key up events.
1989 * @param {MouseEvent|KeyboardEvent} e Mouse up or key up event
1991 OO
.ui
.PopupToolGroup
.prototype.onPopupDocumentMouseKeyUp = function ( e
) {
1992 var $target
= $( e
.target
);
1993 // Only deactivate when clicking outside the dropdown element
1994 if ( $target
.closest( '.oo-ui-popupToolGroup' )[ 0 ] === this.$element
[ 0 ] ) {
1997 if ( $target
.closest( '.oo-ui-popupToolGroup-tools' )[ 0 ] === this.$group
[ 0 ] ) {
2000 this.setActive( false );
2003 // Deprecated alias since 0.28.3
2004 OO
.ui
.PopupToolGroup
.prototype.onBlur = function () {
2005 OO
.ui
.warnDeprecation( 'onBlur is deprecated, use onPopupDocumentMouseKeyUp instead' );
2006 this.onPopupDocumentMouseKeyUp
.apply( this, arguments
);
2012 OO
.ui
.PopupToolGroup
.prototype.onMouseKeyUp = function ( e
) {
2013 // Only close toolgroup when a tool was actually selected
2015 !this.isDisabled() && this.pressed
&& this.pressed
=== this.findTargetTool( e
) &&
2016 ( e
.which
=== OO
.ui
.MouseButtons
.LEFT
|| e
.which
=== OO
.ui
.Keys
.SPACE
|| e
.which
=== OO
.ui
.Keys
.ENTER
)
2018 this.setActive( false );
2020 return OO
.ui
.PopupToolGroup
.parent
.prototype.onMouseKeyUp
.call( this, e
);
2026 OO
.ui
.PopupToolGroup
.prototype.onMouseKeyDown = function ( e
) {
2027 var $focused
, $firstFocusable
, $lastFocusable
;
2028 // Shift-Tab on the first tool in the group jumps to the handle.
2029 // Tab on the last tool in the group jumps to the next group.
2030 if ( !this.isDisabled() && e
.which
=== OO
.ui
.Keys
.TAB
) {
2031 // (We can't use this.items because ListToolGroup inserts the extra fake expand/collapse tool.)
2032 $focused
= $( document
.activeElement
);
2033 $firstFocusable
= OO
.ui
.findFocusable( this.$group
);
2034 if ( $focused
[ 0 ] === $firstFocusable
[ 0 ] && e
.shiftKey
) {
2035 this.$handle
.focus();
2038 $lastFocusable
= OO
.ui
.findFocusable( this.$group
, true );
2039 if ( $focused
[ 0 ] === $lastFocusable
[ 0 ] && !e
.shiftKey
) {
2040 // Focus this group's handle and let the browser's tab handling happen (no 'return false').
2041 // This way we don't have to fiddle with other ToolGroups' business, or worry what to do
2042 // if the next group is not a PopupToolGroup or doesn't exist at all.
2043 this.$handle
.focus();
2044 // Close the popup so that we don't move back inside it (if this is the last group).
2045 this.setActive( false );
2048 return OO
.ui
.PopupToolGroup
.parent
.prototype.onMouseKeyDown
.call( this, e
);
2052 * Handle mouse up and key up events.
2055 * @param {jQuery.Event} e Mouse up or key up event
2056 * @return {undefined/boolean} False to prevent default if event is handled
2058 OO
.ui
.PopupToolGroup
.prototype.onHandleMouseKeyUp = function ( e
) {
2060 !this.isDisabled() &&
2061 ( e
.which
=== OO
.ui
.MouseButtons
.LEFT
|| e
.which
=== OO
.ui
.Keys
.SPACE
|| e
.which
=== OO
.ui
.Keys
.ENTER
)
2068 * Handle mouse down and key down events.
2071 * @param {jQuery.Event} e Mouse down or key down event
2072 * @return {undefined/boolean} False to prevent default if event is handled
2074 OO
.ui
.PopupToolGroup
.prototype.onHandleMouseKeyDown = function ( e
) {
2076 if ( !this.isDisabled() ) {
2077 // Tab on the handle jumps to the first tool in the group (if the popup is open).
2078 if ( e
.which
=== OO
.ui
.Keys
.TAB
&& !e
.shiftKey
) {
2079 $focusable
= OO
.ui
.findFocusable( this.$group
);
2080 if ( $focusable
.length
) {
2085 if ( e
.which
=== OO
.ui
.MouseButtons
.LEFT
|| e
.which
=== OO
.ui
.Keys
.SPACE
|| e
.which
=== OO
.ui
.Keys
.ENTER
) {
2086 this.setActive( !this.active
);
2093 * Check if the tool group is active.
2095 * @return {boolean} Tool group is active
2097 OO
.ui
.PopupToolGroup
.prototype.isActive = function () {
2102 * Switch into 'active' mode.
2104 * When active, the popup is visible. A mouseup event anywhere in the document will trigger
2107 * @param {boolean} value The active state to set
2110 OO
.ui
.PopupToolGroup
.prototype.setActive = function ( value
) {
2111 var containerWidth
, containerLeft
;
2113 if ( this.active
!== value
) {
2114 this.active
= value
;
2116 this.getElementDocument().addEventListener( 'mouseup', this.onPopupDocumentMouseKeyUpHandler
, true );
2117 this.getElementDocument().addEventListener( 'keyup', this.onPopupDocumentMouseKeyUpHandler
, true );
2119 this.$clippable
.css( 'left', '' );
2120 this.$element
.addClass( 'oo-ui-popupToolGroup-active' );
2121 this.$group
.addClass( 'oo-ui-popupToolGroup-active-tools' );
2122 this.togglePositioning( true );
2123 this.toggleClipping( true );
2125 // Try anchoring the popup to the left first
2126 this.setHorizontalPosition( 'start' );
2128 if ( this.isClippedHorizontally() || this.isFloatableOutOfView() ) {
2129 // Anchoring to the left caused the popup to clip, so anchor it to the right instead
2130 this.setHorizontalPosition( 'end' );
2132 if ( this.isClippedHorizontally() || this.isFloatableOutOfView() ) {
2133 // Anchoring to the right also caused the popup to clip, so just make it fill the container
2134 containerWidth
= this.$clippableScrollableContainer
.width();
2135 containerLeft
= this.$clippableScrollableContainer
[ 0 ] === document
.documentElement
?
2137 this.$clippableScrollableContainer
.offset().left
;
2139 this.toggleClipping( false );
2140 this.setHorizontalPosition( 'start' );
2142 this.$clippable
.css( {
2143 'margin-left': -( this.$element
.offset().left
- containerLeft
),
2144 width
: containerWidth
2148 this.getElementDocument().removeEventListener( 'mouseup', this.onPopupDocumentMouseKeyUpHandler
, true );
2149 this.getElementDocument().removeEventListener( 'keyup', this.onPopupDocumentMouseKeyUpHandler
, true );
2150 this.$element
.removeClass( 'oo-ui-popupToolGroup-active' );
2151 this.$group
.removeClass( 'oo-ui-popupToolGroup-active-tools' );
2152 this.togglePositioning( false );
2153 this.toggleClipping( false );
2155 this.emit( 'active', this.active
);
2156 this.updateThemeClasses();
2161 * ListToolGroups are one of three types of {@link OO.ui.ToolGroup toolgroups} that are used to
2162 * create {@link OO.ui.Toolbar toolbars} (the other types of groups are {@link OO.ui.MenuToolGroup MenuToolGroup}
2163 * and {@link OO.ui.BarToolGroup BarToolGroup}). The {@link OO.ui.Tool tools} in a ListToolGroup are displayed
2164 * by label in a dropdown menu. The title of the tool is used as the label text. The menu itself can be configured
2165 * with a label, icon, indicator, header, and title.
2167 * ListToolGroups can be configured to be expanded and collapsed. Collapsed lists will have a ‘More’ option that
2168 * users can select to see the full list of tools. If a collapsed toolgroup is expanded, a ‘Fewer’ option permits
2169 * users to collapse the list again.
2171 * ListToolGroups are created by a {@link OO.ui.ToolGroupFactory toolgroup factory} when the toolbar is set up. The factory
2172 * requires the ListToolGroup's symbolic name, 'list', which is specified along with the other configurations. For more
2173 * information about how to add tools to a ListToolGroup, please see {@link OO.ui.ToolGroup toolgroup}.
2176 * // Example of a ListToolGroup
2177 * var toolFactory = new OO.ui.ToolFactory();
2178 * var toolGroupFactory = new OO.ui.ToolGroupFactory();
2179 * var toolbar = new OO.ui.Toolbar( toolFactory, toolGroupFactory );
2181 * // Configure and register two tools
2182 * function SettingsTool() {
2183 * SettingsTool.parent.apply( this, arguments );
2185 * OO.inheritClass( SettingsTool, OO.ui.Tool );
2186 * SettingsTool.static.name = 'settings';
2187 * SettingsTool.static.icon = 'settings';
2188 * SettingsTool.static.title = 'Change settings';
2189 * SettingsTool.prototype.onSelect = function () {
2190 * this.setActive( false );
2192 * SettingsTool.prototype.onUpdateState = function () {};
2193 * toolFactory.register( SettingsTool );
2194 * // Register two more tools, nothing interesting here
2195 * function StuffTool() {
2196 * StuffTool.parent.apply( this, arguments );
2198 * OO.inheritClass( StuffTool, OO.ui.Tool );
2199 * StuffTool.static.name = 'stuff';
2200 * StuffTool.static.icon = 'search';
2201 * StuffTool.static.title = 'Change the world';
2202 * StuffTool.prototype.onSelect = function () {
2203 * this.setActive( false );
2205 * StuffTool.prototype.onUpdateState = function () {};
2206 * toolFactory.register( StuffTool );
2209 * // Configurations for list toolgroup.
2211 * label: 'ListToolGroup',
2213 * title: 'This is the title, displayed when user moves the mouse over the list toolgroup',
2214 * header: 'This is the header',
2215 * include: [ 'settings', 'stuff' ],
2216 * allowCollapse: ['stuff']
2220 * // Create some UI around the toolbar and place it in the document
2221 * var frame = new OO.ui.PanelLayout( {
2225 * frame.$element.append(
2228 * $( 'body' ).append( frame.$element );
2229 * // Build the toolbar. This must be done after the toolbar has been appended to the document.
2230 * toolbar.initialize();
2232 * For more information about toolbars in general, please see the [OOUI documentation on MediaWiki][1].
2234 * [1]: https://www.mediawiki.org/wiki/OOUI/Toolbars
2237 * @extends OO.ui.PopupToolGroup
2240 * @param {OO.ui.Toolbar} toolbar
2241 * @param {Object} [config] Configuration options
2242 * @cfg {Array} [allowCollapse] Allow the specified tools to be collapsed. By default, collapsible tools
2243 * will only be displayed if users click the ‘More’ option displayed at the bottom of the list. If
2244 * the list is expanded, a ‘Fewer’ option permits users to collapse the list again. Any tools that
2245 * are included in the toolgroup, but are not designated as collapsible, will always be displayed.
2246 * To open a collapsible list in its expanded state, set #expanded to 'true'.
2247 * @cfg {Array} [forceExpand] Expand the specified tools. All other tools will be designated as collapsible.
2248 * Unless #expanded is set to true, the collapsible tools will be collapsed when the list is first opened.
2249 * @cfg {boolean} [expanded=false] Expand collapsible tools. This config is only relevant if tools have
2250 * been designated as collapsible. When expanded is set to true, all tools in the group will be displayed
2251 * when the list is first opened. Users can collapse the list with a ‘Fewer’ option at the bottom.
2253 OO
.ui
.ListToolGroup
= function OoUiListToolGroup( toolbar
, config
) {
2254 // Allow passing positional parameters inside the config object
2255 if ( OO
.isPlainObject( toolbar
) && config
=== undefined ) {
2257 toolbar
= config
.toolbar
;
2260 // Configuration initialization
2261 config
= config
|| {};
2263 // Properties (must be set before parent constructor, which calls #populate)
2264 this.allowCollapse
= config
.allowCollapse
;
2265 this.forceExpand
= config
.forceExpand
;
2266 this.expanded
= config
.expanded
!== undefined ? config
.expanded
: false;
2267 this.collapsibleTools
= [];
2269 // Parent constructor
2270 OO
.ui
.ListToolGroup
.parent
.call( this, toolbar
, config
);
2273 this.$element
.addClass( 'oo-ui-listToolGroup' );
2274 this.$group
.addClass( 'oo-ui-listToolGroup-tools' );
2279 OO
.inheritClass( OO
.ui
.ListToolGroup
, OO
.ui
.PopupToolGroup
);
2281 /* Static Properties */
2287 OO
.ui
.ListToolGroup
.static.name
= 'list';
2294 OO
.ui
.ListToolGroup
.prototype.populate = function () {
2295 var i
, len
, allowCollapse
= [];
2297 OO
.ui
.ListToolGroup
.parent
.prototype.populate
.call( this );
2299 // Update the list of collapsible tools
2300 if ( this.allowCollapse
!== undefined ) {
2301 allowCollapse
= this.allowCollapse
;
2302 } else if ( this.forceExpand
!== undefined ) {
2303 allowCollapse
= OO
.simpleArrayDifference( Object
.keys( this.tools
), this.forceExpand
);
2306 this.collapsibleTools
= [];
2307 for ( i
= 0, len
= allowCollapse
.length
; i
< len
; i
++ ) {
2308 if ( this.tools
[ allowCollapse
[ i
] ] !== undefined ) {
2309 this.collapsibleTools
.push( this.tools
[ allowCollapse
[ i
] ] );
2313 // Keep at the end, even when tools are added
2314 this.$group
.append( this.getExpandCollapseTool().$element
);
2316 this.getExpandCollapseTool().toggle( this.collapsibleTools
.length
!== 0 );
2317 this.updateCollapsibleState();
2321 * Get the expand/collapse tool for this group
2323 * @return {OO.ui.Tool} Expand collapse tool
2325 OO
.ui
.ListToolGroup
.prototype.getExpandCollapseTool = function () {
2326 var ExpandCollapseTool
;
2327 if ( this.expandCollapseTool
=== undefined ) {
2328 ExpandCollapseTool = function () {
2329 ExpandCollapseTool
.parent
.apply( this, arguments
);
2332 OO
.inheritClass( ExpandCollapseTool
, OO
.ui
.Tool
);
2334 ExpandCollapseTool
.prototype.onSelect = function () {
2335 this.toolGroup
.expanded
= !this.toolGroup
.expanded
;
2336 this.toolGroup
.updateCollapsibleState();
2337 this.setActive( false );
2339 ExpandCollapseTool
.prototype.onUpdateState = function () {
2340 // Do nothing. Tool interface requires an implementation of this function.
2343 ExpandCollapseTool
.static.name
= 'more-fewer';
2345 this.expandCollapseTool
= new ExpandCollapseTool( this );
2347 return this.expandCollapseTool
;
2353 OO
.ui
.ListToolGroup
.prototype.onMouseKeyUp = function ( e
) {
2354 // Do not close the popup when the user wants to show more/fewer tools
2356 $( e
.target
).closest( '.oo-ui-tool-name-more-fewer' ).length
&&
2357 ( e
.which
=== OO
.ui
.MouseButtons
.LEFT
|| e
.which
=== OO
.ui
.Keys
.SPACE
|| e
.which
=== OO
.ui
.Keys
.ENTER
)
2359 // HACK: Prevent the popup list from being hidden. Skip the PopupToolGroup implementation (which
2360 // hides the popup list when a tool is selected) and call ToolGroup's implementation directly.
2361 return OO
.ui
.ListToolGroup
.parent
.parent
.prototype.onMouseKeyUp
.call( this, e
);
2363 return OO
.ui
.ListToolGroup
.parent
.prototype.onMouseKeyUp
.call( this, e
);
2367 OO
.ui
.ListToolGroup
.prototype.updateCollapsibleState = function () {
2370 if ( this.toolbar
.position
!== 'bottom' ) {
2371 icon
= this.expanded
? 'collapse' : 'expand';
2373 icon
= this.expanded
? 'expand' : 'collapse';
2376 this.getExpandCollapseTool()
2378 .setTitle( OO
.ui
.msg( this.expanded
? 'ooui-toolgroup-collapse' : 'ooui-toolgroup-expand' ) );
2380 for ( i
= 0, len
= this.collapsibleTools
.length
; i
< len
; i
++ ) {
2381 this.collapsibleTools
[ i
].toggle( this.expanded
);
2384 // Re-evaluate clipping, because our height has changed
2389 * MenuToolGroups are one of three types of {@link OO.ui.ToolGroup toolgroups} that are used to
2390 * create {@link OO.ui.Toolbar toolbars} (the other types of groups are {@link OO.ui.BarToolGroup BarToolGroup}
2391 * and {@link OO.ui.ListToolGroup ListToolGroup}). MenuToolGroups contain selectable {@link OO.ui.Tool tools},
2392 * which are displayed by label in a dropdown menu. The tool's title is used as the label text, and the
2393 * menu label is updated to reflect which tool or tools are currently selected. If no tools are selected,
2394 * the menu label is empty. The menu can be configured with an indicator, icon, title, and/or header.
2396 * MenuToolGroups are created by a {@link OO.ui.ToolGroupFactory tool group factory} when the toolbar
2400 * // Example of a MenuToolGroup
2401 * var toolFactory = new OO.ui.ToolFactory();
2402 * var toolGroupFactory = new OO.ui.ToolGroupFactory();
2403 * var toolbar = new OO.ui.Toolbar( toolFactory, toolGroupFactory );
2405 * // We will be placing status text in this element when tools are used
2406 * var $area = $( '<p>' ).text( 'An example of a MenuToolGroup. Select a tool from the dropdown menu.' );
2408 * // Define the tools that we're going to place in our toolbar
2410 * function SettingsTool() {
2411 * SettingsTool.parent.apply( this, arguments );
2412 * this.reallyActive = false;
2414 * OO.inheritClass( SettingsTool, OO.ui.Tool );
2415 * SettingsTool.static.name = 'settings';
2416 * SettingsTool.static.icon = 'settings';
2417 * SettingsTool.static.title = 'Change settings';
2418 * SettingsTool.prototype.onSelect = function () {
2419 * $area.text( 'Settings tool clicked!' );
2420 * // Toggle the active state on each click
2421 * this.reallyActive = !this.reallyActive;
2422 * this.setActive( this.reallyActive );
2423 * // To update the menu label
2424 * this.toolbar.emit( 'updateState' );
2426 * SettingsTool.prototype.onUpdateState = function () {};
2427 * toolFactory.register( SettingsTool );
2429 * function StuffTool() {
2430 * StuffTool.parent.apply( this, arguments );
2431 * this.reallyActive = false;
2433 * OO.inheritClass( StuffTool, OO.ui.Tool );
2434 * StuffTool.static.name = 'stuff';
2435 * StuffTool.static.icon = 'ellipsis';
2436 * StuffTool.static.title = 'More stuff';
2437 * StuffTool.prototype.onSelect = function () {
2438 * $area.text( 'More stuff tool clicked!' );
2439 * // Toggle the active state on each click
2440 * this.reallyActive = !this.reallyActive;
2441 * this.setActive( this.reallyActive );
2442 * // To update the menu label
2443 * this.toolbar.emit( 'updateState' );
2445 * StuffTool.prototype.onUpdateState = function () {};
2446 * toolFactory.register( StuffTool );
2448 * // Finally define which tools and in what order appear in the toolbar. Each tool may only be
2449 * // used once (but not all defined tools must be used).
2453 * header: 'This is the (optional) header',
2454 * title: 'This is the (optional) title',
2455 * include: [ 'settings', 'stuff' ]
2459 * // Create some UI around the toolbar and place it in the document
2460 * var frame = new OO.ui.PanelLayout( {
2464 * var contentFrame = new OO.ui.PanelLayout( {
2468 * frame.$element.append(
2470 * contentFrame.$element.append( $area )
2472 * $( 'body' ).append( frame.$element );
2474 * // Here is where the toolbar is actually built. This must be done after inserting it into the
2476 * toolbar.initialize();
2477 * toolbar.emit( 'updateState' );
2479 * For more information about how to add tools to a MenuToolGroup, please see {@link OO.ui.ToolGroup toolgroup}.
2480 * For more information about toolbars in general, please see the [OOUI documentation on MediaWiki] [1].
2482 * [1]: https://www.mediawiki.org/wiki/OOUI/Toolbars
2485 * @extends OO.ui.PopupToolGroup
2488 * @param {OO.ui.Toolbar} toolbar
2489 * @param {Object} [config] Configuration options
2491 OO
.ui
.MenuToolGroup
= function OoUiMenuToolGroup( toolbar
, config
) {
2492 // Allow passing positional parameters inside the config object
2493 if ( OO
.isPlainObject( toolbar
) && config
=== undefined ) {
2495 toolbar
= config
.toolbar
;
2498 // Configuration initialization
2499 config
= config
|| {};
2501 // Parent constructor
2502 OO
.ui
.MenuToolGroup
.parent
.call( this, toolbar
, config
);
2505 this.toolbar
.connect( this, { updateState
: 'onUpdateState' } );
2508 this.$element
.addClass( 'oo-ui-menuToolGroup' );
2509 this.$group
.addClass( 'oo-ui-menuToolGroup-tools' );
2514 OO
.inheritClass( OO
.ui
.MenuToolGroup
, OO
.ui
.PopupToolGroup
);
2516 /* Static Properties */
2522 OO
.ui
.MenuToolGroup
.static.name
= 'menu';
2527 * Handle the toolbar state being updated.
2529 * When the state changes, the title of each active item in the menu will be joined together and
2530 * used as a label for the group. The label will be empty if none of the items are active.
2534 OO
.ui
.MenuToolGroup
.prototype.onUpdateState = function () {
2538 for ( name
in this.tools
) {
2539 if ( this.tools
[ name
].isActive() ) {
2540 labelTexts
.push( this.tools
[ name
].getTitle() );
2544 this.setLabel( labelTexts
.join( ', ' ) || ' ' );
2549 //# sourceMappingURL=oojs-ui-toolbars.js.map.json