Debian Codegraph @

closure-library/closure/goog/ui/idletimer.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 Idle Timer.
17 *
18 * Keeps track of transitions between active and idle. This class is built on
19 * top of ActivityMonitor. Whenever an active user becomes idle, this class
20 * dispatches a BECOME_IDLE event. Whenever an idle user becomes active, this
21 * class dispatches a BECOME_ACTIVE event. The amount of inactive time it
22 * takes for a user to be considered idle is specified by the client, and
23 * different instances of this class can all use different thresholds.
24 *
25 */
26
27 goog.provide('goog.ui.IdleTimer');
28 goog.require('goog.Timer');
29 goog.require('goog.events');
30 goog.require('goog.events.EventTarget');
31 goog.require('goog.structs.Set');
32 goog.require('goog.ui.ActivityMonitor');
33
34
35
36 /**
37 * Event target that will give notification of state changes between active and
38 * idle. This class is designed to require few resources while the user is
39 * active.
40 * @param {number} idleThreshold Amount of time in ms at which we consider the
41 * user has gone idle.
42 * @param {goog.ui.ActivityMonitor=} opt_activityMonitor The activity monitor
43 * keeping track of user interaction. Defaults to a default-constructed
44 * activity monitor. If a default activity monitor is used then this class
45 * will dispose of it. If an activity monitor is passed in then the caller
46 * remains responsible for disposing of it.
47 * @constructor
48 * @extends {goog.events.EventTarget}
49 * @final
50 */
51 goog.ui.IdleTimer = function(idleThreshold, opt_activityMonitor) {
52 goog.events.EventTarget.call(this);
53
54 var activityMonitor =
55 opt_activityMonitor || this.getDefaultActivityMonitor_();
56
57 /**
58 * The amount of time in ms at which we consider the user has gone idle
59 * @type {number}
60 * @private
61 */
62 this.idleThreshold_ = idleThreshold;
63
64 /**
65 * The activity monitor keeping track of user interaction
66 * @type {goog.ui.ActivityMonitor}
67 * @private
68 */
69 this.activityMonitor_ = activityMonitor;
70
71 /**
72 * Cached onActivityTick_ bound to the object for later use
73 * @type {Function}
74 * @private
75 */
76 this.boundOnActivityTick_ = goog.bind(this.onActivityTick_, this);
77
78 // Decide whether the user is currently active or idle. This method will
79 // check whether it is correct to start with the user in the active state.
80 this.maybeStillActive_();
81 };
82 goog.inherits(goog.ui.IdleTimer, goog.events.EventTarget);
83
84
85 /**
86 * Whether a listener is currently registered for an idle timer event. On
87 * initialization, the user is assumed to be active.
88 * @type {boolean}
89 * @private
90 */
91 goog.ui.IdleTimer.prototype.hasActivityListener_ = false;
92
93
94 /**
95 * Handle to the timer ID used for checking ongoing activity, or null
96 * @type {?number}
97 * @private
98 */
99 goog.ui.IdleTimer.prototype.onActivityTimerId_ = null;
100
101
102 /**
103 * Whether the user is currently idle
104 * @type {boolean}
105 * @private
106 */
107 goog.ui.IdleTimer.prototype.isIdle_ = false;
108
109
110 /**
111 * The default activity monitor created by this class, if any
112 * @type {goog.ui.ActivityMonitor?}
113 * @private
114 */
115 goog.ui.IdleTimer.defaultActivityMonitor_ = null;
116
117
118 /**
119 * The idle timers that currently reference the default activity monitor
120 * @type {goog.structs.Set}
121 * @private
122 */
123 goog.ui.IdleTimer.defaultActivityMonitorReferences_ = new goog.structs.Set();
124
125
126 /**
127 * Event constants for the idle timer event target
128 * @enum {string}
129 */
130 goog.ui.IdleTimer.Event = {
131 /** Event fired when an idle user transitions into the active state */
132 BECOME_ACTIVE: 'active',
133 /** Event fired when an active user transitions into the idle state */
134 BECOME_IDLE: 'idle'
135 };
136
137
138 /**
139 * Gets the default activity monitor used by this class. If a default has not
140 * been created yet, then a new one will be created.
141 * @return {!goog.ui.ActivityMonitor} The default activity monitor.
142 * @private
143 */
144 goog.ui.IdleTimer.prototype.getDefaultActivityMonitor_ = function() {
145 goog.ui.IdleTimer.defaultActivityMonitorReferences_.add(this);
146 if (goog.ui.IdleTimer.defaultActivityMonitor_ == null) {
147 goog.ui.IdleTimer.defaultActivityMonitor_ = new goog.ui.ActivityMonitor();
148 }
149 return goog.ui.IdleTimer.defaultActivityMonitor_;
150 };
151
152
153 /**
154 * Removes the reference to the default activity monitor. If there are no more
155 * references then the default activity monitor gets disposed.
156 * @private
157 */
158 goog.ui.IdleTimer.prototype.maybeDisposeDefaultActivityMonitor_ = function() {
159 goog.ui.IdleTimer.defaultActivityMonitorReferences_.remove(this);
160 if (goog.ui.IdleTimer.defaultActivityMonitor_ != null &&
161 goog.ui.IdleTimer.defaultActivityMonitorReferences_.isEmpty()) {
162 goog.ui.IdleTimer.defaultActivityMonitor_.dispose();
163 goog.ui.IdleTimer.defaultActivityMonitor_ = null;
164 }
165 };
166
167
168 /**
169 * Checks whether the user is active. If the user is still active, then a timer
170 * is started to check again later.
171 * @private
172 */
173 goog.ui.IdleTimer.prototype.maybeStillActive_ = function() {
174 // See how long before the user would go idle. The user is considered idle
175 // after the idle time has passed, not exactly when the idle time arrives.
176 var remainingIdleThreshold = this.idleThreshold_ + 1 -
177 (goog.now() - this.activityMonitor_.getLastEventTime());
178 if (remainingIdleThreshold > 0) {
179 // The user is still active. Check again later.
180 this.onActivityTimerId_ =
181 goog.Timer.callOnce(this.boundOnActivityTick_, remainingIdleThreshold);
182 } else {
183 // The user has not been active recently.
184 this.becomeIdle_();
185 }
186 };
187
188
189 /**
190 * Handler for the timeout used for checking ongoing activity
191 * @private
192 */
193 goog.ui.IdleTimer.prototype.onActivityTick_ = function() {
194 // The timer has fired.
195 this.onActivityTimerId_ = null;
196
197 // The maybeStillActive method will restart the timer, if appropriate.
198 this.maybeStillActive_();
199 };
200
201
202 /**
203 * Transitions from the active state to the idle state
204 * @private
205 */
206 goog.ui.IdleTimer.prototype.becomeIdle_ = function() {
207 this.isIdle_ = true;
208
209 // The idle timer will send notification when the user does something
210 // interactive.
211 goog.events.listen(
212 this.activityMonitor_, goog.ui.ActivityMonitor.Event.ACTIVITY,
213 this.onActivity_, false, this);
214 this.hasActivityListener_ = true;
215
216 // Notify clients of the state change.
217 this.dispatchEvent(goog.ui.IdleTimer.Event.BECOME_IDLE);
218 };
219
220
221 /**
222 * Handler for idle timer events when the user does something interactive
223 * @param {goog.events.Event} e The event object.
224 * @private
225 */
226 goog.ui.IdleTimer.prototype.onActivity_ = function(e) {
227 this.becomeActive_();
228 };
229
230
231 /**
232 * Transitions from the idle state to the active state
233 * @private
234 */
235 goog.ui.IdleTimer.prototype.becomeActive_ = function() {
236 this.isIdle_ = false;
237
238 // Stop listening to every interactive event.
239 this.removeActivityListener_();
240
241 // Notify clients of the state change.
242 this.dispatchEvent(goog.ui.IdleTimer.Event.BECOME_ACTIVE);
243
244 // Periodically check whether the user has gone inactive.
245 this.maybeStillActive_();
246 };
247
248
249 /**
250 * Removes the activity listener, if necessary
251 * @private
252 */
253 goog.ui.IdleTimer.prototype.removeActivityListener_ = function() {
254 if (this.hasActivityListener_) {
255 goog.events.unlisten(
256 this.activityMonitor_, goog.ui.ActivityMonitor.Event.ACTIVITY,
257 this.onActivity_, false, this);
258 this.hasActivityListener_ = false;
259 }
260 };
261
262
263 /** @override */
264 goog.ui.IdleTimer.prototype.disposeInternal = function() {
265 this.removeActivityListener_();
266 if (this.onActivityTimerId_ != null) {
267 goog.global.clearTimeout(this.onActivityTimerId_);
268 this.onActivityTimerId_ = null;
269 }
270 this.maybeDisposeDefaultActivityMonitor_();
271 goog.ui.IdleTimer.superClass_.disposeInternal.call(this);
272 };
273
274
275 /**
276 * @return {number} the amount of time at which we consider the user has gone
277 * idle in ms.
278 */
279 goog.ui.IdleTimer.prototype.getIdleThreshold = function() {
280 return this.idleThreshold_;
281 };
282
283
284 /**
285 * @return {goog.ui.ActivityMonitor} the activity monitor keeping track of user
286 * interaction.
287 */
288 goog.ui.IdleTimer.prototype.getActivityMonitor = function() {
289 return this.activityMonitor_;
290 };
291
292
293 /**
294 * Returns true if there has been no user action for at least the specified
295 * interval, and false otherwise
296 * @return {boolean} true if the user is idle, false otherwise.
297 */
298 goog.ui.IdleTimer.prototype.isIdle = function() {
299 return this.isIdle_;
300 };