Debian Codegraph @

closure-library/closure/goog/ui/iframemask.js

raw
1 // Copyright 2008 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 Iframe shims, to protect controls on the underlying page
17 * from bleeding through popups.
18 *
19 * @author [email protected] (Garrett Boyer)
20 * @author [email protected] (Nick Santos) (Ported to Closure)
21 */
22
23
24 goog.provide('goog.ui.IframeMask');
25
26 goog.require('goog.Disposable');
27 goog.require('goog.Timer');
28 goog.require('goog.dom');
29 goog.require('goog.dom.iframe');
30 goog.require('goog.events.EventHandler');
31 goog.require('goog.structs.Pool');
32 goog.require('goog.style');
33
34
35
36 /**
37 * Controller for an iframe mask. The mask is only valid in the current
38 * document, or else the document of the given DOM helper.
39 *
40 * @param {goog.dom.DomHelper=} opt_domHelper The DOM helper for the relevant
41 * document.
42 * @param {goog.structs.Pool=} opt_iframePool An optional source of iframes.
43 * Iframes will be grabbed from the pool when they're needed and returned
44 * to the pool (but still attached to the DOM) when they're done.
45 * @constructor
46 * @extends {goog.Disposable}
47 */
48 goog.ui.IframeMask = function(opt_domHelper, opt_iframePool) {
49 goog.Disposable.call(this);
50
51 /**
52 * The DOM helper for this document.
53 * @type {goog.dom.DomHelper}
54 * @private
55 */
56 this.dom_ = opt_domHelper || goog.dom.getDomHelper();
57
58 /**
59 * An Element to snap the mask to. If none is given, defaults to
60 * a full-screen iframe mask.
61 * @type {Element}
62 * @private
63 */
64 this.snapElement_ = this.dom_.getDocument().documentElement;
65
66 /**
67 * An event handler for listening to popups and the like.
68 * @type {goog.events.EventHandler<!goog.ui.IframeMask>}
69 * @private
70 */
71 this.handler_ = new goog.events.EventHandler(this);
72
73 /**
74 * An iframe pool.
75 * @type {goog.structs.Pool|undefined}
76 * @private
77 */
78 this.iframePool_ = opt_iframePool;
79 };
80 goog.inherits(goog.ui.IframeMask, goog.Disposable);
81 goog.tagUnsealableClass(goog.ui.IframeMask);
82
83
84 /**
85 * An iframe.
86 * @type {HTMLIFrameElement}
87 * @private
88 */
89 goog.ui.IframeMask.prototype.iframe_;
90
91
92 /**
93 * The z-index of the iframe mask.
94 * @type {number}
95 * @private
96 */
97 goog.ui.IframeMask.prototype.zIndex_ = 1;
98
99
100 /**
101 * The opacity of the iframe mask, expressed as a value between 0 and 1, with
102 * 1 being totally opaque.
103 * @type {number}
104 * @private
105 */
106 goog.ui.IframeMask.prototype.opacity_ = 0;
107
108
109 /**
110 * Removes the iframe from the DOM.
111 * @override
112 * @protected
113 */
114 goog.ui.IframeMask.prototype.disposeInternal = function() {
115 if (this.iframePool_) {
116 this.iframePool_.releaseObject(
117 /** @type {HTMLIFrameElement} */ (this.iframe_));
118 } else {
119 goog.dom.removeNode(this.iframe_);
120 }
121 this.iframe_ = null;
122
123 this.handler_.dispose();
124 this.handler_ = null;
125
126 goog.ui.IframeMask.superClass_.disposeInternal.call(this);
127 };
128
129
130 /**
131 * CSS for a hidden iframe.
132 * @type {string}
133 * @private
134 */
135 goog.ui.IframeMask.HIDDEN_CSS_TEXT_ =
136 'position:absolute;display:none;z-index:1';
137
138
139 /**
140 * Removes the mask from the screen.
141 */
142 goog.ui.IframeMask.prototype.hideMask = function() {
143 if (this.iframe_) {
144 this.iframe_.style.cssText = goog.ui.IframeMask.HIDDEN_CSS_TEXT_;
145 if (this.iframePool_) {
146 this.iframePool_.releaseObject(this.iframe_);
147 this.iframe_ = null;
148 }
149 }
150 };
151
152
153 /**
154 * Gets the iframe to use as a mask. Creates a new one if one has not been
155 * created yet.
156 * @return {!HTMLIFrameElement} The iframe.
157 * @private
158 */
159 goog.ui.IframeMask.prototype.getIframe_ = function() {
160 if (!this.iframe_) {
161 this.iframe_ = this.iframePool_ ?
162 /** @type {HTMLIFrameElement} */ (this.iframePool_.getObject()) :
163 goog.dom.iframe.createBlank(this.dom_);
164 this.iframe_.style.cssText = goog.ui.IframeMask.HIDDEN_CSS_TEXT_;
165 this.dom_.getDocument().body.appendChild(this.iframe_);
166 }
167 return this.iframe_;
168 };
169
170
171 /**
172 * Applies the iframe mask to the screen.
173 */
174 goog.ui.IframeMask.prototype.applyMask = function() {
175 var iframe = this.getIframe_();
176 var bounds = goog.style.getBounds(this.snapElement_);
177 iframe.style.cssText = 'position:absolute;' +
178 'left:' + bounds.left + 'px;' +
179 'top:' + bounds.top + 'px;' +
180 'width:' + bounds.width + 'px;' +
181 'height:' + bounds.height + 'px;' +
182 'z-index:' + this.zIndex_;
183 goog.style.setOpacity(iframe, this.opacity_);
184 iframe.style.display = 'block';
185 };
186
187
188 /**
189 * Sets the opacity of the mask. Will take effect the next time the mask
190 * is applied.
191 * @param {number} opacity A value between 0 and 1, with 1 being
192 * totally opaque.
193 */
194 goog.ui.IframeMask.prototype.setOpacity = function(opacity) {
195 this.opacity_ = opacity;
196 };
197
198
199 /**
200 * Sets the z-index of the mask. Will take effect the next time the mask
201 * is applied.
202 * @param {number} zIndex A z-index value.
203 */
204 goog.ui.IframeMask.prototype.setZIndex = function(zIndex) {
205 this.zIndex_ = zIndex;
206 };
207
208
209 /**
210 * Sets the element to use as the bounds of the mask. Takes effect immediately.
211 * @param {Element} snapElement The snap element, which the iframe will be
212 * "snapped" around.
213 */
214 goog.ui.IframeMask.prototype.setSnapElement = function(snapElement) {
215 this.snapElement_ = snapElement;
216 if (this.iframe_ && goog.style.isElementShown(this.iframe_)) {
217 this.applyMask();
218 }
219 };
220
221
222 /**
223 * Listens on the specified target, hiding and showing the iframe mask
224 * when the given event types are dispatched.
225 * @param {goog.events.EventTarget} target The event target to listen on.
226 * @param {string} showEvent When this event fires, the mask will be applied.
227 * @param {string} hideEvent When this event fires, the mask will be hidden.
228 * @param {Element=} opt_snapElement When the mask is applied, it will
229 * automatically snap to this element. If no element is specified, it will
230 * use the default snap element.
231 */
232 goog.ui.IframeMask.prototype.listenOnTarget = function(
233 target, showEvent, hideEvent, opt_snapElement) {
234 var timerKey;
235 this.handler_.listen(target, showEvent, function() {
236 if (opt_snapElement) {
237 this.setSnapElement(opt_snapElement);
238 }
239 // Check out the iframe asynchronously, so we don't block the SHOW
240 // event and cause a bounce.
241 timerKey = goog.Timer.callOnce(this.applyMask, 0, this);
242 });
243 this.handler_.listen(target, hideEvent, function() {
244 if (timerKey) {
245 goog.Timer.clear(timerKey);
246 timerKey = null;
247 }
248 this.hideMask();
249 });
250 };
251
252
253 /**
254 * Removes all handlers attached by listenOnTarget.
255 */
256 goog.ui.IframeMask.prototype.removeHandlers = function() {
257 this.handler_.removeAll();
258 };