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
};
194

195