Debian Codegraph @

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

raw
1 // Copyright 2006 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 Activity Monitor.
17 *
18 * Fires throttled events when a user interacts with the specified document.
19 * This class also exposes the amount of time since the last user event.
20 *
21 * If you would prefer to get BECOME_ACTIVE and BECOME_IDLE events when the
22 * user changes states, then you should use the IdleTimer class instead.
23 *
24 */
25
26 goog.provide('goog.ui.ActivityMonitor');
27
28 goog.require('goog.array');
29 goog.require('goog.asserts');
30 goog.require('goog.dom');
31 goog.require('goog.events.EventHandler');
32 goog.require('goog.events.EventTarget');
33 goog.require('goog.events.EventType');
34
35
36
37 /**
38 * Once initialized with a document, the activity monitor can be queried for
39 * the current idle time.
40 *
41 * @param {goog.dom.DomHelper|Array<goog.dom.DomHelper>=} opt_domHelper
42 * DomHelper which contains the document(s) to listen to. If null, the
43 * default document is usedinstead.
44 * @param {boolean=} opt_useBubble Whether to use the bubble phase to listen for
45 * events. By default listens on the capture phase so that it won't miss
46 * events that get stopPropagation/cancelBubble'd. However, this can cause
47 * problems in IE8 if the page loads multiple scripts that include the
48 * closure event handling code.
49 *
50 * @constructor
51 * @extends {goog.events.EventTarget}
52 */
53 goog.ui.ActivityMonitor = function(opt_domHelper, opt_useBubble) {
54 goog.events.EventTarget.call(this);
55
56 /**
57 * Array of documents that are being listened to.
58 * @type {Array<Document>}
59 * @private
60 */
61 this.documents_ = [];
62
63 /**
64 * Whether to use the bubble phase to listen for events.
65 * @type {boolean}
66 * @private
67 */
68 this.useBubble_ = !!opt_useBubble;
69
70 /**
71 * The event handler.
72 * @type {goog.events.EventHandler<!goog.ui.ActivityMonitor>}
73 * @private
74 */
75 this.eventHandler_ = new goog.events.EventHandler(this);
76
77 /**
78 * Whether the current window is an iframe.
79 * TODO(user): Move to goog.dom.
80 * @type {boolean}
81 * @private
82 */
83 this.isIframe_ = window.parent != window;
84
85 if (!opt_domHelper) {
86 this.addDocument(goog.dom.getDomHelper().getDocument());
87 } else if (goog.isArray(opt_domHelper)) {
88 for (var i = 0; i < opt_domHelper.length; i++) {
89 this.addDocument(opt_domHelper[i].getDocument());
90 }
91 } else {
92 this.addDocument(opt_domHelper.getDocument());
93 }
94
95 /**
96 * The time (in milliseconds) of the last user event.
97 * @type {number}
98 * @private
99 */
100 this.lastEventTime_ = goog.now();
101
102 };
103 goog.inherits(goog.ui.ActivityMonitor, goog.events.EventTarget);
104 goog.tagUnsealableClass(goog.ui.ActivityMonitor);
105
106
107 /**
108 * The last event type that was detected.
109 * @type {string}
110 * @private
111 */
112 goog.ui.ActivityMonitor.prototype.lastEventType_ = '';
113
114
115 /**
116 * The mouse x-position after the last user event.
117 * @type {number}
118 * @private
119 */
120 goog.ui.ActivityMonitor.prototype.lastMouseX_;
121
122
123 /**
124 * The mouse y-position after the last user event.
125 * @type {number}
126 * @private
127 */
128 goog.ui.ActivityMonitor.prototype.lastMouseY_;
129
130
131 /**
132 * The earliest time that another throttled ACTIVITY event will be dispatched
133 * @type {number}
134 * @private
135 */
136 goog.ui.ActivityMonitor.prototype.minEventTime_ = 0;
137
138
139 /**
140 * Minimum amount of time in ms between throttled ACTIVITY events
141 * @type {number}
142 */
143 goog.ui.ActivityMonitor.MIN_EVENT_SPACING = 3 * 1000;
144
145
146 /**
147 * If a user executes one of these events, s/he is considered not idle.
148 * @type {Array<goog.events.EventType>}
149 * @private
150 */
151 goog.ui.ActivityMonitor.userEventTypesBody_ = [
152 goog.events.EventType.CLICK, goog.events.EventType.DBLCLICK,
153 goog.events.EventType.MOUSEDOWN, goog.events.EventType.MOUSEMOVE,
154 goog.events.EventType.MOUSEUP
155 ];
156
157
158 /**
159 * If a user executes one of these events, s/he is considered not idle.
160 * Note: monitoring touch events within iframe cause problems in iOS.
161 * @type {Array<goog.events.EventType>}
162 * @private
163 */
164 goog.ui.ActivityMonitor.userTouchEventTypesBody_ = [
165 goog.events.EventType.TOUCHEND, goog.events.EventType.TOUCHMOVE,
166 goog.events.EventType.TOUCHSTART
167 ];
168
169
170 /**
171 * If a user executes one of these events, s/he is considered not idle.
172 * @type {Array<goog.events.EventType>}
173 * @private
174 */
175 goog.ui.ActivityMonitor.userEventTypesDocuments_ =
176 [goog.events.EventType.KEYDOWN, goog.events.EventType.KEYUP];
177
178
179 /**
180 * Event constants for the activity monitor.
181 * @enum {string}
182 */
183 goog.ui.ActivityMonitor.Event = {
184 /** Event fired when the user does something interactive */
185 ACTIVITY: 'activity'
186 };
187
188
189 /** @override */
190 goog.ui.ActivityMonitor.prototype.disposeInternal = function() {
191 goog.ui.ActivityMonitor.superClass_.disposeInternal.call(this);
192 this.eventHandler_.dispose();
193 this.eventHandler_ = null;
194 delete this.documents_;
195 };
196
197
198 /**
199 * Adds a document to those being monitored by this class.
200 *
201 * @param {Document} doc Document to monitor.
202 */
203 goog.ui.ActivityMonitor.prototype.addDocument = function(doc) {
204 if (goog.array.contains(this.documents_, doc)) {
205 return;
206 }
207 this.documents_.push(doc);
208 var useCapture = !this.useBubble_;
209
210 var eventsToListenTo = goog.array.concat(
211 goog.ui.ActivityMonitor.userEventTypesDocuments_,
212 goog.ui.ActivityMonitor.userEventTypesBody_);
213
214 if (!this.isIframe_) {
215 // Monitoring touch events in iframe causes problems interacting with text
216 // fields in iOS (input text, textarea, contenteditable, select/copy/paste),
217 // so just ignore these events. This shouldn't matter much given that a
218 // touchstart event followed by touchend event produces a click event,
219 // which is being monitored correctly.
220 goog.array.extend(
221 eventsToListenTo, goog.ui.ActivityMonitor.userTouchEventTypesBody_);
222 }
223
224 this.eventHandler_.listen(
225 doc, eventsToListenTo, this.handleEvent_, useCapture);
226 };
227
228
229 /**
230 * Removes a document from those being monitored by this class.
231 *
232 * @param {Document} doc Document to monitor.
233 */
234 goog.ui.ActivityMonitor.prototype.removeDocument = function(doc) {
235 if (this.isDisposed()) {
236 return;
237 }
238 goog.array.remove(this.documents_, doc);
239 var useCapture = !this.useBubble_;
240
241 var eventsToUnlistenTo = goog.array.concat(
242 goog.ui.ActivityMonitor.userEventTypesDocuments_,
243 goog.ui.ActivityMonitor.userEventTypesBody_);
244
245 if (!this.isIframe_) {
246 // See note above about monitoring touch events in iframe.
247 goog.array.extend(
248 eventsToUnlistenTo, goog.ui.ActivityMonitor.userTouchEventTypesBody_);
249 }
250
251 this.eventHandler_.unlisten(
252 doc, eventsToUnlistenTo, this.handleEvent_, useCapture);
253 };
254
255
256 /**
257 * Updates the last event time when a user action occurs.
258 * @param {goog.events.BrowserEvent} e Event object.
259 * @private
260 */
261 goog.ui.ActivityMonitor.prototype.handleEvent_ = function(e) {
262 var update = false;
263 switch (e.type) {
264 case goog.events.EventType.MOUSEMOVE:
265 // In FF 1.5, we get spurious mouseover and mouseout events when the UI
266 // redraws. We only want to update the idle time if the mouse has moved.
267 if (typeof this.lastMouseX_ == 'number' &&
268 this.lastMouseX_ != e.clientX ||
269 typeof this.lastMouseY_ == 'number' &&
270 this.lastMouseY_ != e.clientY) {
271 update = true;
272 }
273 this.lastMouseX_ = e.clientX;
274 this.lastMouseY_ = e.clientY;
275 break;
276 default:
277 update = true;
278 }
279
280 if (update) {
281 var type = goog.asserts.assertString(e.type);
282 this.updateIdleTime(goog.now(), type);
283 }
284 };
285
286
287 /**
288 * Updates the last event time to be the present time, useful for non-DOM
289 * events that should update idle time.
290 */
291 goog.ui.ActivityMonitor.prototype.resetTimer = function() {
292 this.updateIdleTime(goog.now(), 'manual');
293 };
294
295
296 /**
297 * Updates the idle time and fires an event if time has elapsed since
298 * the last update.
299 * @param {number} eventTime Time (in MS) of the event that cleared the idle
300 * timer.
301 * @param {string} eventType Type of the event, used only for debugging.
302 * @protected
303 */
304 goog.ui.ActivityMonitor.prototype.updateIdleTime = function(
305 eventTime, eventType) {
306 // update internal state noting whether the user was idle
307 this.lastEventTime_ = eventTime;
308 this.lastEventType_ = eventType;
309
310 // dispatch event
311 if (eventTime > this.minEventTime_) {
312 this.dispatchEvent(goog.ui.ActivityMonitor.Event.ACTIVITY);
313 this.minEventTime_ = eventTime + goog.ui.ActivityMonitor.MIN_EVENT_SPACING;
314 }
315 };
316
317
318 /**
319 * Returns the amount of time the user has been idle.
320 * @param {number=} opt_now The current time can optionally be passed in for the
321 * computation to avoid an extra Date allocation.
322 * @return {number} The amount of time in ms that the user has been idle.
323 */
324 goog.ui.ActivityMonitor.prototype.getIdleTime = function(opt_now) {
325 var now = opt_now || goog.now();
326 return now - this.lastEventTime_;
327 };
328
329
330 /**
331 * Returns the type of the last user event.
332 * @return {string} event type.
333 */
334 goog.ui.ActivityMonitor.prototype.getLastEventType = function() {
335 return this.lastEventType_;
336 };
337
338
339 /**
340 * Returns the time of the last event
341 * @return {number} last event time.
342 */
343 goog.ui.ActivityMonitor.prototype.getLastEventTime = function() {
344 return this.lastEventTime_;
345 };