]>
Commit | Line | Data |
---|---|---|
7adcb81e | 1 | /** |
3b35bd27 | 2 | * @license Copyright (c) 2003-2016, CKSource - Frederico Knabben. All rights reserved. |
7adcb81e IB |
3 | * For licensing, see LICENSE.md or http://ckeditor.com/license |
4 | */ | |
5 | ||
6 | /** | |
7 | * Contains UI features related to an editor instance. | |
8 | * | |
9 | * @class | |
10 | * @mixins CKEDITOR.event | |
11 | * @constructor Creates a `ui` class instance. | |
12 | * @param {CKEDITOR.editor} editor The editor instance. | |
13 | */ | |
14 | CKEDITOR.ui = function( editor ) { | |
15 | if ( editor.ui ) | |
16 | return editor.ui; | |
17 | ||
18 | this.items = {}; | |
19 | this.instances = {}; | |
20 | this.editor = editor; | |
21 | ||
22 | /** | |
23 | * Object used to store private stuff. | |
24 | * | |
25 | * @private | |
26 | */ | |
27 | this._ = { | |
28 | handlers: {} | |
29 | }; | |
30 | ||
31 | return this; | |
32 | }; | |
33 | ||
34 | // PACKAGER_RENAME( CKEDITOR.ui ) | |
35 | ||
36 | CKEDITOR.ui.prototype = { | |
37 | /** | |
38 | * Adds a UI item to the items collection. These items can be later used in | |
39 | * the interface. | |
40 | * | |
41 | * // Add a new button named 'MyBold'. | |
42 | * editorInstance.ui.add( 'MyBold', CKEDITOR.UI_BUTTON, { | |
43 | * label: 'My Bold', | |
44 | * command: 'bold' | |
45 | * } ); | |
46 | * | |
47 | * @param {String} name The UI item name. | |
48 | * @param {Object} type The item type. | |
49 | * @param {Object} definition The item definition. The properties of this | |
50 | * object depend on the item type. | |
51 | */ | |
52 | add: function( name, type, definition ) { | |
53 | // Compensate the unique name of this ui item to definition. | |
54 | definition.name = name.toLowerCase(); | |
55 | ||
56 | var item = this.items[ name ] = { | |
57 | type: type, | |
58 | // The name of {@link CKEDITOR.command} which associate with this UI. | |
59 | command: definition.command || null, | |
60 | args: Array.prototype.slice.call( arguments, 2 ) | |
61 | }; | |
62 | ||
63 | CKEDITOR.tools.extend( item, definition ); | |
64 | }, | |
65 | ||
66 | /** | |
67 | * Retrieves the created UI objects by name. | |
68 | * | |
69 | * @param {String} name The name of the UI definition. | |
70 | */ | |
71 | get: function( name ) { | |
72 | return this.instances[ name ]; | |
73 | }, | |
74 | ||
75 | /** | |
76 | * Gets a UI object. | |
77 | * | |
78 | * @param {String} name The UI item name. | |
79 | * @returns {Object} The UI element. | |
80 | */ | |
81 | create: function( name ) { | |
82 | var item = this.items[ name ], | |
83 | handler = item && this._.handlers[ item.type ], | |
84 | command = item && item.command && this.editor.getCommand( item.command ); | |
85 | ||
86 | var result = handler && handler.create.apply( this, item.args ); | |
87 | ||
88 | this.instances[ name ] = result; | |
89 | ||
90 | // Add reference inside command object. | |
91 | if ( command ) | |
92 | command.uiItems.push( result ); | |
93 | ||
94 | if ( result && !result.type ) | |
95 | result.type = item.type; | |
96 | ||
97 | return result; | |
98 | }, | |
99 | ||
100 | /** | |
101 | * Adds a handler for a UI item type. The handler is responsible for | |
102 | * transforming UI item definitions into UI objects. | |
103 | * | |
104 | * @param {Object} type The item type. | |
105 | * @param {Object} handler The handler definition. | |
106 | */ | |
107 | addHandler: function( type, handler ) { | |
108 | this._.handlers[ type ] = handler; | |
109 | }, | |
110 | ||
111 | /** | |
112 | * Returns the unique DOM element that represents one editor's UI part, also known as "space". | |
113 | * There are 3 main editor spaces available: `top`, `contents` and `bottom` | |
114 | * and their availability depends on editor type. | |
115 | * | |
116 | * // Hide the bottom space in the UI. | |
117 | * var bottom = editor.ui.space( 'bottom' ); | |
118 | * bottom.setStyle( 'display', 'none' ); | |
119 | * | |
120 | * @param {String} name The name of the space. | |
121 | * @returns {CKEDITOR.dom.element} The element that represents the space. | |
122 | */ | |
123 | space: function( name ) { | |
124 | return CKEDITOR.document.getById( this.spaceId( name ) ); | |
125 | }, | |
126 | ||
127 | /** | |
128 | * Returns the HTML ID for a specific UI space name. | |
129 | * | |
130 | * @param {String} name The name of the space. | |
131 | * @returns {String} The ID of an element representing this space in the DOM. | |
132 | */ | |
133 | spaceId: function( name ) { | |
134 | return this.editor.id + '_' + name; | |
135 | } | |
136 | }; | |
137 | ||
138 | CKEDITOR.event.implementOn( CKEDITOR.ui ); | |
139 | ||
140 | /** | |
141 | * Internal event fired when a new UI element is ready. | |
142 | * | |
143 | * @event ready | |
144 | * @param {Object} data The new UI element. | |
145 | */ | |
146 | ||
147 | /** | |
148 | * Virtual class which just illustrates the features of handler objects to be | |
149 | * passed to the {@link CKEDITOR.ui#addHandler} function. | |
150 | * This class is not really a part of the API, so do not call its constructor. | |
151 | * | |
152 | * @class CKEDITOR.ui.handlerDefinition | |
153 | */ | |
154 | ||
155 | /** | |
156 | * Transforms an item definition into a UI item object. | |
157 | * | |
158 | * editorInstance.ui.addHandler( CKEDITOR.UI_BUTTON, { | |
159 | * create: function( definition ) { | |
160 | * return new CKEDITOR.ui.button( definition ); | |
161 | * } | |
162 | * } ); | |
163 | * | |
164 | * @method create | |
165 | * @param {Object} definition The item definition. | |
166 | * @returns {Object} The UI element. | |
167 | * @todo We lack the "UI element" abstract super class. | |
168 | */ | |
169 | ||
170 | /** | |
171 | * The element in the {@link CKEDITOR#document host page's document} that contains the editor content. | |
172 | * If the [fixed editor UI](#!/guide/dev_uitypes-section-fixed-user-interface) is used, then it will be set to | |
173 | * `editor.ui.space( 'contents' )` — i.e. the `<div>` which contains the editor `<iframe>` (in case of classic editor) | |
174 | * or {@link CKEDITOR.editable} (in case of inline editor). Otherwise it is set to the {@link CKEDITOR.editable} itself. | |
175 | * | |
176 | * Use the position of this element if you need to position elements placed in the host page's document relatively to the | |
177 | * editor content. | |
178 | * | |
179 | * var editor = CKEDITOR.instances.editor1; | |
180 | * console.log( editor.ui.contentsElement.getName() ); // 'div' | |
181 | * | |
182 | * @since 4.5 | |
183 | * @readonly | |
184 | * @property {CKEDITOR.dom.element} contentsElement | |
185 | */ |