Debian Codegraph @

closure-library/closure/goog/ui/editor/toolbarfactory.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 Generic factory functions for creating the building blocks for
17 * an editor toolbar.
18 *
19 * @author [email protected] (Attila Bodis)
20 */
21
22 goog.provide('goog.ui.editor.ToolbarFactory');
23
24 goog.require('goog.array');
25 goog.require('goog.dom');
26 goog.require('goog.dom.TagName');
27 goog.require('goog.string');
28 goog.require('goog.string.Unicode');
29 goog.require('goog.style');
30 goog.require('goog.ui.Component');
31 goog.require('goog.ui.Container');
32 goog.require('goog.ui.Option');
33 goog.require('goog.ui.Toolbar');
34 goog.require('goog.ui.ToolbarButton');
35 goog.require('goog.ui.ToolbarColorMenuButton');
36 goog.require('goog.ui.ToolbarMenuButton');
37 goog.require('goog.ui.ToolbarRenderer');
38 goog.require('goog.ui.ToolbarSelect');
39 goog.require('goog.userAgent');
40
41
42 /**
43 * Takes a font spec (e.g. "Arial, Helvetica, sans-serif") and returns the
44 * primary font name, normalized to lowercase (e.g. "arial").
45 * @param {string} fontSpec Font specification.
46 * @return {string} The primary font name, in lowercase.
47 */
48 goog.ui.editor.ToolbarFactory.getPrimaryFont = function(fontSpec) {
49 var i = fontSpec.indexOf(',');
50 var fontName = (i != -1 ? fontSpec.substring(0, i) : fontSpec).toLowerCase();
51 // Strip leading/trailing quotes from the font name (bug 1050118).
52 return goog.string.stripQuotes(fontName, '"\'');
53 };
54
55
56 /**
57 * Bulk-adds fonts to the given font menu button. The argument must be an
58 * array of font descriptor objects, each of which must have the following
59 * attributes:
60 * <ul>
61 * <li>{@code caption} - Caption to show in the font menu (e.g. 'Tahoma')
62 * <li>{@code value} - Value for the corresponding 'font-family' CSS style
63 * (e.g. 'Tahoma, Arial, sans-serif')
64 * </ul>
65 * @param {!goog.ui.Select} button Font menu button.
66 * @param {!Array<{caption: string, value: string}>} fonts Array of
67 * font descriptors.
68 */
69 goog.ui.editor.ToolbarFactory.addFonts = function(button, fonts) {
70 goog.array.forEach(fonts, function(font) {
71 goog.ui.editor.ToolbarFactory.addFont(button, font.caption, font.value);
72 });
73 };
74
75
76 /**
77 * Adds a menu item to the given font menu button. The first font listed in
78 * the {@code value} argument is considered the font ID, so adding two items
79 * whose CSS style starts with the same font may lead to unpredictable results.
80 * @param {!goog.ui.Select} button Font menu button.
81 * @param {string} caption Caption to show for the font menu.
82 * @param {string} value Value for the corresponding 'font-family' CSS style.
83 */
84 goog.ui.editor.ToolbarFactory.addFont = function(button, caption, value) {
85 // The font ID is the first font listed in the CSS style, normalized to
86 // lowercase.
87 var id = goog.ui.editor.ToolbarFactory.getPrimaryFont(value);
88
89 // Construct the option, and add it to the button.
90 var option = new goog.ui.Option(caption, value, button.getDomHelper());
91 option.setId(id);
92 button.addItem(option);
93
94 // Captions are shown in their own font.
95 option.getContentElement().style.fontFamily = value;
96 };
97
98
99 /**
100 * Bulk-adds font sizes to the given font size menu button. The argument must
101 * be an array of font size descriptor objects, each of which must have the
102 * following attributes:
103 * <ul>
104 * <li>{@code caption} - Caption to show in the font size menu (e.g. 'Huge')
105 * <li>{@code value} - Value for the corresponding HTML font size (e.g. 6)
106 * </ul>
107 * @param {!goog.ui.Select} button Font size menu button.
108 * @param {!Array<{caption: string, value:number}>} sizes Array of font
109 * size descriptors.
110 */
111 goog.ui.editor.ToolbarFactory.addFontSizes = function(button, sizes) {
112 goog.array.forEach(sizes, function(size) {
113 goog.ui.editor.ToolbarFactory.addFontSize(button, size.caption, size.value);
114 });
115 };
116
117
118 /**
119 * Adds a menu item to the given font size menu button. The {@code value}
120 * argument must be a legacy HTML font size in the 0-7 range.
121 * @param {!goog.ui.Select} button Font size menu button.
122 * @param {string} caption Caption to show in the font size menu.
123 * @param {number} value Value for the corresponding HTML font size.
124 */
125 goog.ui.editor.ToolbarFactory.addFontSize = function(button, caption, value) {
126 // Construct the option, and add it to the button.
127 var option = new goog.ui.Option(caption, value, button.getDomHelper());
128 button.addItem(option);
129
130 // Adjust the font size of the menu item and the height of the checkbox
131 // element after they've been rendered by addItem(). Captions are shown in
132 // the corresponding font size, and lining up the checkbox is tricky.
133 var content = option.getContentElement();
134 content.style.fontSize =
135 goog.ui.editor.ToolbarFactory.getPxFromLegacySize(value) + 'px';
136 content.firstChild.style.height = '1.1em';
137 };
138
139
140 /**
141 * Converts a legacy font size specification into an equivalent pixel size.
142 * For example, {@code &lt;font size="6"&gt;} is {@code font-size: 32px;}, etc.
143 * @param {number} fontSize Legacy font size spec in the 0-7 range.
144 * @return {number} Equivalent pixel size.
145 */
146 goog.ui.editor.ToolbarFactory.getPxFromLegacySize = function(fontSize) {
147 return goog.ui.editor.ToolbarFactory.LEGACY_SIZE_TO_PX_MAP_[fontSize] || 10;
148 };
149
150
151 /**
152 * Converts a pixel font size specification into an equivalent legacy size.
153 * For example, {@code font-size: 32px;} is {@code &lt;font size="6"&gt;}, etc.
154 * If the given pixel size doesn't exactly match one of the legacy sizes, -1 is
155 * returned.
156 * @param {number} px Pixel font size.
157 * @return {number} Equivalent legacy size spec in the 0-7 range, or -1 if none
158 * exists.
159 */
160 goog.ui.editor.ToolbarFactory.getLegacySizeFromPx = function(px) {
161 // Use lastIndexOf to get the largest legacy size matching the pixel size
162 // (most notably returning 1 instead of 0 for 10px).
163 return goog.array.lastIndexOf(
164 goog.ui.editor.ToolbarFactory.LEGACY_SIZE_TO_PX_MAP_, px);
165 };
166
167
168 /**
169 * Map of legacy font sizes (0-7) to equivalent pixel sizes.
170 * @type {!Array<number>}
171 * @private
172 */
173 goog.ui.editor.ToolbarFactory.LEGACY_SIZE_TO_PX_MAP_ =
174 [10, 10, 13, 16, 18, 24, 32, 48];
175
176
177 /**
178 * Bulk-adds format options to the given "Format block" menu button. The
179 * argument must be an array of format option descriptor objects, each of
180 * which must have the following attributes:
181 * <ul>
182 * <li>{@code caption} - Caption to show in the menu (e.g. 'Minor heading')
183 * <li>{@code command} - Corresponding {@link goog.dom.TagName} (e.g.
184 * 'H4')
185 * </ul>
186 * @param {!goog.ui.Select} button "Format block" menu button.
187 * @param {!Array<{caption: string, command: !goog.dom.TagName}>} formats Array
188 * of format option descriptors.
189 */
190 goog.ui.editor.ToolbarFactory.addFormatOptions = function(button, formats) {
191 goog.array.forEach(formats, function(format) {
192 goog.ui.editor.ToolbarFactory.addFormatOption(
193 button, format.caption, format.command);
194 });
195 };
196
197
198 /**
199 * Adds a menu item to the given "Format block" menu button.
200 * @param {!goog.ui.Select} button "Format block" menu button.
201 * @param {string} caption Caption to show in the menu.
202 * @param {!goog.dom.TagName} tag Corresponding block format tag.
203 */
204 goog.ui.editor.ToolbarFactory.addFormatOption = function(button, caption, tag) {
205 // Construct the option, and add it to the button.
206 // TODO(attila): Create boring but functional menu item for now...
207 var buttonDom = button.getDomHelper();
208 var option = new goog.ui.Option(
209 buttonDom.createDom(goog.dom.TagName.DIV, null, caption), tag, buttonDom);
210 option.setId(String(tag));
211 button.addItem(option);
212 };
213
214
215 /**
216 * Creates a {@link goog.ui.Toolbar} containing the specified set of
217 * toolbar buttons, and renders it into the given parent element. Each
218 * item in the {@code items} array must a {@link goog.ui.Control}.
219 * @param {!Array<goog.ui.Control>} items Toolbar items; each must
220 * be a {@link goog.ui.Control}.
221 * @param {!Element} elem Toolbar parent element.
222 * @param {boolean=} opt_isRightToLeft Whether the editor chrome is
223 * right-to-left; defaults to the directionality of the toolbar parent
224 * element.
225 * @return {!goog.ui.Toolbar} Editor toolbar, rendered into the given parent
226 * element.
227 */
228 goog.ui.editor.ToolbarFactory.makeToolbar = function(
229 items, elem, opt_isRightToLeft) {
230 var domHelper = goog.dom.getDomHelper(elem);
231
232 // Create an empty horizontal toolbar using the default renderer.
233 var toolbar = new goog.ui.Toolbar(
234 goog.ui.ToolbarRenderer.getInstance(),
235 goog.ui.Container.Orientation.HORIZONTAL, domHelper);
236
237 // Optimization: Explicitly test for the directionality of the parent
238 // element here, so we can set it for both the toolbar and its children,
239 // saving a lot of expensive calls to goog.style.isRightToLeft() during
240 // rendering.
241 var isRightToLeft = opt_isRightToLeft || goog.style.isRightToLeft(elem);
242 toolbar.setRightToLeft(isRightToLeft);
243
244 // Optimization: Set the toolbar to non-focusable before it is rendered,
245 // to avoid creating unnecessary keyboard event handler objects.
246 toolbar.setFocusable(false);
247
248 for (var i = 0, button; button = items[i]; i++) {
249 // Optimization: Set the button to non-focusable before it is rendered,
250 // to avoid creating unnecessary keyboard event handler objects. Also set
251 // the directionality of the button explicitly, to avoid expensive calls
252 // to goog.style.isRightToLeft() during rendering.
253 button.setSupportedState(goog.ui.Component.State.FOCUSED, false);
254 button.setRightToLeft(isRightToLeft);
255 toolbar.addChild(button, true);
256 }
257
258 toolbar.render(elem);
259 return toolbar;
260 };
261
262
263 /**
264 * Creates a toolbar button with the given ID, tooltip, and caption. Applies
265 * any custom CSS class names to the button's caption element.
266 * @param {string} id Button ID; must equal a {@link goog.editor.Command} for
267 * built-in buttons, anything else for custom buttons.
268 * @param {string} tooltip Tooltip to be shown on hover.
269 * @param {goog.ui.ControlContent} caption Button caption.
270 * @param {string=} opt_classNames CSS class name(s) to apply to the caption
271 * element.
272 * @param {goog.ui.ButtonRenderer=} opt_renderer Button renderer; defaults to
273 * {@link goog.ui.ToolbarButtonRenderer} if unspecified.
274 * @param {goog.dom.DomHelper=} opt_domHelper DOM helper, used for DOM
275 * creation; defaults to the current document if unspecified.
276 * @return {!goog.ui.Button} A toolbar button.
277 */
278 goog.ui.editor.ToolbarFactory.makeButton = function(
279 id, tooltip, caption, opt_classNames, opt_renderer, opt_domHelper) {
280 var button = new goog.ui.ToolbarButton(
281 goog.ui.editor.ToolbarFactory.createContent_(
282 caption, opt_classNames, opt_domHelper),
283 opt_renderer, opt_domHelper);
284 button.setId(id);
285 button.setTooltip(tooltip);
286 return button;
287 };
288
289
290 /**
291 * Creates a toggle button with the given ID, tooltip, and caption. Applies
292 * any custom CSS class names to the button's caption element. The button
293 * returned has checkbox-like toggle semantics.
294 * @param {string} id Button ID; must equal a {@link goog.editor.Command} for
295 * built-in buttons, anything else for custom buttons.
296 * @param {string} tooltip Tooltip to be shown on hover.
297 * @param {goog.ui.ControlContent} caption Button caption.
298 * @param {string=} opt_classNames CSS class name(s) to apply to the caption
299 * element.
300 * @param {goog.ui.ButtonRenderer=} opt_renderer Button renderer; defaults to
301 * {@link goog.ui.ToolbarButtonRenderer} if unspecified.
302 * @param {goog.dom.DomHelper=} opt_domHelper DOM helper, used for DOM
303 * creation; defaults to the current document if unspecified.
304 * @return {!goog.ui.Button} A toggle button.
305 */
306 goog.ui.editor.ToolbarFactory.makeToggleButton = function(
307 id, tooltip, caption, opt_classNames, opt_renderer, opt_domHelper) {
308 var button = goog.ui.editor.ToolbarFactory.makeButton(
309 id, tooltip, caption, opt_classNames, opt_renderer, opt_domHelper);
310 button.setSupportedState(goog.ui.Component.State.CHECKED, true);
311 return button;
312 };
313
314
315 /**
316 * Creates a menu button with the given ID, tooltip, and caption. Applies
317 * any custom CSS class names to the button's caption element. The button
318 * returned doesn't have an actual menu attached; use {@link
319 * goog.ui.MenuButton#setMenu} to attach a {@link goog.ui.Menu} to the
320 * button.
321 * @param {string} id Button ID; must equal a {@link goog.editor.Command} for
322 * built-in buttons, anything else for custom buttons.
323 * @param {string} tooltip Tooltip to be shown on hover.
324 * @param {goog.ui.ControlContent} caption Button caption.
325 * @param {string=} opt_classNames CSS class name(s) to apply to the caption
326 * element.
327 * @param {goog.ui.ButtonRenderer=} opt_renderer Button renderer; defaults to
328 * {@link goog.ui.ToolbarMenuButtonRenderer} if unspecified.
329 * @param {goog.dom.DomHelper=} opt_domHelper DOM helper, used for DOM
330 * creation; defaults to the current document if unspecified.
331 * @return {!goog.ui.MenuButton} A menu button.
332 */
333 goog.ui.editor.ToolbarFactory.makeMenuButton = function(
334 id, tooltip, caption, opt_classNames, opt_renderer, opt_domHelper) {
335 var button = new goog.ui.ToolbarMenuButton(
336 goog.ui.editor.ToolbarFactory.createContent_(
337 caption, opt_classNames, opt_domHelper),
338 null, opt_renderer, opt_domHelper);
339 button.setId(id);
340 button.setTooltip(tooltip);
341 return button;
342 };
343
344
345 /**
346 * Creates a select button with the given ID, tooltip, and caption. Applies
347 * any custom CSS class names to the button's root element. The button
348 * returned doesn't have an actual menu attached; use {@link
349 * goog.ui.Select#setMenu} to attach a {@link goog.ui.Menu} containing
350 * {@link goog.ui.Option}s to the select button.
351 * @param {string} id Button ID; must equal a {@link goog.editor.Command} for
352 * built-in buttons, anything else for custom buttons.
353 * @param {string} tooltip Tooltip to be shown on hover.
354 * @param {goog.ui.ControlContent} caption Button caption; used as the
355 * default caption when nothing is selected.
356 * @param {string=} opt_classNames CSS class name(s) to apply to the button's
357 * root element.
358 * @param {goog.ui.MenuButtonRenderer=} opt_renderer Button renderer;
359 * defaults to {@link goog.ui.ToolbarMenuButtonRenderer} if unspecified.
360 * @param {goog.dom.DomHelper=} opt_domHelper DOM helper, used for DOM
361 * creation; defaults to the current document if unspecified.
362 * @return {!goog.ui.Select} A select button.
363 */
364 goog.ui.editor.ToolbarFactory.makeSelectButton = function(
365 id, tooltip, caption, opt_classNames, opt_renderer, opt_domHelper) {
366 var button =
367 new goog.ui.ToolbarSelect(null, null, opt_renderer, opt_domHelper);
368 if (opt_classNames) {
369 // Unlike the other button types, for goog.ui.Select buttons we apply the
370 // extra class names to the root element, because for select buttons the
371 // caption isn't stable (as it changes each time the selection changes).
372 goog.array.forEach(
373 opt_classNames.split(/\s+/), button.addClassName, button);
374 }
375 button.addClassName(goog.getCssName('goog-toolbar-select'));
376 button.setDefaultCaption(caption);
377 button.setId(id);
378 button.setTooltip(tooltip);
379 return button;
380 };
381
382
383 /**
384 * Creates a color menu button with the given ID, tooltip, and caption.
385 * Applies any custom CSS class names to the button's caption element. The
386 * button is created with a default color menu containing standard color
387 * palettes.
388 * @param {string} id Button ID; must equal a {@link goog.editor.Command} for
389 * built-in toolbar buttons, but can be anything else for custom buttons.
390 * @param {string} tooltip Tooltip to be shown on hover.
391 * @param {goog.ui.ControlContent} caption Button caption.
392 * @param {string=} opt_classNames CSS class name(s) to apply to the caption
393 * element.
394 * @param {goog.ui.ColorMenuButtonRenderer=} opt_renderer Button renderer;
395 * defaults to {@link goog.ui.ToolbarColorMenuButtonRenderer}
396 * if unspecified.
397 * @param {goog.dom.DomHelper=} opt_domHelper DOM helper, used for DOM
398 * creation; defaults to the current document if unspecified.
399 * @return {!goog.ui.ColorMenuButton} A color menu button.
400 */
401 goog.ui.editor.ToolbarFactory.makeColorMenuButton = function(
402 id, tooltip, caption, opt_classNames, opt_renderer, opt_domHelper) {
403 var button = new goog.ui.ToolbarColorMenuButton(
404 goog.ui.editor.ToolbarFactory.createContent_(
405 caption, opt_classNames, opt_domHelper),
406 null, opt_renderer, opt_domHelper);
407 button.setId(id);
408 button.setTooltip(tooltip);
409 return button;
410 };
411
412
413 /**
414 * Creates a new DIV that wraps a button caption, optionally applying CSS
415 * class names to it. Used as a helper function in button factory methods.
416 * @param {goog.ui.ControlContent} caption Button caption.
417 * @param {string=} opt_classNames CSS class name(s) to apply to the DIV that
418 * wraps the caption (if any).
419 * @param {goog.dom.DomHelper=} opt_domHelper DOM helper, used for DOM
420 * creation; defaults to the current document if unspecified.
421 * @return {!Element} DIV that wraps the caption.
422 * @private
423 */
424 goog.ui.editor.ToolbarFactory.createContent_ = function(
425 caption, opt_classNames, opt_domHelper) {
426 // FF2 doesn't like empty DIVs, especially when rendered right-to-left.
427 if ((!caption || caption == '') && goog.userAgent.GECKO &&
428 !goog.userAgent.isVersionOrHigher('1.9a')) {
429 caption = goog.string.Unicode.NBSP;
430 }
431 return (opt_domHelper || goog.dom.getDomHelper())
432 .createDom(goog.dom.TagName.DIV, opt_classNames, caption);
433 };