Debian Codegraph @

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

raw
1 // Copyright 2005 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 Bubble component - handles display, hiding, etc. of the
17 * actual bubble UI.
18 *
19 * This is used exclusively by code within the editor package, and should not
20 * be used directly.
21 *
22 * @author [email protected] (Robby Walker)
23 */
24
25 goog.provide('goog.ui.editor.Bubble');
26
27 goog.require('goog.asserts');
28 goog.require('goog.dom');
29 goog.require('goog.dom.TagName');
30 goog.require('goog.dom.ViewportSizeMonitor');
31 goog.require('goog.dom.classlist');
32 goog.require('goog.editor.style');
33 goog.require('goog.events.EventHandler');
34 goog.require('goog.events.EventTarget');
35 goog.require('goog.events.EventType');
36 goog.require('goog.functions');
37 goog.require('goog.log');
38 goog.require('goog.math.Box');
39 goog.require('goog.object');
40 goog.require('goog.positioning');
41 goog.require('goog.positioning.Corner');
42 goog.require('goog.positioning.Overflow');
43 goog.require('goog.positioning.OverflowStatus');
44 goog.require('goog.string');
45 goog.require('goog.style');
46 goog.require('goog.ui.Component');
47 goog.require('goog.ui.PopupBase');
48 goog.require('goog.userAgent');
49
50
51
52 /**
53 * Property bubble UI element.
54 * @param {Element} parent The parent element for this bubble.
55 * @param {number} zIndex The z index to draw the bubble at.
56 * @constructor
57 * @extends {goog.events.EventTarget}
58 */
59 goog.ui.editor.Bubble = function(parent, zIndex) {
60 goog.ui.editor.Bubble.base(this, 'constructor');
61
62 /**
63 * Dom helper for the document the bubble should be shown in.
64 * @type {!goog.dom.DomHelper}
65 * @private
66 */
67 this.dom_ = goog.dom.getDomHelper(parent);
68
69 /**
70 * Event handler for this bubble.
71 * @type {goog.events.EventHandler<!goog.ui.editor.Bubble>}
72 * @private
73 */
74 this.eventHandler_ = new goog.events.EventHandler(this);
75
76 /**
77 * Object that monitors the application window for size changes.
78 * @type {goog.dom.ViewportSizeMonitor}
79 * @private
80 */
81 this.viewPortSizeMonitor_ =
82 new goog.dom.ViewportSizeMonitor(this.dom_.getWindow());
83
84 /**
85 * Maps panel ids to panels.
86 * @type {Object<goog.ui.editor.Bubble.Panel_>}
87 * @private
88 */
89 this.panels_ = {};
90
91 /**
92 * Container element for the entire bubble. This may contain elements related
93 * to look and feel or styling of the bubble.
94 * @type {Element}
95 * @private
96 */
97 this.bubbleContainer_ = this.dom_.createDom(
98 goog.dom.TagName.DIV,
99 {'className': goog.ui.editor.Bubble.BUBBLE_CLASSNAME});
100
101 goog.style.setElementShown(this.bubbleContainer_, false);
102 goog.dom.appendChild(parent, this.bubbleContainer_);
103 goog.style.setStyle(this.bubbleContainer_, 'zIndex', zIndex);
104
105 /**
106 * Container element for the bubble panels - this should be some inner element
107 * within (or equal to) bubbleContainer.
108 * @type {Element}
109 * @private
110 */
111 this.bubbleContents_ = this.createBubbleDom(this.dom_, this.bubbleContainer_);
112
113 /**
114 * Element showing the close box.
115 * @type {!Element}
116 * @private
117 */
118 this.closeBox_ = this.dom_.createDom(goog.dom.TagName.DIV, {
119 'className': goog.getCssName('tr_bubble_closebox'),
120 'innerHTML': '&nbsp;'
121 });
122 this.bubbleContents_.appendChild(this.closeBox_);
123
124 // We make bubbles unselectable so that clicking on them does not steal focus
125 // or move the cursor away from the element the bubble is attached to.
126 goog.editor.style.makeUnselectable(this.bubbleContainer_, this.eventHandler_);
127
128 /**
129 * Popup that controls showing and hiding the bubble at the appropriate
130 * position.
131 * @type {goog.ui.PopupBase}
132 * @private
133 */
134 this.popup_ = new goog.ui.PopupBase(this.bubbleContainer_);
135 };
136 goog.inherits(goog.ui.editor.Bubble, goog.events.EventTarget);
137
138
139 /**
140 * The css class name of the bubble container element.
141 * @type {string}
142 */
143 goog.ui.editor.Bubble.BUBBLE_CLASSNAME = goog.getCssName('tr_bubble');
144
145
146 /**
147 * Creates and adds DOM for the bubble UI to the given container. This default
148 * implementation just returns the container itself.
149 * @param {!goog.dom.DomHelper} dom DOM helper to use.
150 * @param {!Element} container Element to add the new elements to.
151 * @return {!Element} The element where bubble content should be added.
152 * @protected
153 */
154 goog.ui.editor.Bubble.prototype.createBubbleDom = function(dom, container) {
155 return container;
156 };
157
158
159 /**
160 * A logger for goog.ui.editor.Bubble.
161 * @type {goog.log.Logger}
162 * @protected
163 */
164 goog.ui.editor.Bubble.prototype.logger =
165 goog.log.getLogger('goog.ui.editor.Bubble');
166
167
168 /** @override */
169 goog.ui.editor.Bubble.prototype.disposeInternal = function() {
170 goog.ui.editor.Bubble.base(this, 'disposeInternal');
171
172 goog.dom.removeNode(this.bubbleContainer_);
173 this.bubbleContainer_ = null;
174
175 this.eventHandler_.dispose();
176 this.eventHandler_ = null;
177
178 this.viewPortSizeMonitor_.dispose();
179 this.viewPortSizeMonitor_ = null;
180 };
181
182
183 /**
184 * @return {Element} The element that where the bubble's contents go.
185 */
186 goog.ui.editor.Bubble.prototype.getContentElement = function() {
187 return this.bubbleContents_;
188 };
189
190
191 /**
192 * @return {Element} The element that contains the bubble.
193 * @protected
194 */
195 goog.ui.editor.Bubble.prototype.getContainerElement = function() {
196 return this.bubbleContainer_;
197 };
198
199
200 /**
201 * @return {goog.events.EventHandler<T>} The event handler.
202 * @protected
203 * @this {T}
204 * @template T
205 */
206 goog.ui.editor.Bubble.prototype.getEventHandler = function() {
207 return this.eventHandler_;
208 };
209
210
211 /**
212 * Handles user resizing of window.
213 * @private
214 */
215 goog.ui.editor.Bubble.prototype.handleWindowResize_ = function() {
216 if (this.isVisible()) {
217 this.reposition();
218 }
219 };
220
221
222 /**
223 * Sets whether the bubble dismisses itself when the user clicks outside of it.
224 * @param {boolean} autoHide Whether to autohide on an external click.
225 */
226 goog.ui.editor.Bubble.prototype.setAutoHide = function(autoHide) {
227 this.popup_.setAutoHide(autoHide);
228 };
229
230
231 /**
232 * Returns whether there is already a panel of the given type.
233 * @param {string} type Type of panel to check.
234 * @return {boolean} Whether there is already a panel of the given type.
235 */
236 goog.ui.editor.Bubble.prototype.hasPanelOfType = function(type) {
237 return goog.object.some(
238 this.panels_, function(panel) { return panel.type == type; });
239 };
240
241
242 /**
243 * Adds a panel to the bubble.
244 * @param {string} type The type of bubble panel this is. Should usually be
245 * the same as the tagName of the targetElement. This ensures multiple
246 * bubble panels don't appear for the same element.
247 * @param {string} title The title of the panel.
248 * @param {Element} targetElement The target element of the bubble.
249 * @param {function(Element): void} contentFn Function that when called with
250 * a container element, will add relevant panel content to it.
251 * @param {boolean=} opt_preferTopPosition Whether to prefer placing the bubble
252 * above the element instead of below it. Defaults to preferring below.
253 * If any panel prefers the top position, the top position is used.
254 * @return {string} The id of the panel.
255 */
256 goog.ui.editor.Bubble.prototype.addPanel = function(
257 type, title, targetElement, contentFn, opt_preferTopPosition) {
258 var id = goog.string.createUniqueString();
259 var panel = new goog.ui.editor.Bubble.Panel_(
260 this.dom_, id, type, title, targetElement, !opt_preferTopPosition);
261 this.panels_[id] = panel;
262
263 // Insert the panel in string order of type. Technically we could use binary
264 // search here but n is really small (probably 0 - 2) so it's not worth it.
265 // The last child of bubbleContents_ is the close box so we take care not
266 // to treat it as a panel element, and we also ensure it stays as the last
267 // element. The intention here is not to create any artificial order, but
268 // just to ensure that it is always consistent.
269 var nextElement;
270 for (var i = 0, len = this.bubbleContents_.childNodes.length - 1; i < len;
271 i++) {
272 var otherChild = this.bubbleContents_.childNodes[i];
273 var otherPanel = this.panels_[otherChild.id];
274 if (otherPanel.type > type) {
275 nextElement = otherChild;
276 break;
277 }
278 }
279 goog.dom.insertSiblingBefore(
280 panel.element, nextElement || this.bubbleContents_.lastChild);
281
282 contentFn(panel.getContentElement());
283 goog.editor.style.makeUnselectable(panel.element, this.eventHandler_);
284
285 var numPanels = goog.object.getCount(this.panels_);
286 if (numPanels == 1) {
287 this.openBubble_();
288 } else if (numPanels == 2) {
289 goog.dom.classlist.add(
290 goog.asserts.assert(this.bubbleContainer_),
291 goog.getCssName('tr_multi_bubble'));
292 }
293 this.reposition();
294
295 return id;
296 };
297
298
299 /**
300 * Removes the panel with the given id.
301 * @param {string} id The id of the panel.
302 */
303 goog.ui.editor.Bubble.prototype.removePanel = function(id) {
304 var panel = this.panels_[id];
305 goog.dom.removeNode(panel.element);
306 delete this.panels_[id];
307
308 var numPanels = goog.object.getCount(this.panels_);
309 if (numPanels <= 1) {
310 goog.dom.classlist.remove(
311 goog.asserts.assert(this.bubbleContainer_),
312 goog.getCssName('tr_multi_bubble'));
313 }
314
315 if (numPanels == 0) {
316 this.closeBubble_();
317 } else {
318 this.reposition();
319 }
320 };
321
322
323 /**
324 * Opens the bubble.
325 * @private
326 */
327 goog.ui.editor.Bubble.prototype.openBubble_ = function() {
328 this.eventHandler_
329 .listen(this.closeBox_, goog.events.EventType.CLICK, this.closeBubble_)
330 .listen(
331 this.viewPortSizeMonitor_, goog.events.EventType.RESIZE,
332 this.handleWindowResize_)
333 .listen(
334 this.popup_, goog.ui.PopupBase.EventType.HIDE, this.handlePopupHide);
335
336 this.popup_.setVisible(true);
337 this.reposition();
338 };
339
340
341 /**
342 * Closes the bubble.
343 * @private
344 */
345 goog.ui.editor.Bubble.prototype.closeBubble_ = function() {
346 this.popup_.setVisible(false);
347 };
348
349
350 /**
351 * Handles the popup's hide event by removing all panels and dispatching a
352 * HIDE event.
353 * @protected
354 */
355 goog.ui.editor.Bubble.prototype.handlePopupHide = function() {
356 // Remove the panel elements.
357 for (var panelId in this.panels_) {
358 goog.dom.removeNode(this.panels_[panelId].element);
359 }
360
361 // Update the state to reflect no panels.
362 this.panels_ = {};
363 goog.dom.classlist.remove(
364 goog.asserts.assert(this.bubbleContainer_),
365 goog.getCssName('tr_multi_bubble'));
366
367 this.eventHandler_.removeAll();
368 this.dispatchEvent(goog.ui.Component.EventType.HIDE);
369 };
370
371
372 /**
373 * Returns the visibility of the bubble.
374 * @return {boolean} True if visible false if not.
375 */
376 goog.ui.editor.Bubble.prototype.isVisible = function() {
377 return this.popup_.isVisible();
378 };
379
380
381 /**
382 * The vertical clearance in pixels between the bottom of the targetElement
383 * and the edge of the bubble.
384 * @type {number}
385 * @private
386 */
387 goog.ui.editor.Bubble.VERTICAL_CLEARANCE_ = goog.userAgent.IE ? 4 : 2;
388
389
390 /**
391 * Bubble's margin box to be passed to goog.positioning.
392 * @type {goog.math.Box}
393 * @private
394 */
395 goog.ui.editor.Bubble.MARGIN_BOX_ = new goog.math.Box(
396 goog.ui.editor.Bubble.VERTICAL_CLEARANCE_, 0,
397 goog.ui.editor.Bubble.VERTICAL_CLEARANCE_, 0);
398
399
400 /**
401 * Returns the margin box.
402 * @return {goog.math.Box}
403 * @protected
404 */
405 goog.ui.editor.Bubble.prototype.getMarginBox = function() {
406 return goog.ui.editor.Bubble.MARGIN_BOX_;
407 };
408
409
410 /**
411 * Positions and displays this bubble below its targetElement. Assumes that
412 * the bubbleContainer is already contained in the document object it applies
413 * to.
414 */
415 goog.ui.editor.Bubble.prototype.reposition = function() {
416 var targetElement = null;
417 var preferBottomPosition = true;
418 for (var panelId in this.panels_) {
419 var panel = this.panels_[panelId];
420 // We don't care which targetElement we get, so we just take the last one.
421 targetElement = panel.targetElement;
422 preferBottomPosition = preferBottomPosition && panel.preferBottomPosition;
423 }
424 var status = goog.positioning.OverflowStatus.FAILED;
425
426 // Fix for bug when bubbleContainer and targetElement have
427 // opposite directionality, the bubble should anchor to the END of
428 // the targetElement instead of START.
429 var reverseLayout =
430 (goog.style.isRightToLeft(this.bubbleContainer_) !=
431 goog.style.isRightToLeft(targetElement));
432
433 // Try to put the bubble at the bottom of the target unless the plugin has
434 // requested otherwise.
435 if (preferBottomPosition) {
436 status = this.positionAtAnchor_(
437 reverseLayout ? goog.positioning.Corner.BOTTOM_END :
438 goog.positioning.Corner.BOTTOM_START,
439 goog.positioning.Corner.TOP_START,
440 goog.positioning.Overflow.ADJUST_X | goog.positioning.Overflow.FAIL_Y);
441 }
442
443 if (status & goog.positioning.OverflowStatus.FAILED) {
444 // Try to put it at the top of the target if there is not enough
445 // space at the bottom.
446 status = this.positionAtAnchor_(
447 reverseLayout ? goog.positioning.Corner.TOP_END :
448 goog.positioning.Corner.TOP_START,
449 goog.positioning.Corner.BOTTOM_START,
450 goog.positioning.Overflow.ADJUST_X | goog.positioning.Overflow.FAIL_Y);
451 }
452
453 if (status & goog.positioning.OverflowStatus.FAILED) {
454 // Put it at the bottom again with adjustment if there is no
455 // enough space at the top.
456 status = this.positionAtAnchor_(
457 reverseLayout ? goog.positioning.Corner.BOTTOM_END :
458 goog.positioning.Corner.BOTTOM_START,
459 goog.positioning.Corner.TOP_START, goog.positioning.Overflow.ADJUST_X |
460 goog.positioning.Overflow.ADJUST_Y);
461 if (status & goog.positioning.OverflowStatus.FAILED) {
462 goog.log.warning(
463 this.logger,
464 'reposition(): positionAtAnchor() failed with ' + status);
465 }
466 }
467 };
468
469
470 /**
471 * A helper for reposition() - positions the bubble in regards to the position
472 * of the elements the bubble is attached to.
473 * @param {goog.positioning.Corner} targetCorner The corner of
474 * the target element.
475 * @param {goog.positioning.Corner} bubbleCorner The corner of the bubble.
476 * @param {number} overflow Overflow handling mode bitmap,
477 * {@see goog.positioning.Overflow}.
478 * @return {number} Status bitmap, {@see goog.positioning.OverflowStatus}.
479 * @private
480 */
481 goog.ui.editor.Bubble.prototype.positionAtAnchor_ = function(
482 targetCorner, bubbleCorner, overflow) {
483 var targetElement = null;
484 for (var panelId in this.panels_) {
485 // For now, we use the outermost element. This assumes the multiple
486 // elements this panel is showing for contain each other - in the event
487 // that is not generally the case this may need to be updated to pick
488 // the lowest or highest element depending on targetCorner.
489 var candidate = this.panels_[panelId].targetElement;
490 if (!targetElement || goog.dom.contains(candidate, targetElement)) {
491 targetElement = this.panels_[panelId].targetElement;
492 }
493 }
494 return goog.positioning.positionAtAnchor(
495 targetElement, targetCorner, this.bubbleContainer_, bubbleCorner, null,
496 this.getMarginBox(), overflow, null, this.getViewportBox());
497 };
498
499
500 /**
501 * Returns the viewport box to use when positioning the bubble.
502 * @return {goog.math.Box}
503 * @protected
504 */
505 goog.ui.editor.Bubble.prototype.getViewportBox = goog.functions.NULL;
506
507
508
509 /**
510 * Private class used to describe a bubble panel.
511 * @param {goog.dom.DomHelper} dom DOM helper used to create the panel.
512 * @param {string} id ID of the panel.
513 * @param {string} type Type of the panel.
514 * @param {string} title Title of the panel.
515 * @param {Element} targetElement Element the panel is showing for.
516 * @param {boolean} preferBottomPosition Whether this panel prefers to show
517 * below the target element.
518 * @constructor
519 * @private
520 */
521 goog.ui.editor.Bubble.Panel_ = function(
522 dom, id, type, title, targetElement, preferBottomPosition) {
523 /**
524 * The type of bubble panel.
525 * @type {string}
526 */
527 this.type = type;
528
529 /**
530 * The target element of this bubble panel.
531 * @type {Element}
532 */
533 this.targetElement = targetElement;
534
535 /**
536 * Whether the panel prefers to be placed below the target element.
537 * @type {boolean}
538 */
539 this.preferBottomPosition = preferBottomPosition;
540
541 /**
542 * The element containing this panel.
543 */
544 this.element = dom.createDom(
545 goog.dom.TagName.DIV,
546 {className: goog.getCssName('tr_bubble_panel'), id: id},
547 dom.createDom(
548 goog.dom.TagName.DIV,
549 {className: goog.getCssName('tr_bubble_panel_title')},
550 title ? title + ':' : ''), // TODO(robbyw): Does this work in bidi?
551 dom.createDom(
552 goog.dom.TagName.DIV,
553 {className: goog.getCssName('tr_bubble_panel_content')}));
554 };
555
556
557 /**
558 * @return {Element} The element in the panel where content should go.
559 */
560 goog.ui.editor.Bubble.Panel_.prototype.getContentElement = function() {
561 return /** @type {Element} */ (this.element.lastChild);
562 };