Debian Codegraph @

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

raw
1 // Copyright 2007 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 Definition of the Bubble class.
17 *
18 *
19 * @see ../demos/bubble.html
20 *
21 * TODO: support decoration and addChild
22 */
23
24 goog.provide('goog.ui.Bubble');
25
26 goog.require('goog.Timer');
27 goog.require('goog.dom.safe');
28 goog.require('goog.events');
29 goog.require('goog.events.EventType');
30 goog.require('goog.html.SafeHtml');
31 goog.require('goog.math.Box');
32 goog.require('goog.positioning');
33 goog.require('goog.positioning.AbsolutePosition');
34 goog.require('goog.positioning.AnchoredPosition');
35 goog.require('goog.positioning.Corner');
36 goog.require('goog.positioning.CornerBit');
37 goog.require('goog.string.Const');
38 goog.require('goog.style');
39 goog.require('goog.ui.Component');
40 goog.require('goog.ui.Popup');
41
42
43 goog.scope(function() {
44 var SafeHtml = goog.html.SafeHtml;
45
46
47
48 /**
49 * The Bubble provides a general purpose bubble implementation that can be
50 * anchored to a particular element and displayed for a period of time.
51 *
52 * @param {string|!goog.html.SafeHtml|?Element} message Message or an element
53 * to display inside the bubble. Strings are treated as plain-text and will
54 * be HTML escaped.
55 * @param {Object=} opt_config The configuration
56 * for the bubble. If not specified, the default configuration will be
57 * used. {@see goog.ui.Bubble.defaultConfig}.
58 * @param {goog.dom.DomHelper=} opt_domHelper Optional DOM helper.
59 * @constructor
60 * @extends {goog.ui.Component}
61 */
62 goog.ui.Bubble = function(message, opt_config, opt_domHelper) {
63 goog.ui.Component.call(this, opt_domHelper);
64
65 if (goog.isString(message)) {
66 message = goog.html.SafeHtml.htmlEscape(message);
67 }
68
69 /**
70 * The HTML string or element to display inside the bubble.
71 *
72 * @type {!goog.html.SafeHtml|Element}
73 * @private
74 */
75 this.message_ = message;
76
77 /**
78 * The Popup element used to position and display the bubble.
79 *
80 * @type {goog.ui.Popup}
81 * @private
82 */
83 this.popup_ = new goog.ui.Popup();
84
85 /**
86 * Configuration map that contains bubble's UI elements.
87 *
88 * @type {Object}
89 * @private
90 */
91 this.config_ = opt_config || goog.ui.Bubble.defaultConfig;
92
93 /**
94 * Id of the close button for this bubble.
95 *
96 * @type {string}
97 * @private
98 */
99 this.closeButtonId_ = this.makeId('cb');
100
101 /**
102 * Id of the div for the embedded element.
103 *
104 * @type {string}
105 * @private
106 */
107 this.messageId_ = this.makeId('mi');
108
109 };
110 goog.inherits(goog.ui.Bubble, goog.ui.Component);
111 goog.tagUnsealableClass(goog.ui.Bubble);
112
113
114 /**
115 * In milliseconds, timeout after which the button auto-hides. Null means
116 * infinite.
117 * @type {?number}
118 * @private
119 */
120 goog.ui.Bubble.prototype.timeout_ = null;
121
122
123 /**
124 * Key returned by the bubble timer.
125 * @type {?number}
126 * @private
127 */
128 goog.ui.Bubble.prototype.timerId_ = 0;
129
130
131 /**
132 * Key returned by the listen function for the close button.
133 * @type {goog.events.Key}
134 * @private
135 */
136 goog.ui.Bubble.prototype.listener_ = null;
137
138
139
140 /** @override */
141 goog.ui.Bubble.prototype.createDom = function() {
142 goog.ui.Bubble.superClass_.createDom.call(this);
143
144 var element = this.getElement();
145 element.style.position = 'absolute';
146 element.style.visibility = 'hidden';
147
148 this.popup_.setElement(element);
149 };
150
151
152 /**
153 * Attaches the bubble to an anchor element. Computes the positioning and
154 * orientation of the bubble.
155 *
156 * @param {Element} anchorElement The element to which we are attaching.
157 */
158 goog.ui.Bubble.prototype.attach = function(anchorElement) {
159 this.setAnchoredPosition_(
160 anchorElement, this.computePinnedCorner_(anchorElement));
161 };
162
163
164 /**
165 * Sets the corner of the bubble to used in the positioning algorithm.
166 *
167 * @param {goog.positioning.Corner} corner The bubble corner used for
168 * positioning constants.
169 */
170 goog.ui.Bubble.prototype.setPinnedCorner = function(corner) {
171 this.popup_.setPinnedCorner(corner);
172 };
173
174
175 /**
176 * Sets the position of the bubble. Pass null for corner in AnchoredPosition
177 * for corner to be computed automatically.
178 *
179 * @param {goog.positioning.AbstractPosition} position The position of the
180 * bubble.
181 */
182 goog.ui.Bubble.prototype.setPosition = function(position) {
183 if (position instanceof goog.positioning.AbsolutePosition) {
184 this.popup_.setPosition(position);
185 } else if (position instanceof goog.positioning.AnchoredPosition) {
186 this.setAnchoredPosition_(position.element, position.corner);
187 } else {
188 throw new Error('Bubble only supports absolute and anchored positions!');
189 }
190 };
191
192
193 /**
194 * Sets the timeout after which bubble hides itself.
195 *
196 * @param {number} timeout Timeout of the bubble.
197 */
198 goog.ui.Bubble.prototype.setTimeout = function(timeout) {
199 this.timeout_ = timeout;
200 };
201
202
203 /**
204 * Sets whether the bubble should be automatically hidden whenever user clicks
205 * outside the bubble element.
206 *
207 * @param {boolean} autoHide Whether to hide if user clicks outside the bubble.
208 */
209 goog.ui.Bubble.prototype.setAutoHide = function(autoHide) {
210 this.popup_.setAutoHide(autoHide);
211 };
212
213
214 /**
215 * Sets whether the bubble should be visible.
216 *
217 * @param {boolean} visible Desired visibility state.
218 */
219 goog.ui.Bubble.prototype.setVisible = function(visible) {
220 if (visible && !this.popup_.isVisible()) {
221 this.configureElement_();
222 }
223 this.popup_.setVisible(visible);
224 if (!this.popup_.isVisible()) {
225 this.unconfigureElement_();
226 }
227 };
228
229
230 /**
231 * @return {boolean} Whether the bubble is visible.
232 */
233 goog.ui.Bubble.prototype.isVisible = function() {
234 return this.popup_.isVisible();
235 };
236
237
238 /** @override */
239 goog.ui.Bubble.prototype.disposeInternal = function() {
240 this.unconfigureElement_();
241 this.popup_.dispose();
242 this.popup_ = null;
243 goog.ui.Bubble.superClass_.disposeInternal.call(this);
244 };
245
246
247 /**
248 * Creates element's contents and configures all timers. This is called on
249 * setVisible(true).
250 * @private
251 */
252 goog.ui.Bubble.prototype.configureElement_ = function() {
253 if (!this.isInDocument()) {
254 throw new Error('You must render the bubble before showing it!');
255 }
256
257 var element = this.getElement();
258 var corner = this.popup_.getPinnedCorner();
259 goog.dom.safe.setInnerHtml(
260 /** @type {!Element} */ (element), this.computeHtmlForCorner_(corner));
261
262 if (!(this.message_ instanceof SafeHtml)) {
263 var messageDiv = this.getDomHelper().getElement(this.messageId_);
264 this.getDomHelper().appendChild(messageDiv, this.message_);
265 }
266 var closeButton = this.getDomHelper().getElement(this.closeButtonId_);
267 this.listener_ = goog.events.listen(
268 closeButton, goog.events.EventType.CLICK, this.hideBubble_, false, this);
269
270 if (this.timeout_) {
271 this.timerId_ = goog.Timer.callOnce(this.hideBubble_, this.timeout_, this);
272 }
273 };
274
275
276 /**
277 * Gets rid of the element's contents and all associated timers and listeners.
278 * This is called on dispose as well as on setVisible(false).
279 * @private
280 */
281 goog.ui.Bubble.prototype.unconfigureElement_ = function() {
282 if (this.listener_) {
283 goog.events.unlistenByKey(this.listener_);
284 this.listener_ = null;
285 }
286 if (this.timerId_) {
287 goog.Timer.clear(this.timerId_);
288 this.timerId_ = null;
289 }
290
291 var element = this.getElement();
292 if (element) {
293 this.getDomHelper().removeChildren(element);
294 goog.dom.safe.setInnerHtml(element, goog.html.SafeHtml.EMPTY);
295 }
296 };
297
298
299 /**
300 * Computes bubble position based on anchored element.
301 *
302 * @param {Element} anchorElement The element to which we are attaching.
303 * @param {goog.positioning.Corner} corner The bubble corner used for
304 * positioning.
305 * @private
306 */
307 goog.ui.Bubble.prototype.setAnchoredPosition_ = function(
308 anchorElement, corner) {
309 this.popup_.setPinnedCorner(corner);
310 var margin = this.createMarginForCorner_(corner);
311 this.popup_.setMargin(margin);
312 var anchorCorner = goog.positioning.flipCorner(corner);
313 this.popup_.setPosition(
314 new goog.positioning.AnchoredPosition(anchorElement, anchorCorner));
315 };
316
317
318 /**
319 * Hides the bubble. This is called asynchronously by timer of event processor
320 * for the mouse click on the close button.
321 * @private
322 */
323 goog.ui.Bubble.prototype.hideBubble_ = function() {
324 this.setVisible(false);
325 };
326
327
328 /**
329 * Returns an AnchoredPosition that will position the bubble optimally
330 * given the position of the anchor element and the size of the viewport.
331 *
332 * @param {Element} anchorElement The element to which the bubble is attached.
333 * @return {!goog.positioning.AnchoredPosition} The AnchoredPosition
334 * to give to {@link #setPosition}.
335 */
336 goog.ui.Bubble.prototype.getComputedAnchoredPosition = function(anchorElement) {
337 return new goog.positioning.AnchoredPosition(
338 anchorElement, this.computePinnedCorner_(anchorElement));
339 };
340
341
342 /**
343 * Computes the pinned corner for the bubble.
344 *
345 * @param {Element} anchorElement The element to which the button is attached.
346 * @return {goog.positioning.Corner} The pinned corner.
347 * @private
348 */
349 goog.ui.Bubble.prototype.computePinnedCorner_ = function(anchorElement) {
350 var doc = this.getDomHelper().getOwnerDocument(anchorElement);
351 var viewportElement = goog.style.getClientViewportElement(doc);
352 var viewportWidth = viewportElement.offsetWidth;
353 var viewportHeight = viewportElement.offsetHeight;
354 var anchorElementOffset = goog.style.getPageOffset(anchorElement);
355 var anchorElementSize = goog.style.getSize(anchorElement);
356 var anchorType = 0;
357 // right margin or left?
358 if (viewportWidth - anchorElementOffset.x - anchorElementSize.width >
359 anchorElementOffset.x) {
360 anchorType += 1;
361 }
362 // attaches to the top or to the bottom?
363 if (viewportHeight - anchorElementOffset.y - anchorElementSize.height >
364 anchorElementOffset.y) {
365 anchorType += 2;
366 }
367 return goog.ui.Bubble.corners_[anchorType];
368 };
369
370
371 /**
372 * Computes the right offset for a given bubble corner
373 * and creates a margin element for it. This is done to have the
374 * button anchor element on its frame rather than on the corner.
375 *
376 * @param {goog.positioning.Corner} corner The corner.
377 * @return {!goog.math.Box} the computed margin. Only left or right fields are
378 * non-zero, but they may be negative.
379 * @private
380 */
381 goog.ui.Bubble.prototype.createMarginForCorner_ = function(corner) {
382 var margin = new goog.math.Box(0, 0, 0, 0);
383 if (corner & goog.positioning.CornerBit.RIGHT) {
384 margin.right -= this.config_.marginShift;
385 } else {
386 margin.left -= this.config_.marginShift;
387 }
388 return margin;
389 };
390
391
392 /**
393 * Computes the HTML string for a given bubble orientation.
394 *
395 * @param {goog.positioning.Corner} corner The corner.
396 * @return {!goog.html.SafeHtml} The HTML string to place inside the
397 * bubble's popup.
398 * @private
399 */
400 goog.ui.Bubble.prototype.computeHtmlForCorner_ = function(corner) {
401 var bubbleTopClass;
402 var bubbleBottomClass;
403 switch (corner) {
404 case goog.positioning.Corner.TOP_LEFT:
405 bubbleTopClass = this.config_.cssBubbleTopLeftAnchor;
406 bubbleBottomClass = this.config_.cssBubbleBottomNoAnchor;
407 break;
408 case goog.positioning.Corner.TOP_RIGHT:
409 bubbleTopClass = this.config_.cssBubbleTopRightAnchor;
410 bubbleBottomClass = this.config_.cssBubbleBottomNoAnchor;
411 break;
412 case goog.positioning.Corner.BOTTOM_LEFT:
413 bubbleTopClass = this.config_.cssBubbleTopNoAnchor;
414 bubbleBottomClass = this.config_.cssBubbleBottomLeftAnchor;
415 break;
416 case goog.positioning.Corner.BOTTOM_RIGHT:
417 bubbleTopClass = this.config_.cssBubbleTopNoAnchor;
418 bubbleBottomClass = this.config_.cssBubbleBottomRightAnchor;
419 break;
420 default:
421 throw new Error('This corner type is not supported by bubble!');
422 }
423 var message = null;
424 if (this.message_ instanceof SafeHtml) {
425 message = this.message_;
426 } else {
427 message = SafeHtml.create('div', {'id': this.messageId_});
428 }
429
430 var tableRows = goog.html.SafeHtml.concat(
431 SafeHtml.create(
432 'tr', {},
433 SafeHtml.create('td', {'colspan': 4, 'class': bubbleTopClass})),
434 SafeHtml.create(
435 'tr', {},
436 SafeHtml.concat(
437 SafeHtml.create('td', {'class': this.config_.cssBubbleLeft}),
438 SafeHtml.create(
439 'td', {
440 'class': this.config_.cssBubbleFont,
441 'style':
442 goog.string.Const.from('padding:0 4px;background:white')
443 },
444 message),
445 SafeHtml.create('td', {
446 'id': this.closeButtonId_,
447 'class': this.config_.cssCloseButton
448 }),
449 SafeHtml.create('td', {'class': this.config_.cssBubbleRight}))),
450 SafeHtml.create(
451 'tr', {},
452 SafeHtml.create('td', {'colspan': 4, 'class': bubbleBottomClass})));
453
454 return SafeHtml.create(
455 'table', {
456 'border': 0,
457 'cellspacing': 0,
458 'cellpadding': 0,
459 'width': this.config_.bubbleWidth,
460 'style': goog.string.Const.from('z-index:1')
461 },
462 tableRows);
463 };
464
465
466 /**
467 * A default configuration for the bubble.
468 *
469 * @type {Object}
470 */
471 goog.ui.Bubble.defaultConfig = {
472 bubbleWidth: 147,
473 marginShift: 60,
474 cssBubbleFont: goog.getCssName('goog-bubble-font'),
475 cssCloseButton: goog.getCssName('goog-bubble-close-button'),
476 cssBubbleTopRightAnchor: goog.getCssName('goog-bubble-top-right-anchor'),
477 cssBubbleTopLeftAnchor: goog.getCssName('goog-bubble-top-left-anchor'),
478 cssBubbleTopNoAnchor: goog.getCssName('goog-bubble-top-no-anchor'),
479 cssBubbleBottomRightAnchor:
480 goog.getCssName('goog-bubble-bottom-right-anchor'),
481 cssBubbleBottomLeftAnchor: goog.getCssName('goog-bubble-bottom-left-anchor'),
482 cssBubbleBottomNoAnchor: goog.getCssName('goog-bubble-bottom-no-anchor'),
483 cssBubbleLeft: goog.getCssName('goog-bubble-left'),
484 cssBubbleRight: goog.getCssName('goog-bubble-right')
485 };
486
487
488 /**
489 * An auxiliary array optimizing the corner computation.
490 *
491 * @type {Array<goog.positioning.Corner>}
492 * @private
493 */
494 goog.ui.Bubble.corners_ = [
495 goog.positioning.Corner.BOTTOM_RIGHT, goog.positioning.Corner.BOTTOM_LEFT,
496 goog.positioning.Corner.TOP_RIGHT, goog.positioning.Corner.TOP_LEFT
497 ];
498 }); // goog.scope