Debian Codegraph @

closure-library/closure/goog/ui/editor/toolbarcontroller.js

raw
1 // Copyright 2008 The Closure Library Authors. All Rights Reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS-IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 /**
16 * @fileoverview A class for managing the editor toolbar.
17 *
18 * @author [email protected] (Attila Bodis)
19 * @see ../../demos/editor/editor.html
20 */
21
22 goog.provide('goog.ui.editor.ToolbarController');
23
24 goog.require('goog.editor.Field');
25 goog.require('goog.events.EventHandler');
26 goog.require('goog.events.EventTarget');
27 goog.require('goog.ui.Component');
28
29
30
31 /**
32 * A class for managing the editor toolbar. Acts as a bridge between
33 * a {@link goog.editor.Field} and a {@link goog.ui.Toolbar}.
34 *
35 * The {@code toolbar} argument must be an instance of {@link goog.ui.Toolbar}
36 * or a subclass. This class doesn't care how the toolbar was created. As
37 * long as one or more controls hosted in the toolbar have IDs that match
38 * built-in {@link goog.editor.Command}s, they will function as expected. It is
39 * the caller's responsibility to ensure that the toolbar is already rendered
40 * or that it decorates an existing element.
41 *
42 *
43 * @param {!goog.editor.Field} field Editable field to be controlled by the
44 * toolbar.
45 * @param {!goog.ui.Toolbar} toolbar Toolbar to control the editable field.
46 * @constructor
47 * @extends {goog.events.EventTarget}
48 */
49 goog.ui.editor.ToolbarController = function(field, toolbar) {
50 goog.events.EventTarget.call(this);
51
52 /**
53 * Event handler to listen for field events and user actions.
54 * @type {!goog.events.EventHandler<!goog.ui.editor.ToolbarController>}
55 * @private
56 */
57 this.handler_ = new goog.events.EventHandler(this);
58
59 /**
60 * The field instance controlled by the toolbar.
61 * @type {!goog.editor.Field}
62 * @private
63 */
64 this.field_ = field;
65
66 /**
67 * The toolbar that controls the field.
68 * @type {!goog.ui.Toolbar}
69 * @private
70 */
71 this.toolbar_ = toolbar;
72
73 /**
74 * Editing commands whose state is to be queried when updating the toolbar.
75 * @type {!Array<string>}
76 * @private
77 */
78 this.queryCommands_ = [];
79
80 // Iterate over all buttons, and find those which correspond to
81 // queryable commands. Add them to the list of commands to query on
82 // each COMMAND_VALUE_CHANGE event.
83 this.toolbar_.forEachChild(function(button) {
84 if (button.queryable) {
85 this.queryCommands_.push(this.getComponentId(button.getId()));
86 }
87 }, this);
88
89 // Make sure the toolbar doesn't steal keyboard focus.
90 this.toolbar_.setFocusable(false);
91
92 // Hook up handlers that update the toolbar in response to field events,
93 // and to execute editor commands in response to toolbar events.
94 this.handler_
95 .listen(
96 this.field_, goog.editor.Field.EventType.COMMAND_VALUE_CHANGE,
97 this.updateToolbar)
98 .listen(
99 this.toolbar_, goog.ui.Component.EventType.ACTION, this.handleAction);
100 };
101 goog.inherits(goog.ui.editor.ToolbarController, goog.events.EventTarget);
102
103
104 /**
105 * Returns the Closure component ID of the control that corresponds to the
106 * given {@link goog.editor.Command} constant.
107 * Subclasses may override this method if they want to use a custom mapping
108 * scheme from commands to controls.
109 * @param {string} command Editor command.
110 * @return {string} Closure component ID of the corresponding toolbar
111 * control, if any.
112 * @protected
113 */
114 goog.ui.editor.ToolbarController.prototype.getComponentId = function(command) {
115 // The default implementation assumes that the component ID is the same as
116 // the command constant.
117 return command;
118 };
119
120
121 /**
122 * Returns the {@link goog.editor.Command} constant
123 * that corresponds to the given Closure component ID. Subclasses may override
124 * this method if they want to use a custom mapping scheme from controls to
125 * commands.
126 * @param {string} id Closure component ID of a toolbar control.
127 * @return {string} Editor command or dialog constant corresponding to the
128 * toolbar control, if any.
129 * @protected
130 */
131 goog.ui.editor.ToolbarController.prototype.getCommand = function(id) {
132 // The default implementation assumes that the component ID is the same as
133 // the command constant.
134 return id;
135 };
136
137
138 /**
139 * Returns the event handler object for the editor toolbar. Useful for classes
140 * that extend {@code goog.ui.editor.ToolbarController}.
141 * @return {!goog.events.EventHandler<T>} The event handler object.
142 * @protected
143 * @this {T}
144 * @template T
145 */
146 goog.ui.editor.ToolbarController.prototype.getHandler = function() {
147 return this.handler_;
148 };
149
150
151 /**
152 * Returns the field instance managed by the toolbar. Useful for
153 * classes that extend {@code goog.ui.editor.ToolbarController}.
154 * @return {!goog.editor.Field} The field managed by the toolbar.
155 * @protected
156 */
157 goog.ui.editor.ToolbarController.prototype.getField = function() {
158 return this.field_;
159 };
160
161
162 /**
163 * Returns the toolbar UI component that manages the editor. Useful for
164 * classes that extend {@code goog.ui.editor.ToolbarController}.
165 * @return {!goog.ui.Toolbar} The toolbar UI component.
166 */
167 goog.ui.editor.ToolbarController.prototype.getToolbar = function() {
168 return this.toolbar_;
169 };
170
171
172 /**
173 * @return {boolean} Whether the toolbar is visible.
174 */
175 goog.ui.editor.ToolbarController.prototype.isVisible = function() {
176 return this.toolbar_.isVisible();
177 };
178
179
180 /**
181 * Shows or hides the toolbar.
182 * @param {boolean} visible Whether to show or hide the toolbar.
183 */
184 goog.ui.editor.ToolbarController.prototype.setVisible = function(visible) {
185 this.toolbar_.setVisible(visible);
186 };
187
188
189 /**
190 * @return {boolean} Whether the toolbar is enabled.
191 */
192 goog.ui.editor.ToolbarController.prototype.isEnabled = function() {
193 return this.toolbar_.isEnabled();
194 };
195
196
197 /**
198 * Enables or disables the toolbar.
199 * @param {boolean} enabled Whether to enable or disable the toolbar.
200 */
201 goog.ui.editor.ToolbarController.prototype.setEnabled = function(enabled) {
202 this.toolbar_.setEnabled(enabled);
203 };
204
205
206 /**
207 * Programmatically blurs the editor toolbar, un-highlighting the currently
208 * highlighted item, and closing the currently open menu (if any).
209 */
210 goog.ui.editor.ToolbarController.prototype.blur = function() {
211 // We can't just call this.toolbar_.getElement().blur(), because the toolbar
212 // element itself isn't focusable, so goog.ui.Container#handleBlur isn't
213 // registered to handle blur events.
214 this.toolbar_.handleBlur(null);
215 };
216
217
218 /** @override */
219 goog.ui.editor.ToolbarController.prototype.disposeInternal = function() {
220 goog.ui.editor.ToolbarController.superClass_.disposeInternal.call(this);
221 if (this.handler_) {
222 this.handler_.dispose();
223 delete this.handler_;
224 }
225 if (this.toolbar_) {
226 this.toolbar_.dispose();
227 delete this.toolbar_;
228 }
229 delete this.field_;
230 delete this.queryCommands_;
231 };
232
233
234 /**
235 * Updates the toolbar in response to editor events. Specifically, updates
236 * button states based on {@code COMMAND_VALUE_CHANGE} events, reflecting the
237 * effective formatting of the selection.
238 * @param {goog.events.Event} e Editor event to handle.
239 * @protected
240 */
241 goog.ui.editor.ToolbarController.prototype.updateToolbar = function(e) {
242 if (!this.toolbar_.isEnabled() || !this.field_.isSelectionEditable() ||
243 !this.dispatchEvent(goog.ui.Component.EventType.CHANGE)) {
244 return;
245 }
246
247 var state;
248
249
250 try {
251 /** @type {Array<string>} */
252 e.commands; // Added by dispatchEvent.
253
254 // If the COMMAND_VALUE_CHANGE event specifies which commands changed
255 // state, then we only need to update those ones, otherwise update all
256 // commands.
257 state = /** @type {Object} */ (
258 this.field_.queryCommandValue(e.commands || this.queryCommands_));
259 } catch (ex) {
260 // TODO(attila): Find out when/why this happens.
261 state = {};
262 }
263
264 this.updateToolbarFromState(state);
265 };
266
267
268 /**
269 * Updates the toolbar to reflect a given state.
270 * @param {Object} state Object mapping editor commands to values.
271 */
272 goog.ui.editor.ToolbarController.prototype.updateToolbarFromState = function(
273 state) {
274 for (var command in state) {
275 var button = this.toolbar_.getChild(this.getComponentId(command));
276 if (button) {
277 var value = state[command];
278 if (button.updateFromValue) {
279 button.updateFromValue(value);
280 } else {
281 button.setChecked(!!value);
282 }
283 }
284 }
285 };
286
287
288 /**
289 * Handles {@code ACTION} events dispatched by toolbar buttons in response to
290 * user actions by executing the corresponding field command.
291 * @param {goog.events.Event} e Action event to handle.
292 * @protected
293 */
294 goog.ui.editor.ToolbarController.prototype.handleAction = function(e) {
295 var command = this.getCommand(e.target.getId());
296 this.field_.execCommand(command, e.target.getValue());
297 };