1
// Copyright 2013 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 This event monitor wraps the Page Visibility API.
17
 * @see http://www.w3.org/TR/page-visibility/
18
 */
19

20
goog.provide('goog.labs.dom.PageVisibilityEvent');
21
goog.provide('goog.labs.dom.PageVisibilityMonitor');
22
goog.provide('goog.labs.dom.PageVisibilityState');
23

24
goog.require('goog.dom');
25
goog.require('goog.dom.vendor');
26
goog.require('goog.events');
27
goog.require('goog.events.Event');
28
goog.require('goog.events.EventTarget');
29
goog.require('goog.events.EventType');
30
goog.require('goog.memoize');
31

32

33
/**
34
 * The different visibility states.
35
 * @enum {string}
36
 */
37
goog.labs.dom.PageVisibilityState = {
38
  HIDDEN: 'hidden',
39
  VISIBLE: 'visible',
40
  PRERENDER: 'prerender',
41
  UNLOADED: 'unloaded'
42
};
43

44

45

46
/**
47
 * This event handler allows you to catch page visibility change events.
48
 * @param {!goog.dom.DomHelper=} opt_domHelper
49
 * @constructor
50
 * @extends {goog.events.EventTarget}
51
 * @final
52
 */
53
goog.labs.dom.PageVisibilityMonitor = function(opt_domHelper) {
54
  goog.labs.dom.PageVisibilityMonitor.base(this, 'constructor');
55

56
  /**
57
   * @private {!goog.dom.DomHelper}
58
   */
59
  this.domHelper_ = opt_domHelper || goog.dom.getDomHelper();
60

61
  /**
62
   * @private {?string}
63
   */
64
  this.eventType_ = this.getBrowserEventType_();
65

66
  // Some browsers do not support visibilityChange and therefore we don't bother
67
  // setting up events.
68
  if (this.eventType_) {
69
    /**
70
     * @private {goog.events.Key}
71
     */
72
    this.eventKey_ = goog.events.listen(
73
        this.domHelper_.getDocument(), this.eventType_,
74
        goog.bind(this.handleChange_, this));
75
  }
76
};
77
goog.inherits(goog.labs.dom.PageVisibilityMonitor, goog.events.EventTarget);
78

79

80
/**
81
 * @return {?string} The visibility change event type, or null if not supported.
82
 *     Memoized for performance.
83
 * @private
84
 */
85
goog.labs.dom.PageVisibilityMonitor.prototype
86
    .getBrowserEventType_ = goog.memoize(function() {
87
  var isSupported =
88
      /** @type {!goog.labs.dom.PageVisibilityMonitor} */ (this).isSupported();
89
  var isPrefixed =
90
      /** @type {!goog.labs.dom.PageVisibilityMonitor} */ (this).isPrefixed_();
91

92
  if (isSupported) {
93
    return isPrefixed ?
94
        goog.dom.vendor.getPrefixedEventType(
95
            goog.events.EventType.VISIBILITYCHANGE) :
96
        goog.events.EventType.VISIBILITYCHANGE;
97
  } else {
98
    return null;
99
  }
100
});
101

102

103
/**
104
 * @return {?string} The browser-specific document.hidden property.  Memoized
105
 *     for performance.
106
 * @private
107
 */
108
goog.labs.dom.PageVisibilityMonitor.prototype.getHiddenPropertyName_ =
109
    goog.memoize(function() {
110
      return goog.dom.vendor.getPrefixedPropertyName(
111
          'hidden',
112
          /** @type {!goog.labs.dom.PageVisibilityMonitor} */
113
          (this).domHelper_.getDocument());
114
    });
115

116

117
/**
118
 * @return {boolean} Whether the visibility API is prefixed.
119
 * @private
120
 */
121
goog.labs.dom.PageVisibilityMonitor.prototype.isPrefixed_ = function() {
122
  return this.getHiddenPropertyName_() != 'hidden';
123
};
124

125

126
/**
127
 * @return {?string} The browser-specific document.visibilityState property.
128
 *     Memoized for performance.
129
 * @private
130
 */
131
goog.labs.dom.PageVisibilityMonitor.prototype.getVisibilityStatePropertyName_ =
132
    goog.memoize(function() {
133
      return goog.dom.vendor.getPrefixedPropertyName(
134
          'visibilityState',
135
          /** @type {!goog.labs.dom.PageVisibilityMonitor} */
136
          (this).domHelper_.getDocument());
137
    });
138

139

140
/**
141
 * @return {boolean} Whether the visibility API is supported.
142
 */
143
goog.labs.dom.PageVisibilityMonitor.prototype.isSupported = function() {
144
  return !!this.getHiddenPropertyName_();
145
};
146

147

148
/**
149
 * @return {boolean} Whether the page is visible.
150
 */
151
goog.labs.dom.PageVisibilityMonitor.prototype.isHidden = function() {
152
  return !!this.domHelper_.getDocument()[this.getHiddenPropertyName_()];
153
};
154

155

156
/**
157
 * @return {?goog.labs.dom.PageVisibilityState} The page visibility state, or
158
 *     null if not supported.
159
 */
160
goog.labs.dom.PageVisibilityMonitor.prototype.getVisibilityState = function() {
161
  if (!this.isSupported()) {
162
    return null;
163
  }
164
  return this.domHelper_.getDocument()[this.getVisibilityStatePropertyName_()];
165
};
166

167

168
/**
169
 * Handles the events on the element.
170
 * @param {goog.events.BrowserEvent} e The underlying browser event.
171
 * @private
172
 */
173
goog.labs.dom.PageVisibilityMonitor.prototype.handleChange_ = function(e) {
174
  var state = this.getVisibilityState();
175
  var visibilityEvent = new goog.labs.dom.PageVisibilityEvent(
176
      this.isHidden(),
177
      /** @type {goog.labs.dom.PageVisibilityState} */ (state));
178
  this.dispatchEvent(visibilityEvent);
179
};
180

181

182
/** @override */
183
goog.labs.dom.PageVisibilityMonitor.prototype.disposeInternal = function() {
184
  goog.events.unlistenByKey(this.eventKey_);
185
  goog.labs.dom.PageVisibilityMonitor.base(this, 'disposeInternal');
186
};
187

188

189

190
/**
191
 * A page visibility change event.
192
 * @param {boolean} hidden Whether the page is hidden.
193
 * @param {goog.labs.dom.PageVisibilityState} visibilityState A more detailed
194
 *     visibility state.
195
 * @constructor
196
 * @extends {goog.events.Event}
197
 * @final
198
 */
199
goog.labs.dom.PageVisibilityEvent = function(hidden, visibilityState) {
200
  goog.labs.dom.PageVisibilityEvent.base(
201
      this, 'constructor', goog.events.EventType.VISIBILITYCHANGE);
202

203
  /**
204
   * Whether the page is hidden.
205
   * @type {boolean}
206
   */
207
  this.hidden = hidden;
208

209
  /**
210
   * A more detailed visibility state.
211
   * @type {goog.labs.dom.PageVisibilityState}
212
   */
213
  this.visibilityState = visibilityState;
214
};
215
goog.inherits(goog.labs.dom.PageVisibilityEvent, goog.events.Event);
216

217