diff options
author | Pierre Schmitz <pierre@archlinux.de> | 2015-06-04 07:31:04 +0200 |
---|---|---|
committer | Pierre Schmitz <pierre@archlinux.de> | 2015-06-04 07:58:39 +0200 |
commit | f6d65e533c62f6deb21342d4901ece24497b433e (patch) | |
tree | f28adf0362d14bcd448f7b65a7aaf38650f923aa /vendor/oojs/oojs-ui/src/ActionSet.js | |
parent | c27b2e832fe25651ef2410fae85b41072aae7519 (diff) |
Update to MediaWiki 1.25.1
Diffstat (limited to 'vendor/oojs/oojs-ui/src/ActionSet.js')
-rw-r--r-- | vendor/oojs/oojs-ui/src/ActionSet.js | 504 |
1 files changed, 504 insertions, 0 deletions
diff --git a/vendor/oojs/oojs-ui/src/ActionSet.js b/vendor/oojs/oojs-ui/src/ActionSet.js new file mode 100644 index 00000000..875ca605 --- /dev/null +++ b/vendor/oojs/oojs-ui/src/ActionSet.js @@ -0,0 +1,504 @@ +/** + * ActionSets manage the behavior of the {@link OO.ui.ActionWidget action widgets} that comprise them. + * Actions can be made available for specific contexts (modes) and circumstances + * (abilities). Action sets are primarily used with {@link OO.ui.Dialog Dialogs}. + * + * ActionSets contain two types of actions: + * + * - Special: Special actions are the first visible actions with special flags, such as 'safe' and 'primary', the default special flags. Additional special flags can be configured in subclasses with the static #specialFlags property. + * - Other: Other actions include all non-special visible actions. + * + * Please see the [OOjs UI documentation on MediaWiki][1] for more information. + * + * @example + * // Example: An action set used in a process dialog + * function MyProcessDialog( config ) { + * MyProcessDialog.super.call( this, config ); + * } + * OO.inheritClass( MyProcessDialog, OO.ui.ProcessDialog ); + * MyProcessDialog.static.title = 'An action set in a process dialog'; + * // An action set that uses modes ('edit' and 'help' mode, in this example). + * MyProcessDialog.static.actions = [ + * { action: 'continue', modes: 'edit', label: 'Continue', flags: [ 'primary', 'constructive' ] }, + * { action: 'help', modes: 'edit', label: 'Help' }, + * { modes: 'edit', label: 'Cancel', flags: 'safe' }, + * { action: 'back', modes: 'help', label: 'Back', flags: 'safe' } + * ]; + * + * MyProcessDialog.prototype.initialize = function () { + * MyProcessDialog.super.prototype.initialize.apply( this, arguments ); + * this.panel1 = new OO.ui.PanelLayout( { padded: true, expanded: false } ); + * this.panel1.$element.append( '<p>This dialog uses an action set (continue, help, cancel, back) configured with modes. This is edit mode. Click \'help\' to see help mode.</p>' ); + * this.panel2 = new OO.ui.PanelLayout( { padded: true, expanded: false } ); + * this.panel2.$element.append( '<p>This is help mode. Only the \'back\' action widget is configured to be visible here. Click \'back\' to return to \'edit\' mode.</p>' ); + * this.stackLayout = new OO.ui.StackLayout( { + * items: [ this.panel1, this.panel2 ] + * } ); + * this.$body.append( this.stackLayout.$element ); + * }; + * MyProcessDialog.prototype.getSetupProcess = function ( data ) { + * return MyProcessDialog.super.prototype.getSetupProcess.call( this, data ) + * .next( function () { + * this.actions.setMode( 'edit' ); + * }, this ); + * }; + * MyProcessDialog.prototype.getActionProcess = function ( action ) { + * if ( action === 'help' ) { + * this.actions.setMode( 'help' ); + * this.stackLayout.setItem( this.panel2 ); + * } else if ( action === 'back' ) { + * this.actions.setMode( 'edit' ); + * this.stackLayout.setItem( this.panel1 ); + * } else if ( action === 'continue' ) { + * var dialog = this; + * return new OO.ui.Process( function () { + * dialog.close(); + * } ); + * } + * return MyProcessDialog.super.prototype.getActionProcess.call( this, action ); + * }; + * MyProcessDialog.prototype.getBodyHeight = function () { + * return this.panel1.$element.outerHeight( true ); + * }; + * var windowManager = new OO.ui.WindowManager(); + * $( 'body' ).append( windowManager.$element ); + * var dialog = new MyProcessDialog( { + * size: 'medium' + * } ); + * windowManager.addWindows( [ dialog ] ); + * windowManager.openWindow( dialog ); + * + * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Windows/Process_Dialogs#Action_sets + * + * @abstract + * @class + * @mixins OO.EventEmitter + * + * @constructor + * @param {Object} [config] Configuration options + */ +OO.ui.ActionSet = function OoUiActionSet( config ) { + // Configuration initialization + config = config || {}; + + // Mixin constructors + OO.EventEmitter.call( this ); + + // Properties + this.list = []; + this.categories = { + actions: 'getAction', + flags: 'getFlags', + modes: 'getModes' + }; + this.categorized = {}; + this.special = {}; + this.others = []; + this.organized = false; + this.changing = false; + this.changed = false; +}; + +/* Setup */ + +OO.mixinClass( OO.ui.ActionSet, OO.EventEmitter ); + +/* Static Properties */ + +/** + * Symbolic name of the flags used to identify special actions. Special actions are displayed in the + * header of a {@link OO.ui.ProcessDialog process dialog}. + * See the [OOjs UI documentation on MediaWiki][2] for more information and examples. + * + * [2]:https://www.mediawiki.org/wiki/OOjs_UI/Windows/Process_Dialogs + * + * @abstract + * @static + * @inheritable + * @property {string} + */ +OO.ui.ActionSet.static.specialFlags = [ 'safe', 'primary' ]; + +/* Events */ + +/** + * @event click + * + * A 'click' event is emitted when an action is clicked. + * + * @param {OO.ui.ActionWidget} action Action that was clicked + */ + +/** + * @event resize + * + * A 'resize' event is emitted when an action widget is resized. + * + * @param {OO.ui.ActionWidget} action Action that was resized + */ + +/** + * @event add + * + * An 'add' event is emitted when actions are {@link #method-add added} to the action set. + * + * @param {OO.ui.ActionWidget[]} added Actions added + */ + +/** + * @event remove + * + * A 'remove' event is emitted when actions are {@link #method-remove removed} + * or {@link #clear cleared}. + * + * @param {OO.ui.ActionWidget[]} added Actions removed + */ + +/** + * @event change + * + * A 'change' event is emitted when actions are {@link #method-add added}, {@link #clear cleared}, + * or {@link #method-remove removed} from the action set or when the {@link #setMode mode} is changed. + * + */ + +/* Methods */ + +/** + * Handle action change events. + * + * @private + * @fires change + */ +OO.ui.ActionSet.prototype.onActionChange = function () { + this.organized = false; + if ( this.changing ) { + this.changed = true; + } else { + this.emit( 'change' ); + } +}; + +/** + * Check if an action is one of the special actions. + * + * @param {OO.ui.ActionWidget} action Action to check + * @return {boolean} Action is special + */ +OO.ui.ActionSet.prototype.isSpecial = function ( action ) { + var flag; + + for ( flag in this.special ) { + if ( action === this.special[ flag ] ) { + return true; + } + } + + return false; +}; + +/** + * Get action widgets based on the specified filter: ‘actions’, ‘flags’, ‘modes’, ‘visible’, + * or ‘disabled’. + * + * @param {Object} [filters] Filters to use, omit to get all actions + * @param {string|string[]} [filters.actions] Actions that action widgets must have + * @param {string|string[]} [filters.flags] Flags that action widgets must have (e.g., 'safe') + * @param {string|string[]} [filters.modes] Modes that action widgets must have + * @param {boolean} [filters.visible] Action widgets must be visible + * @param {boolean} [filters.disabled] Action widgets must be disabled + * @return {OO.ui.ActionWidget[]} Action widgets matching all criteria + */ +OO.ui.ActionSet.prototype.get = function ( filters ) { + var i, len, list, category, actions, index, match, matches; + + if ( filters ) { + this.organize(); + + // Collect category candidates + matches = []; + for ( category in this.categorized ) { + list = filters[ category ]; + if ( list ) { + if ( !Array.isArray( list ) ) { + list = [ list ]; + } + for ( i = 0, len = list.length; i < len; i++ ) { + actions = this.categorized[ category ][ list[ i ] ]; + if ( Array.isArray( actions ) ) { + matches.push.apply( matches, actions ); + } + } + } + } + // Remove by boolean filters + for ( i = 0, len = matches.length; i < len; i++ ) { + match = matches[ i ]; + if ( + ( filters.visible !== undefined && match.isVisible() !== filters.visible ) || + ( filters.disabled !== undefined && match.isDisabled() !== filters.disabled ) + ) { + matches.splice( i, 1 ); + len--; + i--; + } + } + // Remove duplicates + for ( i = 0, len = matches.length; i < len; i++ ) { + match = matches[ i ]; + index = matches.lastIndexOf( match ); + while ( index !== i ) { + matches.splice( index, 1 ); + len--; + index = matches.lastIndexOf( match ); + } + } + return matches; + } + return this.list.slice(); +}; + +/** + * Get 'special' actions. + * + * Special actions are the first visible action widgets with special flags, such as 'safe' and 'primary'. + * Special flags can be configured in subclasses by changing the static #specialFlags property. + * + * @return {OO.ui.ActionWidget[]|null} 'Special' action widgets. + */ +OO.ui.ActionSet.prototype.getSpecial = function () { + this.organize(); + return $.extend( {}, this.special ); +}; + +/** + * Get 'other' actions. + * + * Other actions include all non-special visible action widgets. + * + * @return {OO.ui.ActionWidget[]} 'Other' action widgets + */ +OO.ui.ActionSet.prototype.getOthers = function () { + this.organize(); + return this.others.slice(); +}; + +/** + * Set the mode (e.g., ‘edit’ or ‘view’). Only {@link OO.ui.ActionWidget#modes actions} configured + * to be available in the specified mode will be made visible. All other actions will be hidden. + * + * @param {string} mode The mode. Only actions configured to be available in the specified + * mode will be made visible. + * @chainable + * @fires toggle + * @fires change + */ +OO.ui.ActionSet.prototype.setMode = function ( mode ) { + var i, len, action; + + this.changing = true; + for ( i = 0, len = this.list.length; i < len; i++ ) { + action = this.list[ i ]; + action.toggle( action.hasMode( mode ) ); + } + + this.organized = false; + this.changing = false; + this.emit( 'change' ); + + return this; +}; + +/** + * Set the abilities of the specified actions. + * + * Action widgets that are configured with the specified actions will be enabled + * or disabled based on the boolean values specified in the `actions` + * parameter. + * + * @param {Object.<string,boolean>} actions A list keyed by action name with boolean + * values that indicate whether or not the action should be enabled. + * @chainable + */ +OO.ui.ActionSet.prototype.setAbilities = function ( actions ) { + var i, len, action, item; + + for ( i = 0, len = this.list.length; i < len; i++ ) { + item = this.list[ i ]; + action = item.getAction(); + if ( actions[ action ] !== undefined ) { + item.setDisabled( !actions[ action ] ); + } + } + + return this; +}; + +/** + * Executes a function once per action. + * + * When making changes to multiple actions, use this method instead of iterating over the actions + * manually to defer emitting a #change event until after all actions have been changed. + * + * @param {Object|null} actions Filters to use to determine which actions to iterate over; see #get + * @param {Function} callback Callback to run for each action; callback is invoked with three + * arguments: the action, the action's index, the list of actions being iterated over + * @chainable + */ +OO.ui.ActionSet.prototype.forEach = function ( filter, callback ) { + this.changed = false; + this.changing = true; + this.get( filter ).forEach( callback ); + this.changing = false; + if ( this.changed ) { + this.emit( 'change' ); + } + + return this; +}; + +/** + * Add action widgets to the action set. + * + * @param {OO.ui.ActionWidget[]} actions Action widgets to add + * @chainable + * @fires add + * @fires change + */ +OO.ui.ActionSet.prototype.add = function ( actions ) { + var i, len, action; + + this.changing = true; + for ( i = 0, len = actions.length; i < len; i++ ) { + action = actions[ i ]; + action.connect( this, { + click: [ 'emit', 'click', action ], + resize: [ 'emit', 'resize', action ], + toggle: [ 'onActionChange' ] + } ); + this.list.push( action ); + } + this.organized = false; + this.emit( 'add', actions ); + this.changing = false; + this.emit( 'change' ); + + return this; +}; + +/** + * Remove action widgets from the set. + * + * To remove all actions, you may wish to use the #clear method instead. + * + * @param {OO.ui.ActionWidget[]} actions Action widgets to remove + * @chainable + * @fires remove + * @fires change + */ +OO.ui.ActionSet.prototype.remove = function ( actions ) { + var i, len, index, action; + + this.changing = true; + for ( i = 0, len = actions.length; i < len; i++ ) { + action = actions[ i ]; + index = this.list.indexOf( action ); + if ( index !== -1 ) { + action.disconnect( this ); + this.list.splice( index, 1 ); + } + } + this.organized = false; + this.emit( 'remove', actions ); + this.changing = false; + this.emit( 'change' ); + + return this; +}; + +/** + * Remove all action widets from the set. + * + * To remove only specified actions, use the {@link #method-remove remove} method instead. + * + * @chainable + * @fires remove + * @fires change + */ +OO.ui.ActionSet.prototype.clear = function () { + var i, len, action, + removed = this.list.slice(); + + this.changing = true; + for ( i = 0, len = this.list.length; i < len; i++ ) { + action = this.list[ i ]; + action.disconnect( this ); + } + + this.list = []; + + this.organized = false; + this.emit( 'remove', removed ); + this.changing = false; + this.emit( 'change' ); + + return this; +}; + +/** + * Organize actions. + * + * This is called whenever organized information is requested. It will only reorganize the actions + * if something has changed since the last time it ran. + * + * @private + * @chainable + */ +OO.ui.ActionSet.prototype.organize = function () { + var i, iLen, j, jLen, flag, action, category, list, item, special, + specialFlags = this.constructor.static.specialFlags; + + if ( !this.organized ) { + this.categorized = {}; + this.special = {}; + this.others = []; + for ( i = 0, iLen = this.list.length; i < iLen; i++ ) { + action = this.list[ i ]; + if ( action.isVisible() ) { + // Populate categories + for ( category in this.categories ) { + if ( !this.categorized[ category ] ) { + this.categorized[ category ] = {}; + } + list = action[ this.categories[ category ] ](); + if ( !Array.isArray( list ) ) { + list = [ list ]; + } + for ( j = 0, jLen = list.length; j < jLen; j++ ) { + item = list[ j ]; + if ( !this.categorized[ category ][ item ] ) { + this.categorized[ category ][ item ] = []; + } + this.categorized[ category ][ item ].push( action ); + } + } + // Populate special/others + special = false; + for ( j = 0, jLen = specialFlags.length; j < jLen; j++ ) { + flag = specialFlags[ j ]; + if ( !this.special[ flag ] && action.hasFlag( flag ) ) { + this.special[ flag ] = action; + special = true; + break; + } + } + if ( !special ) { + this.others.push( action ); + } + } + } + this.organized = true; + } + + return this; +}; |