# all files / src/toolgroups/ MenuToolGroup.js

25% Statements 4/16
0% Branches 0/10
0% Functions 0/2
25% Lines 4/16

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    154
    155
    156
    157
    158

    1×

    1×

    1×

    1×

     /**
     * MenuToolGroups are one of three types of {@link OO.ui.ToolGroup toolgroups} that are used to
     * create {@link OO.ui.Toolbar toolbars} (the other types of groups are {@link OO.ui.BarToolGroup BarToolGroup}
     * and {@link OO.ui.ListToolGroup ListToolGroup}). MenuToolGroups contain selectable {@link OO.ui.Tool tools},
     * which are displayed by label in a dropdown menu. The tool's title is used as the label text, and the
     * menu label is updated to reflect which tool or tools are currently selected. If no tools are selected,
     * the menu label is empty. The menu can be configured with an indicator, icon, title, and/or header.
     *
     * MenuToolGroups are created by a {@link OO.ui.ToolGroupFactory tool group factory} when the toolbar
     * is set up.
     *
     *     @example
     *     // Example of a MenuToolGroup
     *     var toolFactory = new OO.ui.ToolFactory();
     *     var toolGroupFactory = new OO.ui.ToolGroupFactory();
     *     var toolbar = new OO.ui.Toolbar( toolFactory, toolGroupFactory );
     *
     *     // We will be placing status text in this element when tools are used
     *     var $area = $( '<p>' ).text( 'An example of a MenuToolGroup. Select a tool from the dropdown menu.' );
     *
     *     // Define the tools that we're going to place in our toolbar
     *
     *     function SettingsTool() {
     *         SettingsTool.parent.apply( this, arguments );
     *         this.reallyActive = false;
     *     }
     *     OO.inheritClass( SettingsTool, OO.ui.Tool );
     *     SettingsTool.static.name = 'settings';
     *     SettingsTool.static.icon = 'settings';
     *     SettingsTool.static.title = 'Change settings';
     *     SettingsTool.prototype.onSelect = function () {
     *         $area.text( 'Settings tool clicked!' );
     *         // Toggle the active state on each click
     *         this.reallyActive = !this.reallyActive;
     *         this.setActive( this.reallyActive );
     *         // To update the menu label
     *         this.toolbar.emit( 'updateState' );
     *     };
     *     SettingsTool.prototype.onUpdateState = function () {};
     *     toolFactory.register( SettingsTool );
     *
     *     function StuffTool() {
     *         StuffTool.parent.apply( this, arguments );
     *         this.reallyActive = false;
     *     }
     *     OO.inheritClass( StuffTool, OO.ui.Tool );
     *     StuffTool.static.name = 'stuff';
     *     StuffTool.static.icon = 'ellipsis';
     *     StuffTool.static.title = 'More stuff';
     *     StuffTool.prototype.onSelect = function () {
     *         $area.text( 'More stuff tool clicked!' );
     *         // Toggle the active state on each click
     *         this.reallyActive = !this.reallyActive;
     *         this.setActive( this.reallyActive );
     *         // To update the menu label
     *         this.toolbar.emit( 'updateState' );
     *     };
     *     StuffTool.prototype.onUpdateState = function () {};
     *     toolFactory.register( StuffTool );
     *
     *     // Finally define which tools and in what order appear in the toolbar. Each tool may only be
     *     // used once (but not all defined tools must be used).
     *     toolbar.setup( [
     *         {
     *             type: 'menu',
     *             header: 'This is the (optional) header',
     *             title: 'This is the (optional) title',
     *             include: [ 'settings', 'stuff' ]
     *         }
     *     ] );
     *
     *     // Create some UI around the toolbar and place it in the document
     *     var frame = new OO.ui.PanelLayout( {
     *         expanded: false,
     *         framed: true
     *     } );
     *     var contentFrame = new OO.ui.PanelLayout( {
     *         expanded: false,
     *         padded: true
     *     } );
     *     frame.$element.append(
     *         toolbar.$element,
     *         contentFrame.$element.append( $area )
     *     );
     *     $( 'body' ).append( frame.$element );
     *
     *     // Here is where the toolbar is actually built. This must be done after inserting it into the
     *     // document.
     *     toolbar.initialize();
     *     toolbar.emit( 'updateState' );
     *
     * For more information about how to add tools to a MenuToolGroup, please see {@link OO.ui.ToolGroup toolgroup}.
     * For more information about toolbars in general, please see the [OOjs UI documentation on MediaWiki] [1].
     *
     * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Toolbars
     *
     * @class
     * @extends OO.ui.PopupToolGroup
     *
     * @constructor
     * @param {OO.ui.Toolbar} toolbar
     * @param {Object} [config] Configuration options
     */
    OO.ui.MenuToolGroup = function OoUiMenuToolGroup( toolbar, config ) {
    	// Allow passing positional parameters inside the config object
    	if ( OO.isPlainObject( toolbar ) && config === undefined ) {
    		config = toolbar;
    		toolbar = config.toolbar;
    	}

    	// Configuration initialization
    	config = config || {};

    	// Parent constructor
    	OO.ui.MenuToolGroup.parent.call( this, toolbar, config );

    	// Events
    	this.toolbar.connect( this, { updateState: 'onUpdateState' } );

    	// Initialization
    	this.$element.addClass( 'oo-ui-menuToolGroup' );
    };

    /* Setup */

    OO.inheritClass( OO.ui.MenuToolGroup, OO.ui.PopupToolGroup );

    /* Static Properties */

    /**
     * @static
     * @inheritdoc
     */
    OO.ui.MenuToolGroup.static.name = 'menu';

    /* Methods */

    /**
     * Handle the toolbar state being updated.
     *
     * When the state changes, the title of each active item in the menu will be joined together and
     * used as a label for the group. The label will be empty if none of the items are active.
     *
     * @private
     */
    OO.ui.MenuToolGroup.prototype.onUpdateState = function () {
    	var name,
    		labelTexts = [];

    	for ( name in this.tools ) {
    		if ( this.tools[ name ].isActive() ) {
    			labelTexts.push( this.tools[ name ].getTitle() );
    		}
    	}

    	this.setLabel( labelTexts.join( ', ' ) || ' ' );
    };