JasonWoof Got questions, comments, patches, etc.? Contact Jason Woofenden
27f226fe36cbb421cb167f176142e6b192defbb3
[ckeditor.git] / _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