resources/lib/ooui/oojs-ui-toolbars.js

   1 /*!
   2  * OOUI v0.31.0
   3  * https://www.mediawiki.org/wiki/OOUI
   4  *
   5  * Copyright 2011–2019 OOUI Team and other contributors.
   6  * Released under the MIT license
   7  * http://oojs.mit-license.org
   8  *
   9  * Date: 2019-03-14T00:52:20Z
  10  */
  11 ( function ( OO ) {
  12
  13 'use strict';
  14
  15 /**
  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
  18  * commands that are part of the toolbar, but not configured as tools.
  19  *
  20  * Individual tools are customized and then registered with a
  21  * {@link OO.ui.ToolFactory tool factory}, which creates the tools on demand. Each tool has a
  22  * symbolic name (used when registering the tool), a title (e.g., ‘Insert image’), and an icon.
  23  *
  24  * Individual tools are organized in {@link OO.ui.ToolGroup toolgroups}, which can be
  25  * {@link OO.ui.MenuToolGroup menus} of tools, {@link OO.ui.ListToolGroup lists} of tools, or a
  26  * single {@link OO.ui.BarToolGroup bar} of tools. The arrangement and order of the toolgroups is
  27  * customized when the toolbar is set up. Tools can be presented in any order, but each can only
  28  * appear once in the toolbar.
  29  *
  30  * The toolbar can be synchronized with the state of the external "application", like a text
  31  * editor's editing area, marking tools as active/inactive (e.g. a 'bold' tool would be shown as
  32  * active when the text cursor was inside bolded text) or enabled/disabled (e.g. a table caption
  33  * tool would be disabled while the user is not editing a table). A state change is signalled by
  34  * emitting the {@link #event-updateState 'updateState' event}, which calls Tools'
  35  * {@link OO.ui.Tool#onUpdateState onUpdateState method}.
  36  *
  37  * The following is an example of a basic toolbar.
  38  *
  39  *     @example
  40  *     // Example of a toolbar
  41  *     // Create the toolbar
  42  *     var toolFactory = new OO.ui.ToolFactory();
  43  *     var toolGroupFactory = new OO.ui.ToolGroupFactory();
  44  *     var toolbar = new OO.ui.Toolbar( toolFactory, toolGroupFactory );
  45  *
  46  *     // We will be placing status text in this element when tools are used
  47  *     var $area = $( '<p>' ).text( 'Toolbar example' );
  48  *
  49  *     // Define the tools that we're going to place in our toolbar
  50  *
  51  *     // Create a class inheriting from OO.ui.Tool
  52  *     function SearchTool() {
  53  *         SearchTool.parent.apply( this, arguments );
  54  *     }
  55  *     OO.inheritClass( SearchTool, OO.ui.Tool );
  56  *     // Each tool must have a 'name' (used as an internal identifier, see later) and at least one
  57  *     // of 'icon' and 'title' (displayed icon and text).
  58  *     SearchTool.static.name = 'search';
  59  *     SearchTool.static.icon = 'search';
  60  *     SearchTool.static.title = 'Search...';
  61  *     // Defines the action that will happen when this tool is selected (clicked).
  62  *     SearchTool.prototype.onSelect = function () {
  63  *         $area.text( 'Search tool clicked!' );
  64  *         // Never display this tool as "active" (selected).
  65  *         this.setActive( false );
  66  *     };
  67  *     SearchTool.prototype.onUpdateState = function () {};
  68  *     // Make this tool available in our toolFactory and thus our toolbar
  69  *     toolFactory.register( SearchTool );
  70  *
  71  *     // Register two more tools, nothing interesting here
  72  *     function SettingsTool() {
  73  *         SettingsTool.parent.apply( this, arguments );
  74  *     }
  75  *     OO.inheritClass( SettingsTool, OO.ui.Tool );
  76  *     SettingsTool.static.name = 'settings';
  77  *     SettingsTool.static.icon = 'settings';
  78  *     SettingsTool.static.title = 'Change settings';
  79  *     SettingsTool.prototype.onSelect = function () {
  80  *         $area.text( 'Settings tool clicked!' );
  81  *         this.setActive( false );
  82  *     };
  83  *     SettingsTool.prototype.onUpdateState = function () {};
  84  *     toolFactory.register( SettingsTool );
  85  *
  86  *     // Register two more tools, nothing interesting here
  87  *     function StuffTool() {
  88  *         StuffTool.parent.apply( this, arguments );
  89  *     }
  90  *     OO.inheritClass( StuffTool, OO.ui.Tool );
  91  *     StuffTool.static.name = 'stuff';
  92  *     StuffTool.static.icon = 'ellipsis';
  93  *     StuffTool.static.title = 'More stuff';
  94  *     StuffTool.prototype.onSelect = function () {
  95  *         $area.text( 'More stuff tool clicked!' );
  96  *         this.setActive( false );
  97  *     };
  98  *     StuffTool.prototype.onUpdateState = function () {};
  99  *     toolFactory.register( StuffTool );
 100  *
 101  *     // This is a PopupTool. Rather than having a custom 'onSelect' action, it will display a
 102  *     // little popup window (a PopupWidget).
 103  *     function HelpTool( toolGroup, config ) {
 104  *         OO.ui.PopupTool.call( this, toolGroup, $.extend( { popup: {
 105  *             padded: true,
 106  *             label: 'Help',
 107  *             head: true
 108  *         } }, config ) );
 109  *         this.popup.$body.append( '<p>I am helpful!</p>' );
 110  *     }
 111  *     OO.inheritClass( HelpTool, OO.ui.PopupTool );
 112  *     HelpTool.static.name = 'help';
 113  *     HelpTool.static.icon = 'help';
 114  *     HelpTool.static.title = 'Help';
 115  *     toolFactory.register( HelpTool );
 116  *
 117  *     // Finally define which tools and in what order appear in the toolbar. Each tool may only be
 118  *     // used once (but not all defined tools must be used).
 119  *     toolbar.setup( [
 120  *         {
 121  *             // 'bar' tool groups display tools' icons only, side-by-side.
 122  *             type: 'bar',
 123  *             include: [ 'search', 'help' ]
 124  *         },
 125  *         {
 126  *             // 'list' tool groups display both the titles and icons, in a dropdown list.
 127  *             type: 'list',
 128  *             indicator: 'down',
 129  *             label: 'More',
 130  *             include: [ 'settings', 'stuff' ]
 131  *         }
 132  *         // Note how the tools themselves are toolgroup-agnostic - the same tool can be displayed
 133  *         // either in a 'list' or a 'bar'. There is a 'menu' tool group too, not showcased here,
 134  *         // since it's more complicated to use. (See the next example snippet on this page.)
 135  *     ] );
 136  *
 137  *     // Create some UI around the toolbar and place it in the document
 138  *     var frame = new OO.ui.PanelLayout( {
 139  *         expanded: false,
 140  *         framed: true
 141  *     } );
 142  *     var contentFrame = new OO.ui.PanelLayout( {
 143  *         expanded: false,
 144  *         padded: true
 145  *     } );
 146  *     frame.$element.append(
 147  *         toolbar.$element,
 148  *         contentFrame.$element.append( $area )
 149  *     );
 150  *     $( document.body ).append( frame.$element );
 151  *
 152  *     // Here is where the toolbar is actually built. This must be done after inserting it into the
 153  *     // document.
 154  *     toolbar.initialize();
 155  *     toolbar.emit( 'updateState' );
 156  *
 157  * The following example extends the previous one to illustrate 'menu' toolgroups and the usage of
 158  * {@link #event-updateState 'updateState' event}.
 159  *
 160  *     @example
 161  *     // Create the toolbar
 162  *     var toolFactory = new OO.ui.ToolFactory();
 163  *     var toolGroupFactory = new OO.ui.ToolGroupFactory();
 164  *     var toolbar = new OO.ui.Toolbar( toolFactory, toolGroupFactory );
 165  *
 166  *     // We will be placing status text in this element when tools are used
 167  *     var $area = $( '<p>' ).text( 'Toolbar example' );
 168  *
 169  *     // Define the tools that we're going to place in our toolbar
 170  *
 171  *     // Create a class inheriting from OO.ui.Tool
 172  *     function SearchTool() {
 173  *         SearchTool.parent.apply( this, arguments );
 174  *     }
 175  *     OO.inheritClass( SearchTool, OO.ui.Tool );
 176  *     // Each tool must have a 'name' (used as an internal identifier, see later) and at least one
 177  *     // of 'icon' and 'title' (displayed icon and text).
 178  *     SearchTool.static.name = 'search';
 179  *     SearchTool.static.icon = 'search';
 180  *     SearchTool.static.title = 'Search...';
 181  *     // Defines the action that will happen when this tool is selected (clicked).
 182  *     SearchTool.prototype.onSelect = function () {
 183  *         $area.text( 'Search tool clicked!' );
 184  *         // Never display this tool as "active" (selected).
 185  *         this.setActive( false );
 186  *     };
 187  *     SearchTool.prototype.onUpdateState = function () {};
 188  *     // Make this tool available in our toolFactory and thus our toolbar
 189  *     toolFactory.register( SearchTool );
 190  *
 191  *     // Register two more tools, nothing interesting here
 192  *     function SettingsTool() {
 193  *         SettingsTool.parent.apply( this, arguments );
 194  *         this.reallyActive = false;
 195  *     }
 196  *     OO.inheritClass( SettingsTool, OO.ui.Tool );
 197  *     SettingsTool.static.name = 'settings';
 198  *     SettingsTool.static.icon = 'settings';
 199  *     SettingsTool.static.title = 'Change settings';
 200  *     SettingsTool.prototype.onSelect = function () {
 201  *         $area.text( 'Settings tool clicked!' );
 202  *         // Toggle the active state on each click
 203  *         this.reallyActive = !this.reallyActive;
 204  *         this.setActive( this.reallyActive );
 205  *         // To update the menu label
 206  *         this.toolbar.emit( 'updateState' );
 207  *     };
 208  *     SettingsTool.prototype.onUpdateState = function () {};
 209  *     toolFactory.register( SettingsTool );
 210  *
 211  *     // Register two more tools, nothing interesting here
 212  *     function StuffTool() {
 213  *         StuffTool.parent.apply( this, arguments );
 214  *         this.reallyActive = false;
 215  *     }
 216  *     OO.inheritClass( StuffTool, OO.ui.Tool );
 217  *     StuffTool.static.name = 'stuff';
 218  *     StuffTool.static.icon = 'ellipsis';
 219  *     StuffTool.static.title = 'More stuff';
 220  *     StuffTool.prototype.onSelect = function () {
 221  *         $area.text( 'More stuff tool clicked!' );
 222  *         // Toggle the active state on each click
 223  *         this.reallyActive = !this.reallyActive;
 224  *         this.setActive( this.reallyActive );
 225  *         // To update the menu label
 226  *         this.toolbar.emit( 'updateState' );
 227  *     };
 228  *     StuffTool.prototype.onUpdateState = function () {};
 229  *     toolFactory.register( StuffTool );
 230  *
 231  *     // This is a PopupTool. Rather than having a custom 'onSelect' action, it will display a
 232  *     // little popup window (a PopupWidget). 'onUpdateState' is also already implemented.
 233  *     function HelpTool( toolGroup, config ) {
 234  *         OO.ui.PopupTool.call( this, toolGroup, $.extend( { popup: {
 235  *             padded: true,
 236  *             label: 'Help',
 237  *             head: true
 238  *         } }, config ) );
 239  *         this.popup.$body.append( '<p>I am helpful!</p>' );
 240  *     }
 241  *     OO.inheritClass( HelpTool, OO.ui.PopupTool );
 242  *     HelpTool.static.name = 'help';
 243  *     HelpTool.static.icon = 'help';
 244  *     HelpTool.static.title = 'Help';
 245  *     toolFactory.register( HelpTool );
 246  *
 247  *     // Finally define which tools and in what order appear in the toolbar. Each tool may only be
 248  *     // used once (but not all defined tools must be used).
 249  *     toolbar.setup( [
 250  *         {
 251  *             // 'bar' tool groups display tools' icons only, side-by-side.
 252  *             type: 'bar',
 253  *             include: [ 'search', 'help' ]
 254  *         },
 255  *         {
 256  *             // 'menu' tool groups display both the titles and icons, in a dropdown menu.
 257  *             // Menu label indicates which items are selected.
 258  *             type: 'menu',
 259  *             indicator: 'down',
 260  *             include: [ 'settings', 'stuff' ]
 261  *         }
 262  *     ] );
 263  *
 264  *     // Create some UI around the toolbar and place it in the document
 265  *     var frame = new OO.ui.PanelLayout( {
 266  *         expanded: false,
 267  *         framed: true
 268  *     } );
 269  *     var contentFrame = new OO.ui.PanelLayout( {
 270  *         expanded: false,
 271  *         padded: true
 272  *     } );
 273  *     frame.$element.append(
 274  *         toolbar.$element,
 275  *         contentFrame.$element.append( $area )
 276  *     );
 277  *     $( document.body ).append( frame.$element );
 278  *
 279  *     // Here is where the toolbar is actually built. This must be done after inserting it into the
 280  *     // document.
 281  *     toolbar.initialize();
 282  *     toolbar.emit( 'updateState' );
 283  *
 284  * @class
 285  * @extends OO.ui.Element
 286  * @mixins OO.EventEmitter
 287  * @mixins OO.ui.mixin.GroupElement
 288  *
 289  * @constructor
 290  * @param {OO.ui.ToolFactory} toolFactory Factory for creating tools
 291  * @param {OO.ui.ToolGroupFactory} toolGroupFactory Factory for creating toolgroups
 292  * @param {Object} [config] Configuration options
 293  * @cfg {boolean} [actions] Add an actions section to the toolbar. Actions are commands that are
 294  *  included in the toolbar, but are not configured as tools. By default, actions are displayed on
 295  *  the right side of the toolbar.
 296  * @cfg {string} [position='top'] Whether the toolbar is positioned above ('top') or below
 297  *  ('bottom') content.
 298  * @cfg {jQuery} [$overlay] An overlay for the popup.
 299  *  See <https://www.mediawiki.org/wiki/OOUI/Concepts#Overlays>.
 300  */
 301 OO.ui.Toolbar = function OoUiToolbar( toolFactory, toolGroupFactory, config ) {
 302         // Allow passing positional parameters inside the config object
 303         if ( OO.isPlainObject( toolFactory ) && config === undefined ) {
 304                 config = toolFactory;
 305                 toolFactory = config.toolFactory;
 306                 toolGroupFactory = config.toolGroupFactory;
 307         }
 308
 309         // Configuration initialization
 310         config = config || {};
 311
 312         // Parent constructor
 313         OO.ui.Toolbar.parent.call( this, config );
 314
 315         // Mixin constructors
 316         OO.EventEmitter.call( this );
 317         OO.ui.mixin.GroupElement.call( this, config );
 318
 319         // Properties
 320         this.toolFactory = toolFactory;
 321         this.toolGroupFactory = toolGroupFactory;
 322         this.groupsByName = {};
 323         this.activeToolGroups = 0;
 324         this.tools = {};
 325         this.position = config.position || 'top';
 326         this.$bar = $( '<div>' );
 327         this.$actions = $( '<div>' );
 328         this.$popups = $( '<div>' );
 329         this.initialized = false;
 330         this.narrowThreshold = null;
 331         this.onWindowResizeHandler = this.onWindowResize.bind( this );
 332         this.$overlay = ( config.$overlay === true ? OO.ui.getDefaultOverlay() : config.$overlay ) ||
 333                 this.$element;
 334
 335         // Events
 336         this.$element
 337                 .add( this.$bar ).add( this.$group ).add( this.$actions )
 338                 .on( 'mousedown keydown', this.onPointerDown.bind( this ) );
 339
 340         // Initialization
 341         this.$group.addClass( 'oo-ui-toolbar-tools' );
 342         if ( config.actions ) {
 343                 this.$bar.append( this.$actions.addClass( 'oo-ui-toolbar-actions' ) );
 344         }
 345         this.$popups.addClass( 'oo-ui-toolbar-popups' );
 346         this.$bar
 347                 .addClass( 'oo-ui-toolbar-bar' )
 348                 .append( this.$group, '<div style="clear:both"></div>' );
 349         // Possible classes: oo-ui-toolbar-position-top, oo-ui-toolbar-position-bottom
 350         this.$element
 351                 .addClass( 'oo-ui-toolbar oo-ui-toolbar-position-' + this.position )
 352                 .append( this.$bar );
 353         this.$overlay.append( this.$popups );
 354 };
 355
 356 /* Setup */
 357
 358 OO.inheritClass( OO.ui.Toolbar, OO.ui.Element );
 359 OO.mixinClass( OO.ui.Toolbar, OO.EventEmitter );
 360 OO.mixinClass( OO.ui.Toolbar, OO.ui.mixin.GroupElement );
 361
 362 /* Events */
 363
 364 /**
 365  * @event updateState
 366  *
 367  * An 'updateState' event must be emitted on the Toolbar (by calling
 368  * `toolbar.emit( 'updateState' )`) every time the state of the application using the toolbar
 369  * changes, and an update to the state of tools is required.
 370  *
 371  * @param {...Mixed} data Application-defined parameters
 372  */
 373
 374 /**
 375  * @event active
 376  *
 377  * An 'active' event is emitted when the number of active toolgroups increases from 0, or
 378  * returns to 0.
 379  *
 380  * @param {boolean} There are active toolgroups in this toolbar
 381  */
 382
 383 /* Methods */
 384
 385 /**
 386  * Get the tool factory.
 387  *
 388  * @return {OO.ui.ToolFactory} Tool factory
 389  */
 390 OO.ui.Toolbar.prototype.getToolFactory = function () {
 391         return this.toolFactory;
 392 };
 393
 394 /**
 395  * Get the toolgroup factory.
 396  *
 397  * @return {OO.Factory} Toolgroup factory
 398  */
 399 OO.ui.Toolbar.prototype.getToolGroupFactory = function () {
 400         return this.toolGroupFactory;
 401 };
 402
 403 /**
 404  * Handles mouse down events.
 405  *
 406  * @private
 407  * @param {jQuery.Event} e Mouse down event
 408  * @return {undefined/boolean} False to prevent default if event is handled
 409  */
 410 OO.ui.Toolbar.prototype.onPointerDown = function ( e ) {
 411         var $closestWidgetToEvent = $( e.target ).closest( '.oo-ui-widget' ),
 412                 $closestWidgetToToolbar = this.$element.closest( '.oo-ui-widget' );
 413         if (
 414                 !$closestWidgetToEvent.length ||
 415                 $closestWidgetToEvent[ 0 ] ===
 416                 $closestWidgetToToolbar[ 0 ]
 417         ) {
 418                 return false;
 419         }
 420 };
 421
 422 /**
 423  * Handle window resize event.
 424  *
 425  * @private
 426  * @param {jQuery.Event} e Window resize event
 427  */
 428 OO.ui.Toolbar.prototype.onWindowResize = function () {
 429         this.$element.add( this.$popups ).toggleClass(
 430                 'oo-ui-toolbar-narrow',
 431                 this.$bar[ 0 ].clientWidth <= this.getNarrowThreshold()
 432         );
 433 };
 434
 435 /**
 436  * Get the (lazily-computed) width threshold for applying the oo-ui-toolbar-narrow
 437  * class.
 438  *
 439  * @private
 440  * @return {number} Width threshold in pixels
 441  */
 442 OO.ui.Toolbar.prototype.getNarrowThreshold = function () {
 443         if ( this.narrowThreshold === null ) {
 444                 this.narrowThreshold = this.$group[ 0 ].offsetWidth + this.$actions[ 0 ].offsetWidth;
 445         }
 446         return this.narrowThreshold;
 447 };
 448
 449 /**
 450  * Sets up handles and preloads required information for the toolbar to work.
 451  * This must be called after it is attached to a visible document and before doing anything else.
 452  */
 453 OO.ui.Toolbar.prototype.initialize = function () {
 454         if ( !this.initialized ) {
 455                 this.initialized = true;
 456                 $( this.getElementWindow() ).on( 'resize', this.onWindowResizeHandler );
 457                 this.onWindowResize();
 458         }
 459 };
 460
 461 /**
 462  * Set up the toolbar.
 463  *
 464  * The toolbar is set up with a list of toolgroup configurations that specify the type of
 465  * toolgroup ({@link OO.ui.BarToolGroup bar}, {@link OO.ui.MenuToolGroup menu}, or
 466  * {@link OO.ui.ListToolGroup list}) to add and which tools to include, exclude, promote, or demote
 467  * within that toolgroup. Please see {@link OO.ui.ToolGroup toolgroups} for more information about
 468  * including tools in toolgroups.
 469  *
 470  * @param {Object.<string,Array>} groups List of toolgroup configurations
 471  * @param {string} [groups.name] Symbolic name for this toolgroup
 472  * @param {string} [groups.type] Toolgroup type, should exist in the toolgroup factory
 473  * @param {Array|string} [groups.include] Tools to include in the toolgroup
 474  * @param {Array|string} [groups.exclude] Tools to exclude from the toolgroup
 475  * @param {Array|string} [groups.promote] Tools to promote to the beginning of the toolgroup
 476  * @param {Array|string} [groups.demote] Tools to demote to the end of the toolgroup
 477  */
 478 OO.ui.Toolbar.prototype.setup = function ( groups ) {
 479         var i, len, type, toolGroup, groupConfig,
 480                 items = [],
 481                 defaultType = 'bar';
 482
 483         // Cleanup previous groups
 484         this.reset();
 485
 486         // Build out new groups
 487         for ( i = 0, len = groups.length; i < len; i++ ) {
 488                 groupConfig = groups[ i ];
 489                 if ( groupConfig.include === '*' ) {
 490                         // Apply defaults to catch-all groups
 491                         if ( groupConfig.type === undefined ) {
 492                                 groupConfig.type = 'list';
 493                         }
 494                         if ( groupConfig.label === undefined ) {
 495                                 groupConfig.label = OO.ui.msg( 'ooui-toolbar-more' );
 496                         }
 497                 }
 498                 // Check type has been registered
 499                 type = this.getToolGroupFactory().lookup( groupConfig.type ) ?
 500                         groupConfig.type : defaultType;
 501                 toolGroup = this.getToolGroupFactory().create( type, this, groupConfig );
 502                 items.push( toolGroup );
 503                 if ( groupConfig.name ) {
 504                         this.groupsByName[ groupConfig.name ] = toolGroup;
 505                 } else {
 506                         // Groups without name are deprecated
 507                         OO.ui.warnDeprecation( 'Toolgroups must have a \'name\' property' );
 508                 }
 509                 toolGroup.connect( this, {
 510                         active: 'onToolGroupActive'
 511                 } );
 512         }
 513         this.addItems( items );
 514 };
 515
 516 /**
 517  * Handle active events from tool groups
 518  *
 519  * @param {boolean} active Tool group has become active, inactive if false
 520  * @fires active
 521  */
 522 OO.ui.Toolbar.prototype.onToolGroupActive = function ( active ) {
 523         if ( active ) {
 524                 this.activeToolGroups++;
 525                 if ( this.activeToolGroups === 1 ) {
 526                         this.emit( 'active', true );
 527                 }
 528         } else {
 529                 this.activeToolGroups--;
 530                 if ( this.activeToolGroups === 0 ) {
 531                         this.emit( 'active', false );
 532                 }
 533         }
 534 };
 535
 536 /**
 537  * Get a toolgroup by name
 538  *
 539  * @param {string} name Group name
 540  * @return {OO.ui.ToolGroup|null} Tool group, or null if none found by that name
 541  */
 542 OO.ui.Toolbar.prototype.getToolGroupByName = function ( name ) {
 543         return this.groupsByName[ name ] || null;
 544 };
 545
 546 /**
 547  * Remove all tools and toolgroups from the toolbar.
 548  */
 549 OO.ui.Toolbar.prototype.reset = function () {
 550         var i, len;
 551
 552         this.groupsByName = {};
 553         this.tools = {};
 554         for ( i = 0, len = this.items.length; i < len; i++ ) {
 555                 this.items[ i ].destroy();
 556         }
 557         this.clearItems();
 558 };
 559
 560 /**
 561  * Destroy the toolbar.
 562  *
 563  * Destroying the toolbar removes all event handlers and DOM elements that constitute the toolbar.
 564  * Call this method whenever you are done using a toolbar.
 565  */
 566 OO.ui.Toolbar.prototype.destroy = function () {
 567         $( this.getElementWindow() ).off( 'resize', this.onWindowResizeHandler );
 568         this.reset();
 569         this.$element.remove();
 570 };
 571
 572 /**
 573  * Check if the tool is available.
 574  *
 575  * Available tools are ones that have not yet been added to the toolbar.
 576  *
 577  * @param {string} name Symbolic name of tool
 578  * @return {boolean} Tool is available
 579  */
 580 OO.ui.Toolbar.prototype.isToolAvailable = function ( name ) {
 581         return !this.tools[ name ];
 582 };
 583
 584 /**
 585  * Prevent tool from being used again.
 586  *
 587  * @param {OO.ui.Tool} tool Tool to reserve
 588  */
 589 OO.ui.Toolbar.prototype.reserveTool = function ( tool ) {
 590         this.tools[ tool.getName() ] = tool;
 591 };
 592
 593 /**
 594  * Allow tool to be used again.
 595  *
 596  * @param {OO.ui.Tool} tool Tool to release
 597  */
 598 OO.ui.Toolbar.prototype.releaseTool = function ( tool ) {
 599         delete this.tools[ tool.getName() ];
 600 };
 601
 602 /**
 603  * Get accelerator label for tool.
 604  *
 605  * The OOUI library does not contain an accelerator system, but this is the hook for one. To
 606  * use an accelerator system, subclass the toolbar and override this method, which is meant to
 607  * return a label that describes the accelerator keys for the tool passed (by symbolic name) to
 608  * the method.
 609  *
 610  * @param {string} name Symbolic name of tool
 611  * @return {string|undefined} Tool accelerator label if available
 612  */
 613 OO.ui.Toolbar.prototype.getToolAccelerator = function () {
 614         return undefined;
 615 };
 616
 617 /**
 618  * Tools, together with {@link OO.ui.ToolGroup toolgroups}, constitute
 619  * {@link OO.ui.Toolbar toolbars}.
 620  * Each tool is configured with a static name, title, and icon and is customized with the command
 621  * to carry out when the tool is selected. Tools must also be registered with a
 622  * {@link OO.ui.ToolFactory tool factory}, which creates the tools on demand.
 623  *
 624  * Every Tool subclass must implement two methods:
 625  *
 626  * - {@link #onUpdateState}
 627  * - {@link #onSelect}
 628  *
 629  * Tools are added to toolgroups ({@link OO.ui.ListToolGroup ListToolGroup},
 630  * {@link OO.ui.BarToolGroup BarToolGroup}, or {@link OO.ui.MenuToolGroup MenuToolGroup}), which
 631  * determine how the tool is displayed in the toolbar. See {@link OO.ui.Toolbar toolbars} for an
 632  * example.
 633  *
 634  * For more information, please see the [OOUI documentation on MediaWiki][1].
 635  * [1]: https://www.mediawiki.org/wiki/OOUI/Toolbars
 636  *
 637  * @abstract
 638  * @class
 639  * @extends OO.ui.Widget
 640  * @mixins OO.ui.mixin.IconElement
 641  * @mixins OO.ui.mixin.FlaggedElement
 642  * @mixins OO.ui.mixin.TabIndexedElement
 643  *
 644  * @constructor
 645  * @param {OO.ui.ToolGroup} toolGroup
 646  * @param {Object} [config] Configuration options
 647  * @cfg {string|Function} [title] Title text or a function that returns text. If this config is
 648  *  omitted, the value of the {@link #static-title static title} property is used.
 649  *
 650  *  The title is used in different ways depending on the type of toolgroup that contains the tool.
 651  *  The title is used as a tooltip if the tool is part of a {@link OO.ui.BarToolGroup bar}
 652  *  toolgroup, or as the label text if the tool is part of a {@link OO.ui.ListToolGroup list} or
 653  *  {@link OO.ui.MenuToolGroup menu} toolgroup.
 654  *
 655  *  For bar toolgroups, a description of the accelerator key is appended to the title if an
 656  *  accelerator key is associated with an action by the same name as the tool and accelerator
 657  *  functionality has been added to the application.
 658  *  To add accelerator key functionality, you must subclass OO.ui.Toolbar and override the
 659  *  {@link OO.ui.Toolbar#getToolAccelerator getToolAccelerator} method.
 660  */
 661 OO.ui.Tool = function OoUiTool( toolGroup, config ) {
 662         // Allow passing positional parameters inside the config object
 663         if ( OO.isPlainObject( toolGroup ) && config === undefined ) {
 664                 config = toolGroup;
 665                 toolGroup = config.toolGroup;
 666         }
 667
 668         // Configuration initialization
 669         config = config || {};
 670
 671         // Parent constructor
 672         OO.ui.Tool.parent.call( this, config );
 673
 674         // Properties
 675         this.toolGroup = toolGroup;
 676         this.toolbar = this.toolGroup.getToolbar();
 677         this.active = false;
 678         this.$title = $( '<span>' );
 679         this.$accel = $( '<span>' );
 680         this.$link = $( '<a>' );
 681         this.title = null;
 682         this.checkIcon = new OO.ui.IconWidget( {
 683                 icon: 'check',
 684                 classes: [ 'oo-ui-tool-checkIcon' ]
 685         } );
 686
 687         // Mixin constructors
 688         OO.ui.mixin.IconElement.call( this, config );
 689         OO.ui.mixin.FlaggedElement.call( this, config );
 690         OO.ui.mixin.TabIndexedElement.call( this, $.extend( {
 691                 $tabIndexed: this.$link
 692         }, config ) );
 693
 694         // Events
 695         this.toolbar.connect( this, {
 696                 updateState: 'onUpdateState'
 697         } );
 698
 699         // Initialization
 700         this.$title.addClass( 'oo-ui-tool-title' );
 701         this.$accel
 702                 .addClass( 'oo-ui-tool-accel' )
 703                 .prop( {
 704                         // This may need to be changed if the key names are ever localized,
 705                         // but for now they are essentially written in English
 706                         dir: 'ltr',
 707                         lang: 'en'
 708                 } );
 709         this.$link
 710                 .addClass( 'oo-ui-tool-link' )
 711                 .append( this.checkIcon.$element, this.$icon, this.$title, this.$accel )
 712                 .attr( 'role', 'button' );
 713         this.$element
 714                 .data( 'oo-ui-tool', this )
 715                 .addClass( 'oo-ui-tool' )
 716                 .addClass( 'oo-ui-tool-name-' +
 717                         this.constructor.static.name.replace( /^([^/]+)\/([^/]+).*$/, '$1-$2' ) )
 718                 .toggleClass( 'oo-ui-tool-with-label', this.constructor.static.displayBothIconAndLabel )
 719                 .append( this.$link );
 720         this.setTitle( config.title || this.constructor.static.title );
 721 };
 722
 723 /* Setup */
 724
 725 OO.inheritClass( OO.ui.Tool, OO.ui.Widget );
 726 OO.mixinClass( OO.ui.Tool, OO.ui.mixin.IconElement );
 727 OO.mixinClass( OO.ui.Tool, OO.ui.mixin.FlaggedElement );
 728 OO.mixinClass( OO.ui.Tool, OO.ui.mixin.TabIndexedElement );
 729
 730 /* Static Properties */
 731
 732 /**
 733  * @static
 734  * @inheritdoc
 735  */
 736 OO.ui.Tool.static.tagName = 'span';
 737
 738 /**
 739  * Symbolic name of tool.
 740  *
 741  * The symbolic name is used internally to register the tool with a
 742  * {@link OO.ui.ToolFactory ToolFactory}. It can also be used when adding tools to toolgroups.
 743  *
 744  * @abstract
 745  * @static
 746  * @inheritable
 747  * @property {string}
 748  */
 749 OO.ui.Tool.static.name = '';
 750
 751 /**
 752  * Symbolic name of the group.
 753  *
 754  * The group name is used to associate tools with each other so that they can be selected later by
 755  * a {@link OO.ui.ToolGroup toolgroup}.
 756  *
 757  * @abstract
 758  * @static
 759  * @inheritable
 760  * @property {string}
 761  */
 762 OO.ui.Tool.static.group = '';
 763
 764 /**
 765  * Tool title text or a function that returns title text. The value of the static property is
 766  * overridden if the #title config option is used.
 767  *
 768  * @abstract
 769  * @static
 770  * @inheritable
 771  * @property {string|Function}
 772  */
 773 OO.ui.Tool.static.title = '';
 774
 775 /**
 776  * Display both icon and label when the tool is used in a {@link OO.ui.BarToolGroup bar} toolgroup.
 777  * Normally only the icon is displayed, or only the label if no icon is given.
 778  *
 779  * @static
 780  * @inheritable
 781  * @property {boolean}
 782  */
 783 OO.ui.Tool.static.displayBothIconAndLabel = false;
 784
 785 /**
 786  * Add tool to catch-all groups automatically.
 787  *
 788  * A catch-all group, which contains all tools that do not currently belong to a toolgroup,
 789  * can be included in a toolgroup using the wildcard selector, an asterisk (*).
 790  *
 791  * @static
 792  * @inheritable
 793  * @property {boolean}
 794  */
 795 OO.ui.Tool.static.autoAddToCatchall = true;
 796
 797 /**
 798  * Add tool to named groups automatically.
 799  *
 800  * By default, tools that are configured with a static ‘group’ property are added
 801  * to that group and will be selected when the symbolic name of the group is specified (e.g., when
 802  * toolgroups include tools by group name).
 803  *
 804  * @static
 805  * @property {boolean}
 806  * @inheritable
 807  */
 808 OO.ui.Tool.static.autoAddToGroup = true;
 809
 810 /**
 811  * Check if this tool is compatible with given data.
 812  *
 813  * This is a stub that can be overridden to provide support for filtering tools based on an
 814  * arbitrary piece of information  (e.g., where the cursor is in a document). The implementation
 815  * must also call this method so that the compatibility check can be performed.
 816  *
 817  * @static
 818  * @inheritable
 819  * @param {Mixed} data Data to check
 820  * @return {boolean} Tool can be used with data
 821  */
 822 OO.ui.Tool.static.isCompatibleWith = function () {
 823         return false;
 824 };
 825
 826 /* Methods */
 827
 828 /**
 829  * Handle the toolbar state being updated. This method is called when the
 830  * {@link OO.ui.Toolbar#event-updateState 'updateState' event} is emitted on the
 831  * {@link OO.ui.Toolbar Toolbar} that uses this tool, and should set the state of this tool
 832  * depending on application state (usually by calling #setDisabled to enable or disable the tool,
 833  * or #setActive to mark is as currently in-use or not).
 834  *
 835  * This is an abstract method that must be overridden in a concrete subclass.
 836  *
 837  * @method
 838  * @protected
 839  * @abstract
 840  */
 841 OO.ui.Tool.prototype.onUpdateState = null;
 842
 843 /**
 844  * Handle the tool being selected. This method is called when the user triggers this tool,
 845  * usually by clicking on its label/icon.
 846  *
 847  * This is an abstract method that must be overridden in a concrete subclass.
 848  *
 849  * @method
 850  * @protected
 851  * @abstract
 852  */
 853 OO.ui.Tool.prototype.onSelect = null;
 854
 855 /**
 856  * Check if the tool is active.
 857  *
 858  * Tools become active when their #onSelect or #onUpdateState handlers change them to appear pressed
 859  * with the #setActive method. Additional CSS is applied to the tool to reflect the active state.
 860  *
 861  * @return {boolean} Tool is active
 862  */
 863 OO.ui.Tool.prototype.isActive = function () {
 864         return this.active;
 865 };
 866
 867 /**
 868  * Make the tool appear active or inactive.
 869  *
 870  * This method should be called within #onSelect or #onUpdateState event handlers to make the tool
 871  * appear pressed or not.
 872  *
 873  * @param {boolean} state Make tool appear active
 874  */
 875 OO.ui.Tool.prototype.setActive = function ( state ) {
 876         this.active = !!state;
 877         this.$element.toggleClass( 'oo-ui-tool-active', this.active );
 878         this.updateThemeClasses();
 879 };
 880
 881 /**
 882  * Set the tool #title.
 883  *
 884  * @param {string|Function} title Title text or a function that returns text
 885  * @chainable
 886  * @return {OO.ui.Tool} The tool, for chaining
 887  */
 888 OO.ui.Tool.prototype.setTitle = function ( title ) {
 889         this.title = OO.ui.resolveMsg( title );
 890         this.updateTitle();
 891         return this;
 892 };
 893
 894 /**
 895  * Get the tool #title.
 896  *
 897  * @return {string} Title text
 898  */
 899 OO.ui.Tool.prototype.getTitle = function () {
 900         return this.title;
 901 };
 902
 903 /**
 904  * Get the tool's symbolic name.
 905  *
 906  * @return {string} Symbolic name of tool
 907  */
 908 OO.ui.Tool.prototype.getName = function () {
 909         return this.constructor.static.name;
 910 };
 911
 912 /**
 913  * Update the title.
 914  */
 915 OO.ui.Tool.prototype.updateTitle = function () {
 916         var titleTooltips = this.toolGroup.constructor.static.titleTooltips,
 917                 accelTooltips = this.toolGroup.constructor.static.accelTooltips,
 918                 accel = this.toolbar.getToolAccelerator( this.constructor.static.name ),
 919                 tooltipParts = [];
 920
 921         this.$title.text( this.title );
 922         this.$accel.text( accel );
 923
 924         if ( titleTooltips && typeof this.title === 'string' && this.title.length ) {
 925                 tooltipParts.push( this.title );
 926         }
 927         if ( accelTooltips && typeof accel === 'string' && accel.length ) {
 928                 tooltipParts.push( accel );
 929         }
 930         if ( tooltipParts.length ) {
 931                 this.$link.attr( 'title', tooltipParts.join( ' ' ) );
 932         } else {
 933                 this.$link.removeAttr( 'title' );
 934         }
 935 };
 936
 937 /**
 938  * Destroy tool.
 939  *
 940  * Destroying the tool removes all event handlers and the tool’s DOM elements.
 941  * Call this method whenever you are done using a tool.
 942  */
 943 OO.ui.Tool.prototype.destroy = function () {
 944         this.toolbar.disconnect( this );
 945         this.$element.remove();
 946 };
 947
 948 /**
 949  * ToolGroups are collections of {@link OO.ui.Tool tools} that are used in a
 950  * {@link OO.ui.Toolbar toolbar}.
 951  * The type of toolgroup ({@link OO.ui.ListToolGroup list}, {@link OO.ui.BarToolGroup bar}, or
 952  * {@link OO.ui.MenuToolGroup menu}) to which a tool belongs determines how the tool is arranged
 953  * and displayed in the toolbar. Toolgroups themselves are created on demand with a
 954  * {@link OO.ui.ToolGroupFactory toolgroup factory}.
 955  *
 956  * Toolgroups can contain individual tools, groups of tools, or all available tools, as specified
 957  * using the `include` config option. See OO.ui.ToolFactory#extract on documentation of the format.
 958  * The options `exclude`, `promote`, and `demote` support the same formats.
 959  *
 960  * See {@link OO.ui.Toolbar toolbars} for a full example. For more information about toolbars in
 961  * general, please see the [OOUI documentation on MediaWiki][1].
 962  *
 963  * [1]: https://www.mediawiki.org/wiki/OOUI/Toolbars
 964  *
 965  * @abstract
 966  * @class
 967  * @extends OO.ui.Widget
 968  * @mixins OO.ui.mixin.GroupElement
 969  *
 970  * @constructor
 971  * @param {OO.ui.Toolbar} toolbar
 972  * @param {Object} [config] Configuration options
 973  * @cfg {Array|string} [include] List of tools to include in the toolgroup, see above.
 974  * @cfg {Array|string} [exclude] List of tools to exclude from the toolgroup, see above.
 975  * @cfg {Array|string} [promote] List of tools to promote to the beginning of the toolgroup,
 976  *  see above.
 977  * @cfg {Array|string} [demote] List of tools to demote to the end of the toolgroup, see above.
 978  *  This setting is particularly useful when tools have been added to the toolgroup
 979  *  en masse (e.g., via the catch-all selector).
 980  */
 981 OO.ui.ToolGroup = function OoUiToolGroup( toolbar, config ) {
 982         // Allow passing positional parameters inside the config object
 983         if ( OO.isPlainObject( toolbar ) && config === undefined ) {
 984                 config = toolbar;
 985                 toolbar = config.toolbar;
 986         }
 987
 988         // Configuration initialization
 989         config = config || {};
 990
 991         // Parent constructor
 992         OO.ui.ToolGroup.parent.call( this, config );
 993
 994         // Mixin constructors
 995         OO.ui.mixin.GroupElement.call( this, config );
 996
 997         // Properties
 998         this.toolbar = toolbar;
 999         this.tools = {};
1000         this.pressed = null;
1001         this.autoDisabled = false;
1002         this.include = config.include || [];
1003         this.exclude = config.exclude || [];
1004         this.promote = config.promote || [];
1005         this.demote = config.demote || [];
1006         this.onDocumentMouseKeyUpHandler = this.onDocumentMouseKeyUp.bind( this );
1007
1008         // Events
1009         this.$group.on( {
1010                 mousedown: this.onMouseKeyDown.bind( this ),
1011                 mouseup: this.onMouseKeyUp.bind( this ),
1012                 keydown: this.onMouseKeyDown.bind( this ),
1013                 keyup: this.onMouseKeyUp.bind( this ),
1014                 focus: this.onMouseOverFocus.bind( this ),
1015                 blur: this.onMouseOutBlur.bind( this ),
1016                 mouseover: this.onMouseOverFocus.bind( this ),
1017                 mouseout: this.onMouseOutBlur.bind( this )
1018         } );
1019         this.toolbar.getToolFactory().connect( this, {
1020                 register: 'onToolFactoryRegister'
1021         } );
1022         this.aggregate( {
1023                 disable: 'itemDisable'
1024         } );
1025         this.connect( this, {
1026                 itemDisable: 'updateDisabled',
1027                 disable: 'onDisable'
1028         } );
1029
1030         // Initialization
1031         this.$group.addClass( 'oo-ui-toolGroup-tools' );
1032         this.$element
1033                 .addClass( 'oo-ui-toolGroup' )
1034                 .append( this.$group );
1035         this.onDisable( this.isDisabled() );
1036         this.populate();
1037 };
1038
1039 /* Setup */
1040
1041 OO.inheritClass( OO.ui.ToolGroup, OO.ui.Widget );
1042 OO.mixinClass( OO.ui.ToolGroup, OO.ui.mixin.GroupElement );
1043
1044 /* Events */
1045
1046 /**
1047  * @event update
1048  */
1049
1050 /**
1051  * @event active
1052  *
1053  * An 'active' event is emitted when any popup is shown/hidden.
1054  *
1055  * @param {boolean} The popup is visible
1056  */
1057
1058 /* Static Properties */
1059
1060 /**
1061  * Show labels in tooltips.
1062  *
1063  * @static
1064  * @inheritable
1065  * @property {boolean}
1066  */
1067 OO.ui.ToolGroup.static.titleTooltips = false;
1068
1069 /**
1070  * Show acceleration labels in tooltips.
1071  *
1072  * Note: The OOUI library does not include an accelerator system, but does contain
1073  * a hook for one. To use an accelerator system, subclass the {@link OO.ui.Toolbar toolbar} and
1074  * override the {@link OO.ui.Toolbar#getToolAccelerator getToolAccelerator} method, which is
1075  * meant to return a label that describes the accelerator keys for a given tool (e.g., Control+M
1076  * key combination).
1077  *
1078  * @static
1079  * @inheritable
1080  * @property {boolean}
1081  */
1082 OO.ui.ToolGroup.static.accelTooltips = false;
1083
1084 /**
1085  * Automatically disable the toolgroup when all tools are disabled
1086  *
1087  * @static
1088  * @inheritable
1089  * @property {boolean}
1090  */
1091 OO.ui.ToolGroup.static.autoDisable = true;
1092
1093 /**
1094  * @abstract
1095  * @static
1096  * @inheritable
1097  * @property {string}
1098  */
1099 OO.ui.ToolGroup.static.name = null;
1100
1101 /* Methods */
1102
1103 /**
1104  * @inheritdoc
1105  */
1106 OO.ui.ToolGroup.prototype.isDisabled = function () {
1107         return this.autoDisabled ||
1108                 OO.ui.ToolGroup.parent.prototype.isDisabled.apply( this, arguments );
1109 };
1110
1111 /**
1112  * @inheritdoc
1113  */
1114 OO.ui.ToolGroup.prototype.updateDisabled = function () {
1115         var i, item, allDisabled = true;
1116
1117         if ( this.constructor.static.autoDisable ) {
1118                 for ( i = this.items.length - 1; i >= 0; i-- ) {
1119                         item = this.items[ i ];
1120                         if ( !item.isDisabled() ) {
1121                                 allDisabled = false;
1122                                 break;
1123                         }
1124                 }
1125                 this.autoDisabled = allDisabled;
1126         }
1127         OO.ui.ToolGroup.parent.prototype.updateDisabled.apply( this, arguments );
1128 };
1129
1130 /**
1131  * Handle disable events.
1132  *
1133  * @protected
1134  * @param {boolean} isDisabled
1135  */
1136 OO.ui.ToolGroup.prototype.onDisable = function ( isDisabled ) {
1137         this.$group.toggleClass( 'oo-ui-toolGroup-disabled-tools', isDisabled );
1138         this.$group.toggleClass( 'oo-ui-toolGroup-enabled-tools', !isDisabled );
1139 };
1140
1141 /**
1142  * Handle mouse down and key down events.
1143  *
1144  * @protected
1145  * @param {jQuery.Event} e Mouse down or key down event
1146  * @return {undefined/boolean} False to prevent default if event is handled
1147  */
1148 OO.ui.ToolGroup.prototype.onMouseKeyDown = function ( e ) {
1149         if (
1150                 !this.isDisabled() && (
1151                         e.which === OO.ui.MouseButtons.LEFT ||
1152                         e.which === OO.ui.Keys.SPACE ||
1153                         e.which === OO.ui.Keys.ENTER
1154                 )
1155         ) {
1156                 this.pressed = this.findTargetTool( e );
1157                 if ( this.pressed ) {
1158                         this.pressed.setActive( true );
1159                         this.getElementDocument().addEventListener(
1160                                 'mouseup',
1161                                 this.onDocumentMouseKeyUpHandler,
1162                                 true
1163                         );
1164                         this.getElementDocument().addEventListener(
1165                                 'keyup',
1166                                 this.onDocumentMouseKeyUpHandler,
1167                                 true
1168                         );
1169                         return false;
1170                 }
1171         }
1172 };
1173
1174 /**
1175  * Handle document mouse up and key up events.
1176  *
1177  * @protected
1178  * @param {MouseEvent|KeyboardEvent} e Mouse up or key up event
1179  */
1180 OO.ui.ToolGroup.prototype.onDocumentMouseKeyUp = function ( e ) {
1181         this.getElementDocument().removeEventListener(
1182                 'mouseup',
1183                 this.onDocumentMouseKeyUpHandler,
1184                 true
1185         );
1186         this.getElementDocument().removeEventListener(
1187                 'keyup',
1188                 this.onDocumentMouseKeyUpHandler,
1189                 true
1190         );
1191         // onMouseKeyUp may be called a second time, depending on where the mouse is when the button is
1192         // released, but since `this.pressed` will no longer be true, the second call will be ignored.
1193         this.onMouseKeyUp( e );
1194 };
1195
1196 /**
1197  * Handle mouse up and key up events.
1198  *
1199  * @protected
1200  * @param {MouseEvent|KeyboardEvent} e Mouse up or key up event
1201  */
1202 OO.ui.ToolGroup.prototype.onMouseKeyUp = function ( e ) {
1203         var tool = this.findTargetTool( e );
1204
1205         if (
1206                 !this.isDisabled() && this.pressed && this.pressed === tool && (
1207                         e.which === OO.ui.MouseButtons.LEFT ||
1208                         e.which === OO.ui.Keys.SPACE ||
1209                         e.which === OO.ui.Keys.ENTER
1210                 )
1211         ) {
1212                 this.pressed.onSelect();
1213                 this.pressed = null;
1214                 e.preventDefault();
1215                 e.stopPropagation();
1216         }
1217
1218         this.pressed = null;
1219 };
1220
1221 /**
1222  * Handle mouse over and focus events.
1223  *
1224  * @protected
1225  * @param {jQuery.Event} e Mouse over or focus event
1226  */
1227 OO.ui.ToolGroup.prototype.onMouseOverFocus = function ( e ) {
1228         var tool = this.findTargetTool( e );
1229
1230         if ( this.pressed && this.pressed === tool ) {
1231                 this.pressed.setActive( true );
1232         }
1233 };
1234
1235 /**
1236  * Handle mouse out and blur events.
1237  *
1238  * @protected
1239  * @param {jQuery.Event} e Mouse out or blur event
1240  */
1241 OO.ui.ToolGroup.prototype.onMouseOutBlur = function ( e ) {
1242         var tool = this.findTargetTool( e );
1243
1244         if ( this.pressed && this.pressed === tool ) {
1245                 this.pressed.setActive( false );
1246         }
1247 };
1248
1249 /**
1250  * Get the closest tool to a jQuery.Event.
1251  *
1252  * Only tool links are considered, which prevents other elements in the tool such as popups from
1253  * triggering tool group interactions.
1254  *
1255  * @private
1256  * @param {jQuery.Event} e
1257  * @return {OO.ui.Tool|null} Tool, `null` if none was found
1258  */
1259 OO.ui.ToolGroup.prototype.findTargetTool = function ( e ) {
1260         var tool,
1261                 $item = $( e.target ).closest( '.oo-ui-tool-link' );
1262
1263         if ( $item.length ) {
1264                 tool = $item.parent().data( 'oo-ui-tool' );
1265         }
1266
1267         return tool && !tool.isDisabled() ? tool : null;
1268 };
1269
1270 /**
1271  * Handle tool registry register events.
1272  *
1273  * If a tool is registered after the group is created, we must repopulate the list to account for:
1274  *
1275  * - a tool being added that may be included
1276  * - a tool already included being overridden
1277  *
1278  * @protected
1279  * @param {string} name Symbolic name of tool
1280  */
1281 OO.ui.ToolGroup.prototype.onToolFactoryRegister = function () {
1282         this.populate();
1283 };
1284
1285 /**
1286  * Get the toolbar that contains the toolgroup.
1287  *
1288  * @return {OO.ui.Toolbar} Toolbar that contains the toolgroup
1289  */
1290 OO.ui.ToolGroup.prototype.getToolbar = function () {
1291         return this.toolbar;
1292 };
1293
1294 /**
1295  * Add and remove tools based on configuration.
1296  */
1297 OO.ui.ToolGroup.prototype.populate = function () {
1298         var i, len, name, tool,
1299                 toolFactory = this.toolbar.getToolFactory(),
1300                 names = {},
1301                 add = [],
1302                 remove = [],
1303                 list = this.toolbar.getToolFactory().getTools(
1304                         this.include, this.exclude, this.promote, this.demote
1305                 );
1306
1307         // Build a list of needed tools
1308         for ( i = 0, len = list.length; i < len; i++ ) {
1309                 name = list[ i ];
1310                 if (
1311                         // Tool exists
1312                         toolFactory.lookup( name ) &&
1313                         // Tool is available or is already in this group
1314                         ( this.toolbar.isToolAvailable( name ) || this.tools[ name ] )
1315                 ) {
1316                         // Hack to prevent infinite recursion via ToolGroupTool. We need to reserve the tool
1317                         // before creating it, but we can't call reserveTool() yet because we haven't created
1318                         // the tool.
1319                         this.toolbar.tools[ name ] = true;
1320                         tool = this.tools[ name ];
1321                         if ( !tool ) {
1322                                 // Auto-initialize tools on first use
1323                                 this.tools[ name ] = tool = toolFactory.create( name, this );
1324                                 tool.updateTitle();
1325                         }
1326                         this.toolbar.reserveTool( tool );
1327                         add.push( tool );
1328                         names[ name ] = true;
1329                 }
1330         }
1331         // Remove tools that are no longer needed
1332         for ( name in this.tools ) {
1333                 if ( !names[ name ] ) {
1334                         this.tools[ name ].destroy();
1335                         this.toolbar.releaseTool( this.tools[ name ] );
1336                         remove.push( this.tools[ name ] );
1337                         delete this.tools[ name ];
1338                 }
1339         }
1340         if ( remove.length ) {
1341                 this.removeItems( remove );
1342         }
1343         // Update emptiness state
1344         if ( add.length ) {
1345                 this.$element.removeClass( 'oo-ui-toolGroup-empty' );
1346         } else {
1347                 this.$element.addClass( 'oo-ui-toolGroup-empty' );
1348         }
1349         // Re-add tools (moving existing ones to new locations)
1350         this.addItems( add );
1351         // Disabled state may depend on items
1352         this.updateDisabled();
1353 };
1354
1355 /**
1356  * Destroy toolgroup.
1357  */
1358 OO.ui.ToolGroup.prototype.destroy = function () {
1359         var name;
1360
1361         this.clearItems();
1362         this.toolbar.getToolFactory().disconnect( this );
1363         for ( name in this.tools ) {
1364                 this.toolbar.releaseTool( this.tools[ name ] );
1365                 this.tools[ name ].disconnect( this ).destroy();
1366                 delete this.tools[ name ];
1367         }
1368         this.$element.remove();
1369 };
1370
1371 /**
1372  * A ToolFactory creates tools on demand. All tools ({@link OO.ui.Tool Tools},
1373  * {@link OO.ui.PopupTool PopupTools}, and {@link OO.ui.ToolGroupTool ToolGroupTools}) must be
1374  * registered with a tool factory. Tools are registered by their symbolic name. See
1375  * {@link OO.ui.Toolbar toolbars} for an example.
1376  *
1377  * For more information about toolbars in general, please see the
1378  * [OOUI documentation on MediaWiki][1].
1379  *
1380  * [1]: https://www.mediawiki.org/wiki/OOUI/Toolbars
1381  *
1382  * @class
1383  * @extends OO.Factory
1384  * @constructor
1385  */
1386 OO.ui.ToolFactory = function OoUiToolFactory() {
1387         // Parent constructor
1388         OO.ui.ToolFactory.parent.call( this );
1389 };
1390
1391 /* Setup */
1392
1393 OO.inheritClass( OO.ui.ToolFactory, OO.Factory );
1394
1395 /* Methods */
1396
1397 /**
1398  * Get tools from the factory.
1399  *
1400  * @param {Array|string} [include] Included tools, see #extract for format
1401  * @param {Array|string} [exclude] Excluded tools, see #extract for format
1402  * @param {Array|string} [promote] Promoted tools, see #extract for format
1403  * @param {Array|string} [demote] Demoted tools, see #extract for format
1404  * @return {string[]} List of tools
1405  */
1406 OO.ui.ToolFactory.prototype.getTools = function ( include, exclude, promote, demote ) {
1407         var i, len, included, promoted, demoted,
1408                 auto = [],
1409                 used = {};
1410
1411         // Collect included and not excluded tools
1412         included = OO.simpleArrayDifference( this.extract( include ), this.extract( exclude ) );
1413
1414         // Promotion
1415         promoted = this.extract( promote, used );
1416         demoted = this.extract( demote, used );
1417
1418         // Auto
1419         for ( i = 0, len = included.length; i < len; i++ ) {
1420                 if ( !used[ included[ i ] ] ) {
1421                         auto.push( included[ i ] );
1422                 }
1423         }
1424
1425         return promoted.concat( auto ).concat( demoted );
1426 };
1427
1428 /**
1429  * Get a flat list of names from a list of names or groups.
1430  *
1431  * Normally, `collection` is an array of tool specifications. Tools can be specified in the
1432  * following ways:
1433  *
1434  * - To include an individual tool, use the symbolic name: `{ name: 'tool-name' }` or `'tool-name'`.
1435  * - To include all tools in a group, use the group name: `{ group: 'group-name' }`. (To assign the
1436  *   tool to a group, use OO.ui.Tool.static.group.)
1437  *
1438  * Alternatively, to include all tools that are not yet assigned to any other toolgroup, use the
1439  * catch-all selector `'*'`.
1440  *
1441  * If `used` is passed, tool names that appear as properties in this object will be considered
1442  * already assigned, and will not be returned even if specified otherwise. The tool names extracted
1443  * by this function call will be added as new properties in the object.
1444  *
1445  * @private
1446  * @param {Array|string} collection List of tools, see above
1447  * @param {Object} [used] Object containing information about used tools, see above
1448  * @return {string[]} List of extracted tool names
1449  */
1450 OO.ui.ToolFactory.prototype.extract = function ( collection, used ) {
1451         var i, len, item, name, tool,
1452                 names = [];
1453
1454         collection = !Array.isArray( collection ) ? [ collection ] : collection;
1455
1456         for ( i = 0, len = collection.length; i < len; i++ ) {
1457                 item = collection[ i ];
1458                 if ( item === '*' ) {
1459                         for ( name in this.registry ) {
1460                                 tool = this.registry[ name ];
1461                                 if (
1462                                         // Only add tools by group name when auto-add is enabled
1463                                         tool.static.autoAddToCatchall &&
1464                                         // Exclude already used tools
1465                                         ( !used || !used[ name ] )
1466                                 ) {
1467                                         names.push( name );
1468                                         if ( used ) {
1469                                                 used[ name ] = true;
1470                                         }
1471                                 }
1472                         }
1473                 } else {
1474                         // Allow plain strings as shorthand for named tools
1475                         if ( typeof item === 'string' ) {
1476                                 item = { name: item };
1477                         }
1478                         if ( OO.isPlainObject( item ) ) {
1479                                 if ( item.group ) {
1480                                         for ( name in this.registry ) {
1481                                                 tool = this.registry[ name ];
1482                                                 if (
1483                                                         // Include tools with matching group
1484                                                         tool.static.group === item.group &&
1485                                                         // Only add tools by group name when auto-add is enabled
1486                                                         tool.static.autoAddToGroup &&
1487                                                         // Exclude already used tools
1488                                                         ( !used || !used[ name ] )
1489                                                 ) {
1490                                                         names.push( name );
1491                                                         if ( used ) {
1492                                                                 used[ name ] = true;
1493                                                         }
1494                                                 }
1495                                         }
1496                                 // Include tools with matching name and exclude already used tools
1497                                 } else if ( item.name && ( !used || !used[ item.name ] ) ) {
1498                                         names.push( item.name );
1499                                         if ( used ) {
1500                                                 used[ item.name ] = true;
1501                                         }
1502                                 }
1503                         }
1504                 }
1505         }
1506         return names;
1507 };
1508
1509 /**
1510  * ToolGroupFactories create {@link OO.ui.ToolGroup toolgroups} on demand. The toolgroup classes
1511  * must specify a symbolic name and be registered with the factory. The following classes are
1512  * registered by default:
1513  *
1514  * - {@link OO.ui.BarToolGroup BarToolGroups} (‘bar’)
1515  * - {@link OO.ui.MenuToolGroup MenuToolGroups} (‘menu’)
1516  * - {@link OO.ui.ListToolGroup ListToolGroups} (‘list’)
1517  *
1518  * See {@link OO.ui.Toolbar toolbars} for an example.
1519  *
1520  * For more information about toolbars in general, please see the
1521  * [OOUI documentation on MediaWiki][1].
1522  *
1523  * [1]: https://www.mediawiki.org/wiki/OOUI/Toolbars
1524  *
1525  * @class
1526  * @extends OO.Factory
1527  * @constructor
1528  */
1529 OO.ui.ToolGroupFactory = function OoUiToolGroupFactory() {
1530         var i, l, defaultClasses;
1531         // Parent constructor
1532         OO.Factory.call( this );
1533
1534         defaultClasses = this.constructor.static.getDefaultClasses();
1535
1536         // Register default toolgroups
1537         for ( i = 0, l = defaultClasses.length; i < l; i++ ) {
1538                 this.register( defaultClasses[ i ] );
1539         }
1540 };
1541
1542 /* Setup */
1543
1544 OO.inheritClass( OO.ui.ToolGroupFactory, OO.Factory );
1545
1546 /* Static Methods */
1547
1548 /**
1549  * Get a default set of classes to be registered on construction.
1550  *
1551  * @return {Function[]} Default classes
1552  */
1553 OO.ui.ToolGroupFactory.static.getDefaultClasses = function () {
1554         return [
1555                 OO.ui.BarToolGroup,
1556                 OO.ui.ListToolGroup,
1557                 OO.ui.MenuToolGroup
1558         ];
1559 };
1560
1561 /**
1562  * Popup tools open a popup window when they are selected from the {@link OO.ui.Toolbar toolbar}.
1563  * Each popup tool is configured with a static name, title, and icon, as well with as any popup
1564  * configurations. Unlike other tools, popup tools do not require that developers specify an
1565  * #onSelect or #onUpdateState method, as these methods have been implemented already.
1566  *
1567  *     // Example of a popup tool. When selected, a popup tool displays
1568  *     // a popup window.
1569  *     function HelpTool( toolGroup, config ) {
1570  *        OO.ui.PopupTool.call( this, toolGroup, $.extend( { popup: {
1571  *            padded: true,
1572  *            label: 'Help',
1573  *            head: true
1574  *        } }, config ) );
1575  *        this.popup.$body.append( '<p>I am helpful!</p>' );
1576  *     };
1577  *     OO.inheritClass( HelpTool, OO.ui.PopupTool );
1578  *     HelpTool.static.name = 'help';
1579  *     HelpTool.static.icon = 'help';
1580  *     HelpTool.static.title = 'Help';
1581  *     toolFactory.register( HelpTool );
1582  *
1583  * For an example of a toolbar that contains a popup tool, see {@link OO.ui.Toolbar toolbars}.
1584  * For more information about toolbars in general, please see the
1585  * [OOUI documentation on MediaWiki][1].
1586  *
1587  * [1]: https://www.mediawiki.org/wiki/OOUI/Toolbars
1588  *
1589  * @abstract
1590  * @class
1591  * @extends OO.ui.Tool
1592  * @mixins OO.ui.mixin.PopupElement
1593  *
1594  * @constructor
1595  * @param {OO.ui.ToolGroup} toolGroup
1596  * @param {Object} [config] Configuration options
1597  */
1598 OO.ui.PopupTool = function OoUiPopupTool( toolGroup, config ) {
1599         // Allow passing positional parameters inside the config object
1600         if ( OO.isPlainObject( toolGroup ) && config === undefined ) {
1601                 config = toolGroup;
1602                 toolGroup = config.toolGroup;
1603         }
1604
1605         // Parent constructor
1606         OO.ui.PopupTool.parent.call( this, toolGroup, config );
1607
1608         // Mixin constructors
1609         OO.ui.mixin.PopupElement.call( this, config );
1610
1611         // Events
1612         this.popup.connect( this, {
1613                 toggle: 'onPopupToggle'
1614         } );
1615
1616         // Initialization
1617         this.popup.setAutoFlip( false );
1618         this.popup.setPosition( toolGroup.getToolbar().position === 'bottom' ? 'above' : 'below' );
1619         this.$element.addClass( 'oo-ui-popupTool' );
1620         this.popup.$element.addClass( 'oo-ui-popupTool-popup' );
1621         this.toolbar.$popups.append( this.popup.$element );
1622 };
1623
1624 /* Setup */
1625
1626 OO.inheritClass( OO.ui.PopupTool, OO.ui.Tool );
1627 OO.mixinClass( OO.ui.PopupTool, OO.ui.mixin.PopupElement );
1628
1629 /* Methods */
1630
1631 /**
1632  * Handle the tool being selected.
1633  *
1634  * @inheritdoc
1635  */
1636 OO.ui.PopupTool.prototype.onSelect = function () {
1637         if ( !this.isDisabled() ) {
1638                 this.popup.toggle();
1639         }
1640         return false;
1641 };
1642
1643 /**
1644  * Handle the toolbar state being updated.
1645  *
1646  * @inheritdoc
1647  */
1648 OO.ui.PopupTool.prototype.onUpdateState = function () {
1649 };
1650
1651 /**
1652  * Handle popup visibility being toggled.
1653  *
1654  * @param {boolean} isVisible
1655  */
1656 OO.ui.PopupTool.prototype.onPopupToggle = function ( isVisible ) {
1657         this.setActive( isVisible );
1658         this.toolGroup.emit( 'active', isVisible );
1659 };
1660
1661 /**
1662  * A ToolGroupTool is a special sort of tool that can contain other {@link OO.ui.Tool tools}
1663  * and {@link OO.ui.ToolGroup toolgroups}. The ToolGroupTool was specifically designed to be used
1664  * inside a {@link OO.ui.BarToolGroup bar} toolgroup to provide access to additional tools from
1665  * the bar item. Included tools will be displayed in a dropdown {@link OO.ui.ListToolGroup list}
1666  * when the ToolGroupTool is selected.
1667  *
1668  *     // Example: ToolGroupTool with two nested tools, 'setting1' and 'setting2',
1669  *     // defined elsewhere.
1670  *
1671  *     function SettingsTool() {
1672  *         SettingsTool.parent.apply( this, arguments );
1673  *     };
1674  *     OO.inheritClass( SettingsTool, OO.ui.ToolGroupTool );
1675  *     SettingsTool.static.name = 'settings';
1676  *     SettingsTool.static.title = 'Change settings';
1677  *     SettingsTool.static.groupConfig = {
1678  *         icon: 'settings',
1679  *         label: 'ToolGroupTool',
1680  *         include: [  'setting1', 'setting2'  ]
1681  *     };
1682  *     toolFactory.register( SettingsTool );
1683  *
1684  * For more information, please see the [OOUI documentation on MediaWiki][1].
1685  *
1686  * Please note that this implementation is subject to change per [T74159] [2].
1687  *
1688  * [1]: https://www.mediawiki.org/wiki/OOUI/Toolbars#ToolGroupTool
1689  * [2]: https://phabricator.wikimedia.org/T74159
1690  *
1691  * @abstract
1692  * @class
1693  * @extends OO.ui.Tool
1694  *
1695  * @constructor
1696  * @param {OO.ui.ToolGroup} toolGroup
1697  * @param {Object} [config] Configuration options
1698  */
1699 OO.ui.ToolGroupTool = function OoUiToolGroupTool( toolGroup, config ) {
1700         // Allow passing positional parameters inside the config object
1701         if ( OO.isPlainObject( toolGroup ) && config === undefined ) {
1702                 config = toolGroup;
1703                 toolGroup = config.toolGroup;
1704         }
1705
1706         // Parent constructor
1707         OO.ui.ToolGroupTool.parent.call( this, toolGroup, config );
1708
1709         // Properties
1710         this.innerToolGroup = this.createGroup( this.constructor.static.groupConfig );
1711
1712         // Events
1713         this.innerToolGroup.connect( this, {
1714                 disable: 'onToolGroupDisable',
1715                 // Re-emit active events from the innerToolGroup on the parent toolGroup
1716                 active: this.toolGroup.emit.bind( this.toolGroup, 'active' )
1717         } );
1718
1719         // Initialization
1720         this.$link.remove();
1721         this.$element
1722                 .addClass( 'oo-ui-toolGroupTool' )
1723                 .append( this.innerToolGroup.$element );
1724 };
1725
1726 /* Setup */
1727
1728 OO.inheritClass( OO.ui.ToolGroupTool, OO.ui.Tool );
1729
1730 /* Static Properties */
1731
1732 /**
1733  * Toolgroup configuration.
1734  *
1735  * The toolgroup configuration consists of the tools to include, as well as an icon and label
1736  * to use for the bar item. Tools can be included by symbolic name, group, or with the
1737  * wildcard selector. Please see {@link OO.ui.ToolGroup toolgroup} for more information.
1738  *
1739  * @property {Object.<string,Array>}
1740  */
1741 OO.ui.ToolGroupTool.static.groupConfig = {};
1742
1743 /* Methods */
1744
1745 /**
1746  * Handle the tool being selected.
1747  *
1748  * @inheritdoc
1749  */
1750 OO.ui.ToolGroupTool.prototype.onSelect = function () {
1751         this.innerToolGroup.setActive( !this.innerToolGroup.active );
1752         return false;
1753 };
1754
1755 /**
1756  * Synchronize disabledness state of the tool with the inner toolgroup.
1757  *
1758  * @private
1759  * @param {boolean} disabled Element is disabled
1760  */
1761 OO.ui.ToolGroupTool.prototype.onToolGroupDisable = function ( disabled ) {
1762         this.setDisabled( disabled );
1763 };
1764
1765 /**
1766  * Handle the toolbar state being updated.
1767  *
1768  * @inheritdoc
1769  */
1770 OO.ui.ToolGroupTool.prototype.onUpdateState = function () {
1771         this.setActive( false );
1772 };
1773
1774 /**
1775  * Build a {@link OO.ui.ToolGroup toolgroup} from the specified configuration.
1776  *
1777  * @param {Object.<string,Array>} group Toolgroup configuration. Please see
1778  *  {@link OO.ui.ToolGroup toolgroup} for more information.
1779  * @return {OO.ui.ListToolGroup}
1780  */
1781 OO.ui.ToolGroupTool.prototype.createGroup = function ( group ) {
1782         if ( group.include === '*' ) {
1783                 // Apply defaults to catch-all groups
1784                 if ( group.label === undefined ) {
1785                         group.label = OO.ui.msg( 'ooui-toolbar-more' );
1786                 }
1787         }
1788
1789         return this.toolbar.getToolGroupFactory().create( 'list', this.toolbar, group );
1790 };
1791
1792 /**
1793  * BarToolGroups are one of three types of {@link OO.ui.ToolGroup toolgroups} that are used to
1794  * create {@link OO.ui.Toolbar toolbars} (the other types of groups are
1795  * {@link OO.ui.MenuToolGroup MenuToolGroup} and {@link OO.ui.ListToolGroup ListToolGroup}).
1796  * The {@link OO.ui.Tool tools} in a BarToolGroup are displayed by icon in a single row. The
1797  * title of the tool is displayed when users move the mouse over the tool.
1798  *
1799  * BarToolGroups are created by a {@link OO.ui.ToolGroupFactory tool group factory} when the toolbar
1800  * is set up.
1801  *
1802  *     @example
1803  *     // Example of a BarToolGroup with two tools
1804  *     var toolFactory = new OO.ui.ToolFactory();
1805  *     var toolGroupFactory = new OO.ui.ToolGroupFactory();
1806  *     var toolbar = new OO.ui.Toolbar( toolFactory, toolGroupFactory );
1807  *
1808  *     // We will be placing status text in this element when tools are used
1809  *     var $area = $( '<p>' ).text( 'Example of a BarToolGroup with two tools.' );
1810  *
1811  *     // Define the tools that we're going to place in our toolbar
1812  *
1813  *     // Create a class inheriting from OO.ui.Tool
1814  *     function SearchTool() {
1815  *         SearchTool.parent.apply( this, arguments );
1816  *     }
1817  *     OO.inheritClass( SearchTool, OO.ui.Tool );
1818  *     // Each tool must have a 'name' (used as an internal identifier, see later) and at least one
1819  *     // of 'icon' and 'title' (displayed icon and text).
1820  *     SearchTool.static.name = 'search';
1821  *     SearchTool.static.icon = 'search';
1822  *     SearchTool.static.title = 'Search...';
1823  *     // Defines the action that will happen when this tool is selected (clicked).
1824  *     SearchTool.prototype.onSelect = function () {
1825  *         $area.text( 'Search tool clicked!' );
1826  *         // Never display this tool as "active" (selected).
1827  *         this.setActive( false );
1828  *     };
1829  *     SearchTool.prototype.onUpdateState = function () {};
1830  *     // Make this tool available in our toolFactory and thus our toolbar
1831  *     toolFactory.register( SearchTool );
1832  *
1833  *     // This is a PopupTool. Rather than having a custom 'onSelect' action, it will display a
1834  *     // little popup window (a PopupWidget).
1835  *     function HelpTool( toolGroup, config ) {
1836  *         OO.ui.PopupTool.call( this, toolGroup, $.extend( { popup: {
1837  *             padded: true,
1838  *             label: 'Help',
1839  *             head: true
1840  *         } }, config ) );
1841  *         this.popup.$body.append( '<p>I am helpful!</p>' );
1842  *     }
1843  *     OO.inheritClass( HelpTool, OO.ui.PopupTool );
1844  *     HelpTool.static.name = 'help';
1845  *     HelpTool.static.icon = 'help';
1846  *     HelpTool.static.title = 'Help';
1847  *     toolFactory.register( HelpTool );
1848  *
1849  *     // Finally define which tools and in what order appear in the toolbar. Each tool may only be
1850  *     // used once (but not all defined tools must be used).
1851  *     toolbar.setup( [
1852  *         {
1853  *             // 'bar' tool groups display tools by icon only
1854  *             type: 'bar',
1855  *             include: [ 'search', 'help' ]
1856  *         }
1857  *     ] );
1858  *
1859  *     // Create some UI around the toolbar and place it in the document
1860  *     var frame = new OO.ui.PanelLayout( {
1861  *         expanded: false,
1862  *         framed: true
1863  *     } );
1864  *     var contentFrame = new OO.ui.PanelLayout( {
1865  *         expanded: false,
1866  *         padded: true
1867  *     } );
1868  *     frame.$element.append(
1869  *         toolbar.$element,
1870  *         contentFrame.$element.append( $area )
1871  *     );
1872  *     $( document.body ).append( frame.$element );
1873  *
1874  *     // Here is where the toolbar is actually built. This must be done after inserting it into the
1875  *     // document.
1876  *     toolbar.initialize();
1877  *
1878  * For more information about how to add tools to a bar tool group, please see
1879  * {@link OO.ui.ToolGroup toolgroup}.
1880  * For more information about toolbars in general, please see the
1881  * [OOUI documentation on MediaWiki][1].
1882  *
1883  * [1]: https://www.mediawiki.org/wiki/OOUI/Toolbars
1884  *
1885  * @class
1886  * @extends OO.ui.ToolGroup
1887  *
1888  * @constructor
1889  * @param {OO.ui.Toolbar} toolbar
1890  * @param {Object} [config] Configuration options
1891  */
1892 OO.ui.BarToolGroup = function OoUiBarToolGroup( toolbar, config ) {
1893         // Allow passing positional parameters inside the config object
1894         if ( OO.isPlainObject( toolbar ) && config === undefined ) {
1895                 config = toolbar;
1896                 toolbar = config.toolbar;
1897         }
1898
1899         // Parent constructor
1900         OO.ui.BarToolGroup.parent.call( this, toolbar, config );
1901
1902         // Initialization
1903         this.$element.addClass( 'oo-ui-barToolGroup' );
1904         this.$group.addClass( 'oo-ui-barToolGroup-tools' );
1905 };
1906
1907 /* Setup */
1908
1909 OO.inheritClass( OO.ui.BarToolGroup, OO.ui.ToolGroup );
1910
1911 /* Static Properties */
1912
1913 /**
1914  * @static
1915  * @inheritdoc
1916  */
1917 OO.ui.BarToolGroup.static.titleTooltips = true;
1918
1919 /**
1920  * @static
1921  * @inheritdoc
1922  */
1923 OO.ui.BarToolGroup.static.accelTooltips = true;
1924
1925 /**
1926  * @static
1927  * @inheritdoc
1928  */
1929 OO.ui.BarToolGroup.static.name = 'bar';
1930
1931 /**
1932  * PopupToolGroup is an abstract base class used by both {@link OO.ui.MenuToolGroup MenuToolGroup}
1933  * and {@link OO.ui.ListToolGroup ListToolGroup} to provide a popup (an overlaid menu or list of
1934  * tools with an optional icon and label). This class can be used for other base classes that
1935  * also use this functionality.
1936  *
1937  * @abstract
1938  * @class
1939  * @extends OO.ui.ToolGroup
1940  * @mixins OO.ui.mixin.IconElement
1941  * @mixins OO.ui.mixin.IndicatorElement
1942  * @mixins OO.ui.mixin.LabelElement
1943  * @mixins OO.ui.mixin.TitledElement
1944  * @mixins OO.ui.mixin.FlaggedElement
1945  * @mixins OO.ui.mixin.ClippableElement
1946  * @mixins OO.ui.mixin.FloatableElement
1947  * @mixins OO.ui.mixin.TabIndexedElement
1948  *
1949  * @constructor
1950  * @param {OO.ui.Toolbar} toolbar
1951  * @param {Object} [config] Configuration options
1952  * @cfg {string} [header] Text to display at the top of the popup
1953  */
1954 OO.ui.PopupToolGroup = function OoUiPopupToolGroup( toolbar, config ) {
1955         // Allow passing positional parameters inside the config object
1956         if ( OO.isPlainObject( toolbar ) && config === undefined ) {
1957                 config = toolbar;
1958                 toolbar = config.toolbar;
1959         }
1960
1961         // Configuration initialization
1962         config = $.extend( {
1963                 indicator: config.indicator === undefined ?
1964                         ( toolbar.position === 'bottom' ? 'up' : 'down' ) : config.indicator
1965         }, config );
1966
1967         // Parent constructor
1968         OO.ui.PopupToolGroup.parent.call( this, toolbar, config );
1969
1970         // Properties
1971         this.active = false;
1972         this.dragging = false;
1973         // Don't conflict with parent method of the same name
1974         this.onPopupDocumentMouseKeyUpHandler = this.onPopupDocumentMouseKeyUp.bind( this );
1975         this.$handle = $( '<span>' );
1976
1977         // Mixin constructors
1978         OO.ui.mixin.IconElement.call( this, config );
1979         OO.ui.mixin.IndicatorElement.call( this, config );
1980         OO.ui.mixin.LabelElement.call( this, config );
1981         OO.ui.mixin.TitledElement.call( this, config );
1982         OO.ui.mixin.FlaggedElement.call( this, config );
1983         OO.ui.mixin.ClippableElement.call( this, $.extend( {
1984                 $clippable: this.$group
1985         }, config ) );
1986         OO.ui.mixin.FloatableElement.call( this, $.extend( {
1987                 $floatable: this.$group,
1988                 $floatableContainer: this.$handle,
1989                 hideWhenOutOfView: false,
1990                 verticalPosition: this.toolbar.position === 'bottom' ? 'above' : 'below'
1991         }, config ) );
1992         OO.ui.mixin.TabIndexedElement.call( this, $.extend( {
1993                 $tabIndexed: this.$handle
1994         }, config ) );
1995
1996         // Events
1997         this.$handle.on( {
1998                 keydown: this.onHandleMouseKeyDown.bind( this ),
1999                 keyup: this.onHandleMouseKeyUp.bind( this ),
2000                 mousedown: this.onHandleMouseKeyDown.bind( this ),
2001                 mouseup: this.onHandleMouseKeyUp.bind( this )
2002         } );
2003
2004         // Initialization
2005         this.$handle
2006                 .addClass( 'oo-ui-popupToolGroup-handle' )
2007                 .attr( 'role', 'button' )
2008                 .append( this.$icon, this.$label, this.$indicator );
2009         // If the pop-up should have a header, add it to the top of the toolGroup.
2010         // Note: If this feature is useful for other widgets, we could abstract it into an
2011         // OO.ui.HeaderedElement mixin constructor.
2012         if ( config.header !== undefined ) {
2013                 this.$group
2014                         .prepend( $( '<span>' )
2015                                 .addClass( 'oo-ui-popupToolGroup-header' )
2016                                 .text( config.header )
2017                         );
2018         }
2019         this.$element
2020                 .addClass( 'oo-ui-popupToolGroup' )
2021                 .prepend( this.$handle );
2022         this.$group.addClass( 'oo-ui-popupToolGroup-tools' );
2023         this.toolbar.$popups.append( this.$group );
2024 };
2025
2026 /* Setup */
2027
2028 OO.inheritClass( OO.ui.PopupToolGroup, OO.ui.ToolGroup );
2029 OO.mixinClass( OO.ui.PopupToolGroup, OO.ui.mixin.IconElement );
2030 OO.mixinClass( OO.ui.PopupToolGroup, OO.ui.mixin.IndicatorElement );
2031 OO.mixinClass( OO.ui.PopupToolGroup, OO.ui.mixin.LabelElement );
2032 OO.mixinClass( OO.ui.PopupToolGroup, OO.ui.mixin.TitledElement );
2033 OO.mixinClass( OO.ui.PopupToolGroup, OO.ui.mixin.FlaggedElement );
2034 OO.mixinClass( OO.ui.PopupToolGroup, OO.ui.mixin.ClippableElement );
2035 OO.mixinClass( OO.ui.PopupToolGroup, OO.ui.mixin.FloatableElement );
2036 OO.mixinClass( OO.ui.PopupToolGroup, OO.ui.mixin.TabIndexedElement );
2037
2038 /* Methods */
2039
2040 /**
2041  * @inheritdoc
2042  */
2043 OO.ui.PopupToolGroup.prototype.setDisabled = function () {
2044         // Parent method
2045         OO.ui.PopupToolGroup.parent.prototype.setDisabled.apply( this, arguments );
2046
2047         if ( this.isDisabled() && this.isElementAttached() ) {
2048                 this.setActive( false );
2049         }
2050 };
2051
2052 /**
2053  * Handle document mouse up and key up events.
2054  *
2055  * @protected
2056  * @param {MouseEvent|KeyboardEvent} e Mouse up or key up event
2057  */
2058 OO.ui.PopupToolGroup.prototype.onPopupDocumentMouseKeyUp = function ( e ) {
2059         var $target = $( e.target );
2060         // Only deactivate when clicking outside the dropdown element
2061         if ( $target.closest( '.oo-ui-popupToolGroup' )[ 0 ] === this.$element[ 0 ] ) {
2062                 return;
2063         }
2064         if ( $target.closest( '.oo-ui-popupToolGroup-tools' )[ 0 ] === this.$group[ 0 ] ) {
2065                 return;
2066         }
2067         this.setActive( false );
2068 };
2069
2070 /**
2071  * @inheritdoc
2072  */
2073 OO.ui.PopupToolGroup.prototype.onMouseKeyUp = function ( e ) {
2074         // Only close toolgroup when a tool was actually selected
2075         if (
2076                 !this.isDisabled() && this.pressed && this.pressed === this.findTargetTool( e ) && (
2077                         e.which === OO.ui.MouseButtons.LEFT ||
2078                         e.which === OO.ui.Keys.SPACE ||
2079                         e.which === OO.ui.Keys.ENTER
2080                 )
2081         ) {
2082                 this.setActive( false );
2083         }
2084         return OO.ui.PopupToolGroup.parent.prototype.onMouseKeyUp.call( this, e );
2085 };
2086
2087 /**
2088  * @inheritdoc
2089  */
2090 OO.ui.PopupToolGroup.prototype.onMouseKeyDown = function ( e ) {
2091         var $focused, $firstFocusable, $lastFocusable;
2092         // Shift-Tab on the first tool in the group jumps to the handle.
2093         // Tab on the last tool in the group jumps to the next group.
2094         if ( !this.isDisabled() && e.which === OO.ui.Keys.TAB ) {
2095                 // We can't use this.items because ListToolGroup inserts the extra fake
2096                 // expand/collapse tool.
2097                 $focused = $( document.activeElement );
2098                 $firstFocusable = OO.ui.findFocusable( this.$group );
2099                 if ( $focused[ 0 ] === $firstFocusable[ 0 ] && e.shiftKey ) {
2100                         this.$handle.trigger( 'focus' );
2101                         return false;
2102                 }
2103                 $lastFocusable = OO.ui.findFocusable( this.$group, true );
2104                 if ( $focused[ 0 ] === $lastFocusable[ 0 ] && !e.shiftKey ) {
2105                         // Focus this group's handle and let the browser's tab handling happen
2106                         // (no 'return false').
2107                         // This way we don't have to fiddle with other ToolGroups' business, or worry what to do
2108                         // if the next group is not a PopupToolGroup or doesn't exist at all.
2109                         this.$handle.trigger( 'focus' );
2110                         // Close the popup so that we don't move back inside it (if this is the last group).
2111                         this.setActive( false );
2112                 }
2113         }
2114         return OO.ui.PopupToolGroup.parent.prototype.onMouseKeyDown.call( this, e );
2115 };
2116
2117 /**
2118  * Handle mouse up and key up events.
2119  *
2120  * @protected
2121  * @param {jQuery.Event} e Mouse up or key up event
2122  * @return {undefined/boolean} False to prevent default if event is handled
2123  */
2124 OO.ui.PopupToolGroup.prototype.onHandleMouseKeyUp = function ( e ) {
2125         if (
2126                 !this.isDisabled() && (
2127                         e.which === OO.ui.MouseButtons.LEFT ||
2128                         e.which === OO.ui.Keys.SPACE ||
2129                         e.which === OO.ui.Keys.ENTER
2130                 )
2131         ) {
2132                 return false;
2133         }
2134 };
2135
2136 /**
2137  * Handle mouse down and key down events.
2138  *
2139  * @protected
2140  * @param {jQuery.Event} e Mouse down or key down event
2141  * @return {undefined/boolean} False to prevent default if event is handled
2142  */
2143 OO.ui.PopupToolGroup.prototype.onHandleMouseKeyDown = function ( e ) {
2144         var $focusable;
2145         if ( !this.isDisabled() ) {
2146                 // Tab on the handle jumps to the first tool in the group (if the popup is open).
2147                 if ( e.which === OO.ui.Keys.TAB && !e.shiftKey ) {
2148                         $focusable = OO.ui.findFocusable( this.$group );
2149                         if ( $focusable.length ) {
2150                                 $focusable.trigger( 'focus' );
2151                                 return false;
2152                         }
2153                 }
2154                 if (
2155                         e.which === OO.ui.MouseButtons.LEFT ||
2156                         e.which === OO.ui.Keys.SPACE ||
2157                         e.which === OO.ui.Keys.ENTER
2158                 ) {
2159                         this.setActive( !this.active );
2160                         return false;
2161                 }
2162         }
2163 };
2164
2165 /**
2166  * Check if the tool group is active.
2167  *
2168  * @return {boolean} Tool group is active
2169  */
2170 OO.ui.PopupToolGroup.prototype.isActive = function () {
2171         return this.active;
2172 };
2173
2174 /**
2175  * Switch into 'active' mode.
2176  *
2177  * When active, the popup is visible. A mouseup event anywhere in the document will trigger
2178  * deactivation.
2179  *
2180  * @param {boolean} value The active state to set
2181  * @fires active
2182  */
2183 OO.ui.PopupToolGroup.prototype.setActive = function ( value ) {
2184         var containerWidth, containerLeft;
2185         value = !!value;
2186         if ( this.active !== value ) {
2187                 this.active = value;
2188                 if ( value ) {
2189                         this.getElementDocument().addEventListener(
2190                                 'mouseup',
2191                                 this.onPopupDocumentMouseKeyUpHandler,
2192                                 true
2193                         );
2194                         this.getElementDocument().addEventListener(
2195                                 'keyup',
2196                                 this.onPopupDocumentMouseKeyUpHandler,
2197                                 true
2198                         );
2199
2200                         this.$clippable.css( 'left', '' );
2201                         this.$element.addClass( 'oo-ui-popupToolGroup-active' );
2202                         this.$group.addClass( 'oo-ui-popupToolGroup-active-tools' );
2203                         this.togglePositioning( true );
2204                         this.toggleClipping( true );
2205
2206                         // Try anchoring the popup to the left first
2207                         this.setHorizontalPosition( 'start' );
2208
2209                         if ( this.isClippedHorizontally() || this.isFloatableOutOfView() ) {
2210                                 // Anchoring to the left caused the popup to clip, so anchor it to the
2211                                 // right instead.
2212                                 this.setHorizontalPosition( 'end' );
2213                         }
2214                         if ( this.isClippedHorizontally() || this.isFloatableOutOfView() ) {
2215                                 // Anchoring to the right also caused the popup to clip, so just make it fill the
2216                                 // container.
2217                                 containerWidth = this.$clippableScrollableContainer.width();
2218                                 containerLeft = this.$clippableScrollableContainer[ 0 ] ===
2219                                         document.documentElement ?
2220                                         0 :
2221                                         this.$clippableScrollableContainer.offset().left;
2222
2223                                 this.toggleClipping( false );
2224                                 this.setHorizontalPosition( 'start' );
2225
2226                                 this.$clippable.css( {
2227                                         'margin-left': -( this.$element.offset().left - containerLeft ),
2228                                         width: containerWidth
2229                                 } );
2230                         }
2231                 } else {
2232                         this.getElementDocument().removeEventListener(
2233                                 'mouseup',
2234                                 this.onPopupDocumentMouseKeyUpHandler,
2235                                 true
2236                         );
2237                         this.getElementDocument().removeEventListener(
2238                                 'keyup',
2239                                 this.onPopupDocumentMouseKeyUpHandler,
2240                                 true
2241                         );
2242                         this.$element.removeClass( 'oo-ui-popupToolGroup-active' );
2243                         this.$group.removeClass( 'oo-ui-popupToolGroup-active-tools' );
2244                         this.togglePositioning( false );
2245                         this.toggleClipping( false );
2246                 }
2247                 this.emit( 'active', this.active );
2248                 this.updateThemeClasses();
2249         }
2250 };
2251
2252 /**
2253  * ListToolGroups are one of three types of {@link OO.ui.ToolGroup toolgroups} that are used to
2254  * create {@link OO.ui.Toolbar toolbars} (the other types of groups are
2255  * {@link OO.ui.MenuToolGroup MenuToolGroup} and {@link OO.ui.BarToolGroup BarToolGroup}).
2256  * The {@link OO.ui.Tool tools} in a ListToolGroup are displayed by label in a dropdown menu.
2257  * The title of the tool is used as the label text. The menu itself can be configured with a label,
2258  * icon, indicator, header, and title.
2259  *
2260  * ListToolGroups can be configured to be expanded and collapsed. Collapsed lists will have a
2261  * ‘More’ option that users can select to see the full list of tools. If a collapsed toolgroup is
2262  * expanded, a ‘Fewer’ option permits users to collapse the list again.
2263  *
2264  * ListToolGroups are created by a {@link OO.ui.ToolGroupFactory toolgroup factory} when the
2265  * toolbar is set up. The factory requires the ListToolGroup's symbolic name, 'list', which is
2266  * specified along with the other configurations. For more information about how to add tools to a
2267  * ListToolGroup, please see {@link OO.ui.ToolGroup toolgroup}.
2268  *
2269  *     @example
2270  *     // Example of a ListToolGroup
2271  *     var toolFactory = new OO.ui.ToolFactory();
2272  *     var toolGroupFactory = new OO.ui.ToolGroupFactory();
2273  *     var toolbar = new OO.ui.Toolbar( toolFactory, toolGroupFactory );
2274  *
2275  *     // Configure and register two tools
2276  *     function SettingsTool() {
2277  *         SettingsTool.parent.apply( this, arguments );
2278  *     }
2279  *     OO.inheritClass( SettingsTool, OO.ui.Tool );
2280  *     SettingsTool.static.name = 'settings';
2281  *     SettingsTool.static.icon = 'settings';
2282  *     SettingsTool.static.title = 'Change settings';
2283  *     SettingsTool.prototype.onSelect = function () {
2284  *         this.setActive( false );
2285  *     };
2286  *     SettingsTool.prototype.onUpdateState = function () {};
2287  *     toolFactory.register( SettingsTool );
2288  *     // Register two more tools, nothing interesting here
2289  *     function StuffTool() {
2290  *         StuffTool.parent.apply( this, arguments );
2291  *     }
2292  *     OO.inheritClass( StuffTool, OO.ui.Tool );
2293  *     StuffTool.static.name = 'stuff';
2294  *     StuffTool.static.icon = 'search';
2295  *     StuffTool.static.title = 'Change the world';
2296  *     StuffTool.prototype.onSelect = function () {
2297  *         this.setActive( false );
2298  *     };
2299  *     StuffTool.prototype.onUpdateState = function () {};
2300  *     toolFactory.register( StuffTool );
2301  *     toolbar.setup( [
2302  *         {
2303  *             // Configurations for list toolgroup.
2304  *             type: 'list',
2305  *             label: 'ListToolGroup',
2306  *             icon: 'ellipsis',
2307  *             title: 'This is the title, displayed when user moves the mouse over the list ' +
2308  *                 'toolgroup',
2309  *             header: 'This is the header',
2310  *             include: [ 'settings', 'stuff' ],
2311  *             allowCollapse: ['stuff']
2312  *         }
2313  *     ] );
2314  *
2315  *     // Create some UI around the toolbar and place it in the document
2316  *     var frame = new OO.ui.PanelLayout( {
2317  *         expanded: false,
2318  *         framed: true
2319  *     } );
2320  *     frame.$element.append(
2321  *         toolbar.$element
2322  *     );
2323  *     $( document.body ).append( frame.$element );
2324  *     // Build the toolbar. This must be done after the toolbar has been appended to the document.
2325  *     toolbar.initialize();
2326  *
2327  * For more information about toolbars in general, please see the
2328  * [OOUI documentation on MediaWiki][1].
2329  *
2330  * [1]: https://www.mediawiki.org/wiki/OOUI/Toolbars
2331  *
2332  * @class
2333  * @extends OO.ui.PopupToolGroup
2334  *
2335  * @constructor
2336  * @param {OO.ui.Toolbar} toolbar
2337  * @param {Object} [config] Configuration options
2338  * @cfg {Array} [allowCollapse] Allow the specified tools to be collapsed. By default, collapsible
2339  *  tools will only be displayed if users click the ‘More’ option displayed at the bottom of the
2340  *  list. If the list is expanded, a ‘Fewer’ option permits users to collapse the list again.
2341  *  Any tools that are included in the toolgroup, but are not designated as collapsible, will always
2342  *  be displayed.
2343  *  To open a collapsible list in its expanded state, set #expanded to 'true'.
2344  * @cfg {Array} [forceExpand] Expand the specified tools. All other tools will be designated as
2345  *  collapsible. Unless #expanded is set to true, the collapsible tools will be collapsed when the
2346  *  list is first opened.
2347  * @cfg {boolean} [expanded=false] Expand collapsible tools. This config is only relevant if tools
2348  *  have been designated as collapsible. When expanded is set to true, all tools in the group will
2349  *  be displayed when the list is first opened. Users can collapse the list with a ‘Fewer’ option at
2350  *  the bottom.
2351  */
2352 OO.ui.ListToolGroup = function OoUiListToolGroup( toolbar, config ) {
2353         // Allow passing positional parameters inside the config object
2354         if ( OO.isPlainObject( toolbar ) && config === undefined ) {
2355                 config = toolbar;
2356                 toolbar = config.toolbar;
2357         }
2358
2359         // Configuration initialization
2360         config = config || {};
2361
2362         // Properties (must be set before parent constructor, which calls #populate)
2363         this.allowCollapse = config.allowCollapse;
2364         this.forceExpand = config.forceExpand;
2365         this.expanded = config.expanded !== undefined ? config.expanded : false;
2366         this.collapsibleTools = [];
2367
2368         // Parent constructor
2369         OO.ui.ListToolGroup.parent.call( this, toolbar, config );
2370
2371         // Initialization
2372         this.$element.addClass( 'oo-ui-listToolGroup' );
2373         this.$group.addClass( 'oo-ui-listToolGroup-tools' );
2374 };
2375
2376 /* Setup */
2377
2378 OO.inheritClass( OO.ui.ListToolGroup, OO.ui.PopupToolGroup );
2379
2380 /* Static Properties */
2381
2382 /**
2383  * @static
2384  * @inheritdoc
2385  */
2386 OO.ui.ListToolGroup.static.name = 'list';
2387
2388 /* Methods */
2389
2390 /**
2391  * @inheritdoc
2392  */
2393 OO.ui.ListToolGroup.prototype.populate = function () {
2394         var i, len, allowCollapse = [];
2395
2396         OO.ui.ListToolGroup.parent.prototype.populate.call( this );
2397
2398         // Update the list of collapsible tools
2399         if ( this.allowCollapse !== undefined ) {
2400                 allowCollapse = this.allowCollapse;
2401         } else if ( this.forceExpand !== undefined ) {
2402                 allowCollapse = OO.simpleArrayDifference( Object.keys( this.tools ), this.forceExpand );
2403         }
2404
2405         this.collapsibleTools = [];
2406         for ( i = 0, len = allowCollapse.length; i < len; i++ ) {
2407                 if ( this.tools[ allowCollapse[ i ] ] !== undefined ) {
2408                         this.collapsibleTools.push( this.tools[ allowCollapse[ i ] ] );
2409                 }
2410         }
2411
2412         // Keep at the end, even when tools are added
2413         this.$group.append( this.getExpandCollapseTool().$element );
2414
2415         this.getExpandCollapseTool().toggle( this.collapsibleTools.length !== 0 );
2416         this.updateCollapsibleState();
2417 };
2418
2419 /**
2420  * Get the expand/collapse tool for this group
2421  *
2422  * @return {OO.ui.Tool} Expand collapse tool
2423  */
2424 OO.ui.ListToolGroup.prototype.getExpandCollapseTool = function () {
2425         var ExpandCollapseTool;
2426         if ( this.expandCollapseTool === undefined ) {
2427                 ExpandCollapseTool = function () {
2428                         ExpandCollapseTool.parent.apply( this, arguments );
2429                 };
2430
2431                 OO.inheritClass( ExpandCollapseTool, OO.ui.Tool );
2432
2433                 ExpandCollapseTool.prototype.onSelect = function () {
2434                         this.toolGroup.expanded = !this.toolGroup.expanded;
2435                         this.toolGroup.updateCollapsibleState();
2436                         this.setActive( false );
2437                 };
2438                 ExpandCollapseTool.prototype.onUpdateState = function () {
2439                         // Do nothing. Tool interface requires an implementation of this function.
2440                 };
2441
2442                 ExpandCollapseTool.static.name = 'more-fewer';
2443
2444                 this.expandCollapseTool = new ExpandCollapseTool( this );
2445         }
2446         return this.expandCollapseTool;
2447 };
2448
2449 /**
2450  * @inheritdoc
2451  */
2452 OO.ui.ListToolGroup.prototype.onMouseKeyUp = function ( e ) {
2453         // Do not close the popup when the user wants to show more/fewer tools
2454         if (
2455                 $( e.target ).closest( '.oo-ui-tool-name-more-fewer' ).length && (
2456                         e.which === OO.ui.MouseButtons.LEFT ||
2457                         e.which === OO.ui.Keys.SPACE ||
2458                         e.which === OO.ui.Keys.ENTER
2459                 )
2460         ) {
2461                 // HACK: Prevent the popup list from being hidden. Skip the PopupToolGroup implementation
2462                 // (which hides the popup list when a tool is selected) and call ToolGroup's implementation
2463                 // directly.
2464                 return OO.ui.ListToolGroup.parent.parent.prototype.onMouseKeyUp.call( this, e );
2465         } else {
2466                 return OO.ui.ListToolGroup.parent.prototype.onMouseKeyUp.call( this, e );
2467         }
2468 };
2469
2470 OO.ui.ListToolGroup.prototype.updateCollapsibleState = function () {
2471         var i, icon, len;
2472
2473         if ( this.toolbar.position !== 'bottom' ) {
2474                 icon = this.expanded ? 'collapse' : 'expand';
2475         } else {
2476                 icon = this.expanded ? 'expand' : 'collapse';
2477         }
2478
2479         this.getExpandCollapseTool()
2480                 .setIcon( icon )
2481                 .setTitle( OO.ui.msg( this.expanded ? 'ooui-toolgroup-collapse' : 'ooui-toolgroup-expand' ) );
2482
2483         for ( i = 0, len = this.collapsibleTools.length; i < len; i++ ) {
2484                 this.collapsibleTools[ i ].toggle( this.expanded );
2485         }
2486
2487         // Re-evaluate clipping, because our height has changed
2488         this.clip();
2489 };
2490
2491 /**
2492  * MenuToolGroups are one of three types of {@link OO.ui.ToolGroup toolgroups} that are used to
2493  * create {@link OO.ui.Toolbar toolbars} (the other types of groups are
2494  * {@link OO.ui.BarToolGroup BarToolGroup} and {@link OO.ui.ListToolGroup ListToolGroup}).
2495  * MenuToolGroups contain selectable {@link OO.ui.Tool tools}, which are displayed by label in a
2496  * dropdown menu. The tool's title is used as the label text, and the menu label is updated to
2497  * reflect which tool or tools are currently selected. If no tools are selected, the menu label
2498  * is empty. The menu can be configured with an indicator, icon, title, and/or header.
2499  *
2500  * MenuToolGroups are created by a {@link OO.ui.ToolGroupFactory tool group factory} when the
2501  * toolbar is set up.
2502  *
2503  *     @example
2504  *     // Example of a MenuToolGroup
2505  *     var toolFactory = new OO.ui.ToolFactory();
2506  *     var toolGroupFactory = new OO.ui.ToolGroupFactory();
2507  *     var toolbar = new OO.ui.Toolbar( toolFactory, toolGroupFactory );
2508  *
2509  *     // We will be placing status text in this element when tools are used
2510  *     var $area = $( '<p>' ).text( 'An example of a MenuToolGroup. Select a tool from the '
2511  *         + 'dropdown menu.' );
2512  *
2513  *     // Define the tools that we're going to place in our toolbar
2514  *
2515  *     function SettingsTool() {
2516  *         SettingsTool.parent.apply( this, arguments );
2517  *         this.reallyActive = false;
2518  *     }
2519  *     OO.inheritClass( SettingsTool, OO.ui.Tool );
2520  *     SettingsTool.static.name = 'settings';
2521  *     SettingsTool.static.icon = 'settings';
2522  *     SettingsTool.static.title = 'Change settings';
2523  *     SettingsTool.prototype.onSelect = function () {
2524  *         $area.text( 'Settings tool clicked!' );
2525  *         // Toggle the active state on each click
2526  *         this.reallyActive = !this.reallyActive;
2527  *         this.setActive( this.reallyActive );
2528  *         // To update the menu label
2529  *         this.toolbar.emit( 'updateState' );
2530  *     };
2531  *     SettingsTool.prototype.onUpdateState = function () {};
2532  *     toolFactory.register( SettingsTool );
2533  *
2534  *     function StuffTool() {
2535  *         StuffTool.parent.apply( this, arguments );
2536  *         this.reallyActive = false;
2537  *     }
2538  *     OO.inheritClass( StuffTool, OO.ui.Tool );
2539  *     StuffTool.static.name = 'stuff';
2540  *     StuffTool.static.icon = 'ellipsis';
2541  *     StuffTool.static.title = 'More stuff';
2542  *     StuffTool.prototype.onSelect = function () {
2543  *         $area.text( 'More stuff tool clicked!' );
2544  *         // Toggle the active state on each click
2545  *         this.reallyActive = !this.reallyActive;
2546  *         this.setActive( this.reallyActive );
2547  *         // To update the menu label
2548  *         this.toolbar.emit( 'updateState' );
2549  *     };
2550  *     StuffTool.prototype.onUpdateState = function () {};
2551  *     toolFactory.register( StuffTool );
2552  *
2553  *     // Finally define which tools and in what order appear in the toolbar. Each tool may only be
2554  *     // used once (but not all defined tools must be used).
2555  *     toolbar.setup( [
2556  *         {
2557  *             type: 'menu',
2558  *             header: 'This is the (optional) header',
2559  *             title: 'This is the (optional) title',
2560  *             include: [ 'settings', 'stuff' ]
2561  *         }
2562  *     ] );
2563  *
2564  *     // Create some UI around the toolbar and place it in the document
2565  *     var frame = new OO.ui.PanelLayout( {
2566  *         expanded: false,
2567  *         framed: true
2568  *     } );
2569  *     var contentFrame = new OO.ui.PanelLayout( {
2570  *         expanded: false,
2571  *         padded: true
2572  *     } );
2573  *     frame.$element.append(
2574  *         toolbar.$element,
2575  *         contentFrame.$element.append( $area )
2576  *     );
2577  *     $( document.body ).append( frame.$element );
2578  *
2579  *     // Here is where the toolbar is actually built. This must be done after inserting it into the
2580  *     // document.
2581  *     toolbar.initialize();
2582  *     toolbar.emit( 'updateState' );
2583  *
2584  * For more information about how to add tools to a MenuToolGroup, please see
2585  * {@link OO.ui.ToolGroup toolgroup}.
2586  * For more information about toolbars in general, please see the
2587  * [OOUI documentation on MediaWiki] [1].
2588  *
2589  * [1]: https://www.mediawiki.org/wiki/OOUI/Toolbars
2590  *
2591  * @class
2592  * @extends OO.ui.PopupToolGroup
2593  *
2594  * @constructor
2595  * @param {OO.ui.Toolbar} toolbar
2596  * @param {Object} [config] Configuration options
2597  */
2598 OO.ui.MenuToolGroup = function OoUiMenuToolGroup( toolbar, config ) {
2599         // Allow passing positional parameters inside the config object
2600         if ( OO.isPlainObject( toolbar ) && config === undefined ) {
2601                 config = toolbar;
2602                 toolbar = config.toolbar;
2603         }
2604
2605         // Configuration initialization
2606         config = config || {};
2607
2608         // Parent constructor
2609         OO.ui.MenuToolGroup.parent.call( this, toolbar, config );
2610
2611         // Events
2612         this.toolbar.connect( this, {
2613                 updateState: 'onUpdateState'
2614         } );
2615
2616         // Initialization
2617         this.$element.addClass( 'oo-ui-menuToolGroup' );
2618         this.$group.addClass( 'oo-ui-menuToolGroup-tools' );
2619 };
2620
2621 /* Setup */
2622
2623 OO.inheritClass( OO.ui.MenuToolGroup, OO.ui.PopupToolGroup );
2624
2625 /* Static Properties */
2626
2627 /**
2628  * @static
2629  * @inheritdoc
2630  */
2631 OO.ui.MenuToolGroup.static.name = 'menu';
2632
2633 /* Methods */
2634
2635 /**
2636  * Handle the toolbar state being updated.
2637  *
2638  * When the state changes, the title of each active item in the menu will be joined together and
2639  * used as a label for the group. The label will be empty if none of the items are active.
2640  *
2641  * @private
2642  */
2643 OO.ui.MenuToolGroup.prototype.onUpdateState = function () {
2644         var name,
2645                 labelTexts = [];
2646
2647         for ( name in this.tools ) {
2648                 if ( this.tools[ name ].isActive() ) {
2649                         labelTexts.push( this.tools[ name ].getTitle() );
2650                 }
2651         }
2652
2653         this.setLabel( labelTexts.join( ', ' ) || ' ' );
2654 };
2655
2656 }( OO ) );
2657
2658 //# sourceMappingURL=oojs-ui-toolbars.js.map.json