diff options
Diffstat (limited to 'vendor/oojs/oojs-ui/src/elements/IndicatorElement.js')
-rw-r--r-- | vendor/oojs/oojs-ui/src/elements/IndicatorElement.js | 168 |
1 files changed, 168 insertions, 0 deletions
diff --git a/vendor/oojs/oojs-ui/src/elements/IndicatorElement.js b/vendor/oojs/oojs-ui/src/elements/IndicatorElement.js new file mode 100644 index 00000000..5c6294d2 --- /dev/null +++ b/vendor/oojs/oojs-ui/src/elements/IndicatorElement.js @@ -0,0 +1,168 @@ +/** + * IndicatorElement is often mixed into other classes to generate an indicator. + * Indicators are small graphics that are generally used in two ways: + * + * - To draw attention to the status of an item. For example, an indicator might be + * used to show that an item in a list has errors that need to be resolved. + * - To clarify the function of a control that acts in an exceptional way (a button + * that opens a menu instead of performing an action directly, for example). + * + * For a list of indicators included in the library, please see the + * [OOjs UI documentation on MediaWiki] [1]. + * + * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Indicators + * + * @abstract + * @class + * + * @constructor + * @param {Object} [config] Configuration options + * @cfg {jQuery} [$indicator] The indicator element created by the class. If this + * configuration is omitted, the indicator element will use a generated `<span>`. + * @cfg {string} [indicator] Symbolic name of the indicator (e.g., ‘alert’ or ‘down’). + * See the [OOjs UI documentation on MediaWiki][2] for a list of indicators included + * in the library. + * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Indicators + * @cfg {string|Function} [indicatorTitle] A text string used as the indicator title, + * or a function that returns title text. The indicator title is displayed when users move + * the mouse over the indicator. + */ +OO.ui.IndicatorElement = function OoUiIndicatorElement( config ) { + // Configuration initialization + config = config || {}; + + // Properties + this.$indicator = null; + this.indicator = null; + this.indicatorTitle = null; + + // Initialization + this.setIndicator( config.indicator || this.constructor.static.indicator ); + this.setIndicatorTitle( config.indicatorTitle || this.constructor.static.indicatorTitle ); + this.setIndicatorElement( config.$indicator || $( '<span>' ) ); +}; + +/* Setup */ + +OO.initClass( OO.ui.IndicatorElement ); + +/* Static Properties */ + +/** + * Symbolic name of the indicator (e.g., ‘alert’ or ‘down’). + * The static property will be overridden if the #indicator configuration is used. + * + * @static + * @inheritable + * @property {string|null} + */ +OO.ui.IndicatorElement.static.indicator = null; + +/** + * A text string used as the indicator title, a function that returns title text, or `null` + * for no title. The static property will be overridden if the #indicatorTitle configuration is used. + * + * @static + * @inheritable + * @property {string|Function|null} + */ +OO.ui.IndicatorElement.static.indicatorTitle = null; + +/* Methods */ + +/** + * Set the indicator element. + * + * If an element is already set, it will be cleaned up before setting up the new element. + * + * @param {jQuery} $indicator Element to use as indicator + */ +OO.ui.IndicatorElement.prototype.setIndicatorElement = function ( $indicator ) { + if ( this.$indicator ) { + this.$indicator + .removeClass( 'oo-ui-indicatorElement-indicator oo-ui-indicator-' + this.indicator ) + .removeAttr( 'title' ); + } + + this.$indicator = $indicator + .addClass( 'oo-ui-indicatorElement-indicator' ) + .toggleClass( 'oo-ui-indicator-' + this.indicator, !!this.indicator ); + if ( this.indicatorTitle !== null ) { + this.$indicator.attr( 'title', this.indicatorTitle ); + } +}; + +/** + * Set the indicator by its symbolic name: ‘alert’, ‘down’, ‘next’, ‘previous’, ‘required’, ‘up’. Use `null` to remove the indicator. + * + * @param {string|null} indicator Symbolic name of indicator, or `null` for no indicator + * @chainable + */ +OO.ui.IndicatorElement.prototype.setIndicator = function ( indicator ) { + indicator = typeof indicator === 'string' && indicator.length ? indicator.trim() : null; + + if ( this.indicator !== indicator ) { + if ( this.$indicator ) { + if ( this.indicator !== null ) { + this.$indicator.removeClass( 'oo-ui-indicator-' + this.indicator ); + } + if ( indicator !== null ) { + this.$indicator.addClass( 'oo-ui-indicator-' + indicator ); + } + } + this.indicator = indicator; + } + + this.$element.toggleClass( 'oo-ui-indicatorElement', !!this.indicator ); + this.updateThemeClasses(); + + return this; +}; + +/** + * Set the indicator title. + * + * The title is displayed when a user moves the mouse over the indicator. + * + * @param {string|Function|null} indicator Indicator title text, a function that returns text, or + * `null` for no indicator title + * @chainable + */ +OO.ui.IndicatorElement.prototype.setIndicatorTitle = function ( indicatorTitle ) { + indicatorTitle = typeof indicatorTitle === 'function' || + ( typeof indicatorTitle === 'string' && indicatorTitle.length ) ? + OO.ui.resolveMsg( indicatorTitle ) : null; + + if ( this.indicatorTitle !== indicatorTitle ) { + this.indicatorTitle = indicatorTitle; + if ( this.$indicator ) { + if ( this.indicatorTitle !== null ) { + this.$indicator.attr( 'title', indicatorTitle ); + } else { + this.$indicator.removeAttr( 'title' ); + } + } + } + + return this; +}; + +/** + * Get the symbolic name of the indicator (e.g., ‘alert’ or ‘down’). + * + * @return {string} Symbolic name of indicator + */ +OO.ui.IndicatorElement.prototype.getIndicator = function () { + return this.indicator; +}; + +/** + * Get the indicator title. + * + * The title is displayed when a user moves the mouse over the indicator. + * + * @return {string} Indicator title text + */ +OO.ui.IndicatorElement.prototype.getIndicatorTitle = function () { + return this.indicatorTitle; +}; |