Debian Codegraph @

closure-library/closure/goog/async/delay.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 Defines a class useful for handling functions that must be
17 * invoked after a delay, especially when that delay is frequently restarted.
18 * Examples include delaying before displaying a tooltip, menu hysteresis,
19 * idle timers, etc.
20 * @author [email protected] (Shawn Brenneman)
21 * @see ../demos/timers.html
22 */
23
24
25 goog.provide('goog.Delay');
26 goog.provide('goog.async.Delay');
27
28 goog.require('goog.Disposable');
29 goog.require('goog.Timer');
30
31
32
33 /**
34 * A Delay object invokes the associated function after a specified delay. The
35 * interval duration can be specified once in the constructor, or can be defined
36 * each time the delay is started. Calling start on an active delay will reset
37 * the timer.
38 *
39 * @param {function(this:THIS)} listener Function to call when the
40 * delay completes.
41 * @param {number=} opt_interval The default length of the invocation delay (in
42 * milliseconds).
43 * @param {THIS=} opt_handler The object scope to invoke the function in.
44 * @template THIS
45 * @constructor
46 * @struct
47 * @extends {goog.Disposable}
48 * @final
49 */
50 goog.async.Delay = function(listener, opt_interval, opt_handler) {
51 goog.async.Delay.base(this, 'constructor');
52
53 /**
54 * The function that will be invoked after a delay.
55 * @private {function(this:THIS)}
56 */
57 this.listener_ = listener;
58
59 /**
60 * The default amount of time to delay before invoking the callback.
61 * @type {number}
62 * @private
63 */
64 this.interval_ = opt_interval || 0;
65
66 /**
67 * The object context to invoke the callback in.
68 * @type {Object|undefined}
69 * @private
70 */
71 this.handler_ = opt_handler;
72
73
74 /**
75 * Cached callback function invoked when the delay finishes.
76 * @type {Function}
77 * @private
78 */
79 this.callback_ = goog.bind(this.doAction_, this);
80 };
81 goog.inherits(goog.async.Delay, goog.Disposable);
82
83
84
85 /**
86 * A deprecated alias.
87 * @deprecated Use goog.async.Delay instead.
88 * @constructor
89 * @final
90 */
91 goog.Delay = goog.async.Delay;
92
93
94 /**
95 * Identifier of the active delay timeout, or 0 when inactive.
96 * @type {number}
97 * @private
98 */
99 goog.async.Delay.prototype.id_ = 0;
100
101
102 /**
103 * Disposes of the object, cancelling the timeout if it is still outstanding and
104 * removing all object references.
105 * @override
106 * @protected
107 */
108 goog.async.Delay.prototype.disposeInternal = function() {
109 goog.async.Delay.base(this, 'disposeInternal');
110 this.stop();
111 delete this.listener_;
112 delete this.handler_;
113 };
114
115
116 /**
117 * Starts the delay timer. The provided listener function will be called after
118 * the specified interval. Calling start on an active timer will reset the
119 * delay interval.
120 * @param {number=} opt_interval If specified, overrides the object's default
121 * interval with this one (in milliseconds).
122 */
123 goog.async.Delay.prototype.start = function(opt_interval) {
124 this.stop();
125 this.id_ = goog.Timer.callOnce(
126 this.callback_, goog.isDef(opt_interval) ? opt_interval : this.interval_);
127 };
128
129
130 /**
131 * Starts the delay timer if it's not already active.
132 * @param {number=} opt_interval If specified and the timer is not already
133 * active, overrides the object's default interval with this one (in
134 * milliseconds).
135 */
136 goog.async.Delay.prototype.startIfNotActive = function(opt_interval) {
137 if (!this.isActive()) {
138 this.start(opt_interval);
139 }
140 };
141
142
143 /**
144 * Stops the delay timer if it is active. No action is taken if the timer is not
145 * in use.
146 */
147 goog.async.Delay.prototype.stop = function() {
148 if (this.isActive()) {
149 goog.Timer.clear(this.id_);
150 }
151 this.id_ = 0;
152 };
153
154
155 /**
156 * Fires delay's action even if timer has already gone off or has not been
157 * started yet; guarantees action firing. Stops the delay timer.
158 */
159 goog.async.Delay.prototype.fire = function() {
160 this.stop();
161 this.doAction_();
162 };
163
164
165 /**
166 * Fires delay's action only if timer is currently active. Stops the delay
167 * timer.
168 */
169 goog.async.Delay.prototype.fireIfActive = function() {
170 if (this.isActive()) {
171 this.fire();
172 }
173 };
174
175
176 /**
177 * @return {boolean} True if the delay is currently active, false otherwise.
178 */
179 goog.async.Delay.prototype.isActive = function() {
180 return this.id_ != 0;
181 };
182
183
184 /**
185 * Invokes the callback function after the delay successfully completes.
186 * @private
187 */
188 goog.async.Delay.prototype.doAction_ = function() {
189 this.id_ = 0;
190 if (this.listener_) {
191 this.listener_.call(this.handler_);
192 }
193 };