diff options
Diffstat (limited to 'vendor/oojs/oojs-ui/src/elements/IconElement.js')
-rw-r--r-- | vendor/oojs/oojs-ui/src/elements/IconElement.js | 187 |
1 files changed, 187 insertions, 0 deletions
diff --git a/vendor/oojs/oojs-ui/src/elements/IconElement.js b/vendor/oojs/oojs-ui/src/elements/IconElement.js new file mode 100644 index 00000000..e3cf2f2a --- /dev/null +++ b/vendor/oojs/oojs-ui/src/elements/IconElement.js @@ -0,0 +1,187 @@ +/** + * 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.IconElement = function OoUiIconElement( 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.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.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.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.IconElement.prototype.setIconElement = function ( $icon ) { + if ( 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 ); + if ( this.iconTitle !== null ) { + this.$icon.attr( 'title', this.iconTitle ); + } +}; + +/** + * 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.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 ) { + if ( 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.IconElement.prototype.setIconTitle = function ( iconTitle ) { + iconTitle = typeof iconTitle === 'function' || + ( typeof iconTitle === 'string' && iconTitle.length ) ? + OO.ui.resolveMsg( iconTitle ) : null; + + if ( 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.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.IconElement.prototype.getIconTitle = function () { + return this.iconTitle; +}; |