Debian Codegraph @

closure-library/closure/goog/ui/containerscroller.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 Scroll behavior that can be added onto a container.
17 * @author [email protected] (Garry Boyer)
18 */
19
20 goog.provide('goog.ui.ContainerScroller');
21
22 goog.require('goog.Disposable');
23 goog.require('goog.Timer');
24 goog.require('goog.events.EventHandler');
25 goog.require('goog.style');
26 goog.require('goog.ui.Component');
27 goog.require('goog.ui.Container');
28
29
30
31 /**
32 * Plug-on scrolling behavior for a container.
33 *
34 * Use this to style containers, such as pop-up menus, to be scrolling, and
35 * automatically keep the highlighted element visible.
36 *
37 * To use this, first style your container with the desired overflow
38 * properties and height to achieve vertical scrolling. Also, the scrolling
39 * div should have no vertical padding, for two reasons: it is difficult to
40 * compensate for, and is generally not what you want due to the strange way
41 * CSS handles padding on the scrolling dimension.
42 *
43 * The container must already be rendered before this may be constructed.
44 *
45 * @param {!goog.ui.Container} container The container to attach behavior to.
46 * @constructor
47 * @extends {goog.Disposable}
48 * @final
49 */
50 goog.ui.ContainerScroller = function(container) {
51 goog.Disposable.call(this);
52
53 /**
54 * The container that we are bestowing scroll behavior on.
55 * @type {!goog.ui.Container}
56 * @private
57 */
58 this.container_ = container;
59
60 /**
61 * Event handler for this object.
62 * @type {!goog.events.EventHandler<!goog.ui.ContainerScroller>}
63 * @private
64 */
65 this.eventHandler_ = new goog.events.EventHandler(this);
66
67 this.eventHandler_.listen(
68 container, goog.ui.Component.EventType.HIGHLIGHT, this.onHighlight_);
69 this.eventHandler_.listen(
70 container, goog.ui.Component.EventType.ENTER, this.onEnter_);
71 this.eventHandler_.listen(
72 container, goog.ui.Container.EventType.AFTER_SHOW, this.onAfterShow_);
73 this.eventHandler_.listen(
74 container, goog.ui.Component.EventType.HIDE, this.onHide_);
75
76 // TODO(gboyer): Allow a ContainerScroller to be attached with a Container
77 // before the container is rendered.
78
79 this.doScrolling_(true);
80 };
81 goog.inherits(goog.ui.ContainerScroller, goog.Disposable);
82
83
84 /**
85 * The last target the user hovered over.
86 *
87 * @see #onEnter_
88 * @type {goog.ui.Component}
89 * @private
90 */
91 goog.ui.ContainerScroller.prototype.lastEnterTarget_ = null;
92
93
94 /**
95 * The scrollTop of the container before it was hidden.
96 * Used to restore the scroll position when the container is shown again.
97 * @type {?number}
98 * @private
99 */
100 goog.ui.ContainerScroller.prototype.scrollTopBeforeHide_ = null;
101
102
103 /**
104 * Whether we are disabling the default handler for hovering.
105 *
106 * @see #onEnter_
107 * @see #temporarilyDisableHover_
108 * @type {boolean}
109 * @private
110 */
111 goog.ui.ContainerScroller.prototype.disableHover_ = false;
112
113
114 /**
115 * Handles hover events on the container's children.
116 *
117 * Helps enforce two constraints: scrolling should not cause mouse highlights,
118 * and mouse highlights should not cause scrolling.
119 *
120 * @param {goog.events.Event} e The container's ENTER event.
121 * @private
122 */
123 goog.ui.ContainerScroller.prototype.onEnter_ = function(e) {
124 if (this.disableHover_) {
125 // The container was scrolled recently. Since the mouse may be over the
126 // container, stop the default action of the ENTER event from causing
127 // highlights.
128 e.preventDefault();
129 } else {
130 // The mouse is moving and causing hover events. Stop the resulting
131 // highlight (if it happens) from causing a scroll.
132 this.lastEnterTarget_ = /** @type {goog.ui.Component} */ (e.target);
133 }
134 };
135
136
137 /**
138 * Handles highlight events on the container's children.
139 * @param {goog.events.Event} e The container's highlight event.
140 * @private
141 */
142 goog.ui.ContainerScroller.prototype.onHighlight_ = function(e) {
143 this.doScrolling_();
144 };
145
146
147 /**
148 * Handles AFTER_SHOW events on the container. Makes the container
149 * scroll to the previously scrolled position (if there was one),
150 * then adjust it to make the highlighted element be in view (if there is one).
151 * If there was no previous scroll position, then center the highlighted
152 * element (if there is one).
153 * @param {goog.events.Event} e The container's AFTER_SHOW event.
154 * @private
155 */
156 goog.ui.ContainerScroller.prototype.onAfterShow_ = function(e) {
157 if (this.scrollTopBeforeHide_ != null) {
158 this.container_.getElement().scrollTop = this.scrollTopBeforeHide_;
159 // Make sure the highlighted item is still visible, in case the list
160 // or its hilighted item has changed.
161 this.doScrolling_(false);
162 } else {
163 this.doScrolling_(true);
164 }
165 };
166
167
168 /**
169 * Handles hide events on the container. Clears out the last enter target,
170 * since it is no longer applicable, and remembers the scroll position of
171 * the menu so that it can be restored when the menu is reopened.
172 * @param {goog.events.Event} e The container's hide event.
173 * @private
174 */
175 goog.ui.ContainerScroller.prototype.onHide_ = function(e) {
176 if (e.target == this.container_) {
177 this.lastEnterTarget_ = null;
178 this.scrollTopBeforeHide_ = this.container_.getElement().scrollTop;
179 }
180 };
181
182
183 /**
184 * Centers the currently highlighted item, if this is scrollable.
185 * @param {boolean=} opt_center Whether to center the highlighted element
186 * rather than simply ensure it is in view. Useful for the first
187 * render.
188 * @private
189 */
190 goog.ui.ContainerScroller.prototype.doScrolling_ = function(opt_center) {
191 var highlighted = this.container_.getHighlighted();
192
193 // Only scroll if we're visible and there is a highlighted item.
194 if (this.container_.isVisible() && highlighted &&
195 highlighted != this.lastEnterTarget_) {
196 var element = this.container_.getElement();
197 goog.style.scrollIntoContainerView(
198 highlighted.getElement(), element, opt_center);
199 this.temporarilyDisableHover_();
200 this.lastEnterTarget_ = null;
201 }
202 };
203
204
205 /**
206 * Temporarily disables hover events from changing highlight.
207 * @see #onEnter_
208 * @private
209 */
210 goog.ui.ContainerScroller.prototype.temporarilyDisableHover_ = function() {
211 this.disableHover_ = true;
212 goog.Timer.callOnce(function() { this.disableHover_ = false; }, 0, this);
213 };
214
215
216 /** @override */
217 goog.ui.ContainerScroller.prototype.disposeInternal = function() {
218 goog.ui.ContainerScroller.superClass_.disposeInternal.call(this);
219 this.eventHandler_.dispose();
220 this.lastEnterTarget_ = null;
221 };