# all files / src/mixins/ IconElement.js

70.45% Statements 31/44
56.76% Branches 21/37
66.67% Functions 4/6
70.45% Lines 31/44

    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
    159
    160
    161
    162
    163
    164
    165
    166
    167
    168
    169
    170
    171
    172
    173
    174
    175
    176
    177
    178
    179
    180
    181
    182
    183
    184
    185
    186
    187
    188
    189
    190

    1×

    25696×

    25696×
    25696×
    25696×

    25696×
    25696×
    25696×

    1×

    1×

    1×

    1×
    25696×

    25696×

    25696×

    25696×

    1×
    25696×
    25696×

    25696×
    2600×

    2600×

    25696×
    25696×

    25696×

    1×
    25696×

    25696×

    25696×

    1×

    1×

     /**
     * IconElement is often mixed into other classes to generate an icon.
     * Icons are graphics, about the size of normal text. They are used to aid the user
     * in locating a control or to convey information in a space-efficient way. See the
     * [OOjs UI documentation on MediaWiki] [1] for a list of icons
     * included in the library.
     *
     * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Icons
     *
     * @abstract
     * @class
     *
     * @constructor
     * @param {Object} [config] Configuration options
     * @cfg {jQuery} [$icon] The icon element created by the class. If this configuration is omitted,
     *  the icon element will use a generated `<span>`. To use a different HTML tag, or to specify that
     *  the icon element be set to an existing icon instead of the one generated by this class, set a
     *  value using a jQuery selection. For example:
     *
     *      // Use a <div> tag instead of a <span>
     *     $icon: $("<div>")
     *     // Use an existing icon element instead of the one generated by the class
     *     $icon: this.$element
     *     // Use an icon element from a child widget
     *     $icon: this.childwidget.$element
     * @cfg {Object|string} [icon=''] The symbolic name of the icon (e.g., ‘remove’ or ‘menu’), or a map of
     *  symbolic names.  A map is used for i18n purposes and contains a `default` icon
     *  name and additional names keyed by language code. The `default` name is used when no icon is keyed
     *  by the user's language.
     *
     *  Example of an i18n map:
     *
     *     { default: 'bold-a', en: 'bold-b', de: 'bold-f' }
     *  See the [OOjs UI documentation on MediaWiki] [2] for a list of icons included in the library.
     * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Icons
     * @cfg {string|Function} [iconTitle] A text string used as the icon title, or a function that returns title
     *  text. The icon title is displayed when users move the mouse over the icon.
     */
    OO.ui.mixin.IconElement = function OoUiMixinIconElement( config ) {
    	// Configuration initialization
    	config = config || {};

    	// Properties
    	this.$icon = null;
    	this.icon = null;
    	this.iconTitle = null;

    	// Initialization
    	this.setIcon( config.icon || this.constructor.static.icon );
    	this.setIconTitle( config.iconTitle || this.constructor.static.iconTitle );
    	this.setIconElement( config.$icon || $( '<span>' ) );
    };

    /* Setup */

    OO.initClass( OO.ui.mixin.IconElement );

    /* Static Properties */

    /**
     * The symbolic name of the icon (e.g., ‘remove’ or ‘menu’), or a map of symbolic names. A map is used
     * for i18n purposes and contains a `default` icon name and additional names keyed by
     * language code. The `default` name is used when no icon is keyed by the user's language.
     *
     * Example of an i18n map:
     *
     *     { default: 'bold-a', en: 'bold-b', de: 'bold-f' }
     *
     * Note: the static property will be overridden if the #icon configuration is used.
     *
     * @static
     * @inheritable
     * @property {Object|string}
     */
    OO.ui.mixin.IconElement.static.icon = null;

    /**
     * The icon title, displayed when users move the mouse over the icon. The value can be text, a
     * function that returns title text, or `null` for no title.
     *
     * The static property will be overridden if the #iconTitle configuration is used.
     *
     * @static
     * @inheritable
     * @property {string|Function|null}
     */
    OO.ui.mixin.IconElement.static.iconTitle = null;

    /* Methods */

    /**
     * Set the icon element. This method is used to retarget an icon mixin so that its functionality
     * applies to the specified icon element instead of the one created by the class. If an icon
     * element is already set, the mixin’s effect on that element is removed. Generated CSS classes
     * and mixin methods will no longer affect the element.
     *
     * @param {jQuery} $icon Element to use as icon
     */
    OO.ui.mixin.IconElement.prototype.setIconElement = function ( $icon ) {
    	Iif ( this.$icon ) {
    		this.$icon
    			.removeClass( 'oo-ui-iconElement-icon oo-ui-icon-' + this.icon )
    			.removeAttr( 'title' );
    	}

    	this.$icon = $icon
    		.addClass( 'oo-ui-iconElement-icon' )
    		.toggleClass( 'oo-ui-icon-' + this.icon, !!this.icon );
    	Iif ( this.iconTitle !== null ) {
    		this.$icon.attr( 'title', this.iconTitle );
    	}

    	this.updateThemeClasses();
    };

    /**
     * Set icon by symbolic name (e.g., ‘remove’ or ‘menu’). Use `null` to remove an icon.
     * The icon parameter can also be set to a map of icon names. See the #icon config setting
     * for an example.
     *
     * @param {Object|string|null} icon A symbolic icon name, a {@link #icon map of icon names} keyed
     *  by language code, or `null` to remove the icon.
     * @chainable
     */
    OO.ui.mixin.IconElement.prototype.setIcon = function ( icon ) {
    	icon = OO.isPlainObject( icon ) ? OO.ui.getLocalValue( icon, null, 'default' ) : icon;
    	icon = typeof icon === 'string' && icon.trim().length ? icon.trim() : null;

    	if ( this.icon !== icon ) {
    		Iif ( this.$icon ) {
    			if ( this.icon !== null ) {
    				this.$icon.removeClass( 'oo-ui-icon-' + this.icon );
    			}
    			if ( icon !== null ) {
    				this.$icon.addClass( 'oo-ui-icon-' + icon );
    			}
    		}
    		this.icon = icon;
    	}

    	this.$element.toggleClass( 'oo-ui-iconElement', !!this.icon );
    	this.updateThemeClasses();

    	return this;
    };

    /**
     * Set the icon title. Use `null` to remove the title.
     *
     * @param {string|Function|null} iconTitle A text string used as the icon title,
     *  a function that returns title text, or `null` for no title.
     * @chainable
     */
    OO.ui.mixin.IconElement.prototype.setIconTitle = function ( iconTitle ) {
    	iconTitle =
    		( typeof iconTitle === 'function' || ( typeof iconTitle === 'string' && iconTitle.length ) ) ?
    			OO.ui.resolveMsg( iconTitle ) : null;

    	Iif ( this.iconTitle !== iconTitle ) {
    		this.iconTitle = iconTitle;
    		if ( this.$icon ) {
    			if ( this.iconTitle !== null ) {
    				this.$icon.attr( 'title', iconTitle );
    			} else {
    				this.$icon.removeAttr( 'title' );
    			}
    		}
    	}

    	return this;
    };

    /**
     * Get the symbolic name of the icon.
     *
     * @return {string} Icon name
     */
    OO.ui.mixin.IconElement.prototype.getIcon = function () {
    	return this.icon;
    };

    /**
     * Get the icon title. The title text is displayed when a user moves the mouse over the icon.
     *
     * @return {string} Icon title text
     */
    OO.ui.mixin.IconElement.prototype.getIconTitle = function () {
    	return this.iconTitle;
    };