_source/core/ui.js

   1 /*
   2 Copyright (c) 2003-2011, 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  */