_source/core/ui.js

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