_source/core/ui.js

   1 /*\r
   2 Copyright (c) 2003-2011, 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                 // Add reference inside command object.\r
  75                 if ( command )\r
  76                         command.uiItems.push( result );\r
  77 \r
  78                 return result;\r
  79         },\r
  80 \r
  81         /**\r
  82          * Adds a handler for a UI item type. The handler is responsible for\r
  83          * transforming UI item definitions in UI objects.\r
  84          * @param {Object} type The item type.\r
  85          * @param {Object} handler The handler definition.\r
  86          * @example\r
  87          */\r
  88         addHandler : function( type, handler )\r
  89         {\r
  90                 this._.handlers[ type ] = handler;\r
  91         }\r
  92 };\r
  93 \r
  94 CKEDITOR.event.implementOn( CKEDITOR.ui );\r
  95 \r
  96 /**\r
  97  * (Virtual Class) Do not call this constructor. This class is not really part\r
  98  *              of the API. It just illustrates the features of hanlder objects to be\r
  99  *              passed to the {@link CKEDITOR.ui.prototype.addHandler} function.\r
 100  * @name CKEDITOR.ui.handlerDefinition\r
 101  * @constructor\r
 102  * @example\r
 103  */\r
 104 \r
 105  /**\r
 106  * Transforms an item definition into an UI item object.\r
 107  * @name CKEDITOR.handlerDefinition.prototype.create\r
 108  * @function\r
 109  * @param {Object} definition The item definition.\r
 110  * @example\r
 111  * editorInstance.ui.addHandler( CKEDITOR.UI_BUTTON,\r
 112  *     {\r
 113  *         create : function( definition )\r
 114  *         {\r
 115  *             return new CKEDITOR.ui.button( definition );\r
 116  *         }\r
 117  *     });\r
 118  */\r
 119 \r
 120 /**\r
 121  * Internal event fired when a new UI element is ready\r
 122  * @name CKEDITOR.ui#ready\r
 123  * @event\r
 124  * @param {Object} element The new element\r
 125  */\r