Debian Codegraph @

closure-library/closure/goog/labs/dom/pagevisibilitymonitor.js

raw
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);