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

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