mediawiki-extensions-Visual.../modules/ve/ui/ve.ui.Toolbar.js
Trevor Parscal 332e31fb00 Toolbar API
Objectives:

* Make it possible to add items to toolbars without having to have all
  toolbars know about the items in advance
* Make it possible to specialize an existing tool and have it be used
  instead of the base implementation

Approach:

* Tools are named using a path-style category/id/ext system, making them
  selectable, the latter component being used to differentiate extended
  tools from their base classes, but is ignored during selection
* Toolbars have ToolGroups, which include or exclude tools by category or
  category/id, and order them by promoting and demoting selections of
  tools by category or category/id

Future:

* Add a way to place available but not yet placed tools in an "overflow"
  group
* Add a mode to ToolGroup to make the tools a multi-column drop-down style
  list with labels so tools with less obvious icons are easier to identify
  - and probably use this as the overflow group

Change-Id: I7625f861435a99ce3d7a2b1ece9731aaab1776f8
2013-08-20 16:08:26 -07:00

104 lines
2.5 KiB
JavaScript

/*!
* VisualEditor UserInterface Toolbar class.
*
* @copyright 2011-2013 VisualEditor Team and others; see AUTHORS.txt
* @license The MIT License (MIT); see LICENSE.txt
*/
/**
* UserInterface toolbar.
*
* @class
* @extends ve.Element
* @mixins ve.EventEmitter
* @mixins ve.ui.GroupElement
*
* @constructor
* @param {Object} [config] Config options
* @cfg {boolean} [actions] Add an actions section opposite to the tools
* @cfg {boolean} [shadow] Add a shadow below the toolbar
*/
ve.ui.Toolbar = function VeUiToolbar( options ) {
// Configuration initialization
options = options || {};
// Parent constructor
ve.Element.call( this, options );
// Mixin constructors
ve.EventEmitter.call( this );
ve.ui.GroupElement.call( this, this.$$( '<div>' ) );
// Properties
this.groups = [];
this.$bar = this.$$( '<div>' );
this.$actions = this.$$( '<div>' );
this.initialized = false;
// Events
this.$
.add( this.$bar ).add( this.$group ).add( this.$actions )
.on( 'mousedown', false );
// Initialization
this.$group.addClass( 've-ui-toolbar-tools' );
this.$bar.addClass( 've-ui-toolbar-bar' ).append( this.$group );
if ( options.actions ) {
this.$actions.addClass( 've-ui-toolbar-actions' );
this.$bar.append( this.$actions );
}
this.$bar.append( '<div style="clear:both"></div>' );
if ( options.shadow ) {
this.$bar.append( '<div class="ve-ui-toolbar-shadow"></div>' );
}
this.$.addClass( 've-ui-toolbar' ).append( this.$bar );
};
/* Inheritance */
ve.inheritClass( ve.ui.Toolbar, ve.Element );
ve.mixinClass( ve.ui.Toolbar, ve.EventEmitter );
ve.mixinClass( ve.ui.Toolbar, ve.ui.GroupElement );
/* Methods */
/**
* Sets up handles and preloads required information for the toolbar to work.
* This must be called immediately after it is attached to a visible document.
*/
ve.ui.Toolbar.prototype.initialize = function () {
this.initialized = true;
};
/**
* Setup toolbar.
*
* @method
* @param {Object[]} groups List of tool group configurations
*/
ve.ui.Toolbar.prototype.setup = function ( groups ) {
var i, len,
items = [];
for ( i = 0, len = groups.length; i < len; i++ ) {
items.push( new ve.ui.ToolGroup( this, ve.extendObject( { '$$': this.$$ }, groups[i] ) ) );
}
this.addItems( items );
};
/**
* Destroys toolbar, removing event handlers and DOM elements.
*
* Call this whenever you are done using a toolbar.
*/
ve.ui.Toolbar.prototype.destroy = function () {
var i, len;
this.clearItems();
for ( i = 0, len = this.items.length; i < len; i++ ) {
this.items[i].destroy();
}
this.$.remove();
};