1 /*
  2 Copyright (c) 2003-2012, CKSource - Frederico Knabben. All rights reserved.
  3 For licensing, see LICENSE.html or http://ckeditor.com/license
  4 */
  5 
  6 /**
  7  * Contains UI features related to an editor instance.
  8  * @constructor
  9  * @param {CKEDITOR.editor} editor The editor instance.
 10  * @example
 11  */
 12 CKEDITOR.ui = function( editor )
 13 {
 14 	if ( editor.ui )
 15 		return editor.ui;
 16 
 17 	/**
 18 	 * Object used to hold private stuff.
 19 	 * @private
 20 	 */
 21 	this._ =
 22 	{
 23 		handlers : {},
 24 		items : {},
 25 		editor : editor
 26 	};
 27 
 28 	return this;
 29 };
 30 
 31 // PACKAGER_RENAME( CKEDITOR.ui )
 32 
 33 CKEDITOR.ui.prototype =
 34 {
 35 	/**
 36 	 * Adds a UI item to the items collection. These items can be later used in
 37 	 * the interface.
 38 	 * @param {String} name The UI item name.
 39 	 * @param {Object} type The item type.
 40 	 * @param {Object} definition The item definition. The properties of this
 41 	 *		object depend on the item type.
 42 	 * @example
 43 	 * // Add a new button named "MyBold".
 44 	 * editorInstance.ui.add( 'MyBold', CKEDITOR.UI_BUTTON,
 45 	 *     {
 46 	 *         label : 'My Bold',
 47 	 *         command : 'bold'
 48 	 *     });
 49 	 */
 50 	add : function( name, type, definition )
 51 	{
 52 		this._.items[ name ] =
 53 		{
 54 			type : type,
 55 			// The name of {@link CKEDITOR.command} which associate with this UI.
 56 			command : definition.command || null,
 57 			args : Array.prototype.slice.call( arguments, 2 )
 58 		};
 59 	},
 60 
 61 	/**
 62 	 * Gets a UI object.
 63 	 * @param {String} name The UI item hame.
 64 	 * @example
 65 	 */
 66 	create : function( name )
 67 	{
 68 		var item	= this._.items[ name ],
 69 			handler	= item && this._.handlers[ item.type ],
 70 			command = item && item.command && this._.editor.getCommand( item.command );
 71 
 72 		var result = handler && handler.create.apply( this, item.args );
 73 
 74 		// Allow overrides from skin ui definitions..
 75 		item && ( result = CKEDITOR.tools.extend( result, this._.editor.skin[ item.type ], true ) );
 76 
 77 		// Add reference inside command object.
 78 		if ( command )
 79 			command.uiItems.push( result );
 80 
 81 		return result;
 82 	},
 83 
 84 	/**
 85 	 * Adds a handler for a UI item type. The handler is responsible for
 86 	 * transforming UI item definitions in UI objects.
 87 	 * @param {Object} type The item type.
 88 	 * @param {Object} handler The handler definition.
 89 	 * @example
 90 	 */
 91 	addHandler : function( type, handler )
 92 	{
 93 		this._.handlers[ type ] = handler;
 94 	}
 95 };
 96 
 97 CKEDITOR.event.implementOn( CKEDITOR.ui );
 98 
 99 /**
100  * (Virtual Class) Do not call this constructor. This class is not really part
101  *		of the API. It just illustrates the features of hanlder objects to be
102  *		passed to the {@link CKEDITOR.ui.prototype.addHandler} function.
103  * @name CKEDITOR.ui.handlerDefinition
104  * @constructor
105  * @example
106  */
107 
108  /**
109  * Transforms an item definition into an UI item object.
110  * @name CKEDITOR.handlerDefinition.prototype.create
111  * @function
112  * @param {Object} definition The item definition.
113  * @example
114  * editorInstance.ui.addHandler( CKEDITOR.UI_BUTTON,
115  *     {
116  *         create : function( definition )
117  *         {
118  *             return new CKEDITOR.ui.button( definition );
119  *         }
120  *     });
121  */
122 
123 /**
124  * Internal event fired when a new UI element is ready
125  * @name CKEDITOR.ui#ready
126  * @event
127  * @param {Object} element The new element
128  */
129