Debian Codegraph @

closure-library/closure/goog/ui/advancedtooltip.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 Advanced tooltip widget implementation.
17 *
18 * @author [email protected] (Emil A Eklund)
19 * @see ../demos/advancedtooltip.html
20 */
21
22 goog.provide('goog.ui.AdvancedTooltip');
23
24 goog.require('goog.events');
25 goog.require('goog.events.EventType');
26 goog.require('goog.math.Box');
27 goog.require('goog.math.Coordinate');
28 goog.require('goog.style');
29 goog.require('goog.ui.Tooltip');
30 goog.require('goog.userAgent');
31
32
33
34 /**
35 * Advanced tooltip widget with cursor tracking abilities. Works like a regular
36 * tooltip but can track the cursor position and direction to determine if the
37 * tooltip should be dismissed or remain open.
38 *
39 * @param {Element|string=} opt_el Element to display tooltip for, either
40 * element reference or string id.
41 * @param {?string=} opt_str Text message to display in tooltip.
42 * @param {goog.dom.DomHelper=} opt_domHelper Optional DOM helper.
43 * @constructor
44 * @extends {goog.ui.Tooltip}
45 */
46 goog.ui.AdvancedTooltip = function(opt_el, opt_str, opt_domHelper) {
47 goog.ui.Tooltip.call(this, opt_el, opt_str, opt_domHelper);
48 };
49 goog.inherits(goog.ui.AdvancedTooltip, goog.ui.Tooltip);
50 goog.tagUnsealableClass(goog.ui.AdvancedTooltip);
51
52
53 /**
54 * Whether to track the cursor and thereby close the tooltip if it moves away
55 * from the tooltip and keep it open if it moves towards it.
56 *
57 * @type {boolean}
58 * @private
59 */
60 goog.ui.AdvancedTooltip.prototype.cursorTracking_ = false;
61
62
63 /**
64 * Delay in milliseconds before tooltips are hidden if cursor tracking is
65 * enabled and the cursor is moving away from the tooltip.
66 *
67 * @type {number}
68 * @private
69 */
70 goog.ui.AdvancedTooltip.prototype.cursorTrackingHideDelayMs_ = 100;
71
72
73 /**
74 * Box object representing a margin around the tooltip where the cursor is
75 * allowed without dismissing the tooltip.
76 *
77 * @type {goog.math.Box}
78 * @private
79 */
80 goog.ui.AdvancedTooltip.prototype.hotSpotPadding_;
81
82
83 /**
84 * Bounding box.
85 *
86 * @type {goog.math.Box}
87 * @private
88 */
89 goog.ui.AdvancedTooltip.prototype.boundingBox_;
90
91
92 /**
93 * Anchor bounding box.
94 *
95 * @type {goog.math.Box}
96 * @private
97 */
98 goog.ui.AdvancedTooltip.prototype.anchorBox_;
99
100
101 /**
102 * Whether the cursor tracking is active.
103 *
104 * @type {boolean}
105 * @private
106 */
107 goog.ui.AdvancedTooltip.prototype.tracking_ = false;
108
109
110 /**
111 * Sets margin around the tooltip where the cursor is allowed without dismissing
112 * the tooltip.
113 *
114 * @param {goog.math.Box=} opt_box The margin around the tooltip.
115 */
116 goog.ui.AdvancedTooltip.prototype.setHotSpotPadding = function(opt_box) {
117 this.hotSpotPadding_ = opt_box || null;
118 };
119
120
121 /**
122 * @return {goog.math.Box} box The margin around the tooltip where the cursor is
123 * allowed without dismissing the tooltip.
124 */
125 goog.ui.AdvancedTooltip.prototype.getHotSpotPadding = function() {
126 return this.hotSpotPadding_;
127 };
128
129
130 /**
131 * Sets whether to track the cursor and thereby close the tooltip if it moves
132 * away from the tooltip and keep it open if it moves towards it.
133 *
134 * @param {boolean} b Whether to track the cursor.
135 */
136 goog.ui.AdvancedTooltip.prototype.setCursorTracking = function(b) {
137 this.cursorTracking_ = b;
138 };
139
140
141 /**
142 * @return {boolean} Whether to track the cursor and thereby close the tooltip
143 * if it moves away from the tooltip and keep it open if it moves towards
144 * it.
145 */
146 goog.ui.AdvancedTooltip.prototype.getCursorTracking = function() {
147 return this.cursorTracking_;
148 };
149
150
151 /**
152 * Sets delay in milliseconds before tooltips are hidden if cursor tracking is
153 * enabled and the cursor is moving away from the tooltip.
154 *
155 * @param {number} delay The delay in milliseconds.
156 */
157 goog.ui.AdvancedTooltip.prototype.setCursorTrackingHideDelayMs = function(
158 delay) {
159 this.cursorTrackingHideDelayMs_ = delay;
160 };
161
162
163 /**
164 * @return {number} The delay in milliseconds before tooltips are hidden if
165 * cursor tracking is enabled and the cursor is moving away from the
166 * tooltip.
167 */
168 goog.ui.AdvancedTooltip.prototype.getCursorTrackingHideDelayMs = function() {
169 return this.cursorTrackingHideDelayMs_;
170 };
171
172
173 /**
174 * Called after the popup is shown.
175 * @protected
176 * @override
177 */
178 goog.ui.AdvancedTooltip.prototype.onShow = function() {
179 goog.ui.AdvancedTooltip.superClass_.onShow.call(this);
180
181 this.boundingBox_ = goog.style.getBounds(this.getElement()).toBox();
182 if (this.anchor) {
183 this.anchorBox_ = goog.style.getBounds(this.anchor).toBox();
184 }
185
186 this.tracking_ = this.cursorTracking_;
187 goog.events.listen(
188 this.getDomHelper().getDocument(), goog.events.EventType.MOUSEMOVE,
189 this.handleMouseMove, false, this);
190 };
191
192
193 /**
194 * Called after the popup is hidden.
195 * @protected
196 * @override
197 */
198 goog.ui.AdvancedTooltip.prototype.onHide = function() {
199 goog.events.unlisten(
200 this.getDomHelper().getDocument(), goog.events.EventType.MOUSEMOVE,
201 this.handleMouseMove, false, this);
202
203 this.boundingBox_ = null;
204 this.anchorBox_ = null;
205 this.tracking_ = false;
206
207 goog.ui.AdvancedTooltip.superClass_.onHide.call(this);
208 };
209
210
211 /**
212 * Returns true if the mouse is in the tooltip.
213 * @return {boolean} True if the mouse is in the tooltip.
214 */
215 goog.ui.AdvancedTooltip.prototype.isMouseInTooltip = function() {
216 return this.isCoordinateInTooltip(this.cursorPosition);
217 };
218
219
220 /**
221 * Checks whether the supplied coordinate is inside the tooltip, including
222 * padding if any.
223 * @param {goog.math.Coordinate} coord Coordinate being tested.
224 * @return {boolean} Whether the coord is in the tooltip.
225 * @override
226 */
227 goog.ui.AdvancedTooltip.prototype.isCoordinateInTooltip = function(coord) {
228 // Check if coord is inside the bounding box of the tooltip
229 if (this.hotSpotPadding_) {
230 var offset = goog.style.getPageOffset(this.getElement());
231 var size = goog.style.getSize(this.getElement());
232 return offset.x - this.hotSpotPadding_.left <= coord.x &&
233 coord.x <= offset.x + size.width + this.hotSpotPadding_.right &&
234 offset.y - this.hotSpotPadding_.top <= coord.y &&
235 coord.y <= offset.y + size.height + this.hotSpotPadding_.bottom;
236 }
237
238 return goog.ui.AdvancedTooltip.superClass_.isCoordinateInTooltip.call(
239 this, coord);
240 };
241
242
243 /**
244 * Checks if supplied coordinate is in the tooltip, its triggering anchor, or
245 * a tooltip that has been triggered by a child of this tooltip.
246 * Called from handleMouseMove to determine if hide timer should be started,
247 * and from maybeHide to determine if tooltip should be hidden.
248 * @param {goog.math.Coordinate} coord Coordinate being tested.
249 * @return {boolean} Whether coordinate is in the anchor, the tooltip, or any
250 * tooltip whose anchor is a child of this tooltip.
251 * @private
252 */
253 goog.ui.AdvancedTooltip.prototype.isCoordinateActive_ = function(coord) {
254 if ((this.anchorBox_ && this.anchorBox_.contains(coord)) ||
255 this.isCoordinateInTooltip(coord)) {
256 return true;
257 }
258
259 // Check if mouse might be in active child element.
260 var childTooltip = this.getChildTooltip();
261 return !!childTooltip && childTooltip.isCoordinateInTooltip(coord);
262 };
263
264
265 /**
266 * Called by timer from mouse out handler. Hides tooltip if cursor is still
267 * outside element and tooltip.
268 * @param {?Element|undefined} el Anchor when hide timer was started.
269 * @override
270 */
271 goog.ui.AdvancedTooltip.prototype.maybeHide = function(el) {
272 this.hideTimer = undefined;
273 if (el == this.anchor) {
274 // Check if cursor is inside the bounding box of the tooltip or the element
275 // that triggered it, or if tooltip is active (possibly due to receiving
276 // the focus), or if there is a nested tooltip being shown.
277 if (!this.isCoordinateActive_(this.cursorPosition) &&
278 !this.getActiveElement() && !this.hasActiveChild()) {
279 // Under certain circumstances gecko fires ghost mouse events with the
280 // coordinates 0, 0 regardless of the cursors position.
281 if (goog.userAgent.GECKO && this.cursorPosition.x == 0 &&
282 this.cursorPosition.y == 0) {
283 return;
284 }
285 this.setVisible(false);
286 }
287 }
288 };
289
290
291 /**
292 * Handler for mouse move events.
293 *
294 * @param {goog.events.BrowserEvent} event Event object.
295 * @protected
296 * @override
297 */
298 goog.ui.AdvancedTooltip.prototype.handleMouseMove = function(event) {
299 var startTimer = this.isVisible();
300 if (this.boundingBox_) {
301 var scroll = this.getDomHelper().getDocumentScroll();
302 var c = new goog.math.Coordinate(
303 event.clientX + scroll.x, event.clientY + scroll.y);
304 if (this.isCoordinateActive_(c)) {
305 startTimer = false;
306 } else if (this.tracking_) {
307 var prevDist =
308 goog.math.Box.distance(this.boundingBox_, this.cursorPosition);
309 var currDist = goog.math.Box.distance(this.boundingBox_, c);
310 startTimer = currDist >= prevDist;
311 }
312 }
313
314 if (startTimer) {
315 this.startHideTimer();
316
317 // Even though the mouse coordinate is not on the tooltip (or nested child),
318 // they may have an active element because of a focus event. Don't let
319 // that prevent us from taking down the tooltip(s) on this mouse move.
320 this.setActiveElement(null);
321 var childTooltip = this.getChildTooltip();
322 if (childTooltip) {
323 childTooltip.setActiveElement(null);
324 }
325 } else if (this.getState() == goog.ui.Tooltip.State.WAITING_TO_HIDE) {
326 this.clearHideTimer();
327 }
328
329 goog.ui.AdvancedTooltip.superClass_.handleMouseMove.call(this, event);
330 };
331
332
333 /**
334 * Handler for mouse over events for the tooltip element.
335 *
336 * @param {goog.events.BrowserEvent} event Event object.
337 * @protected
338 * @override
339 */
340 goog.ui.AdvancedTooltip.prototype.handleTooltipMouseOver = function(event) {
341 if (this.getActiveElement() != this.getElement()) {
342 this.tracking_ = false;
343 this.setActiveElement(this.getElement());
344 }
345 };
346
347
348 /**
349 * Override hide delay with cursor tracking hide delay while tracking.
350 * @return {number} Hide delay to use.
351 * @override
352 */
353 goog.ui.AdvancedTooltip.prototype.getHideDelayMs = function() {
354 return this.tracking_ ? this.cursorTrackingHideDelayMs_ :
355 goog.ui.AdvancedTooltip.base(this, 'getHideDelayMs');
356 };
357
358
359 /**
360 * Forces the recalculation of the hotspot on the next mouse over event.
361 * @deprecated Not ever necessary to call this function. Hot spot is calculated
362 * as necessary.
363 */
364 goog.ui.AdvancedTooltip.prototype.resetHotSpot = goog.nullFunction;