Debian Codegraph @

closure-library/closure/goog/fx/dragscrollsupport.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 Class to support scrollable containers for drag and drop.
17 *
18 * @author [email protected] (Damian Gajda)
19 */
20
21 goog.provide('goog.fx.DragScrollSupport');
22
23 goog.require('goog.Disposable');
24 goog.require('goog.Timer');
25 goog.require('goog.dom');
26 goog.require('goog.events.EventHandler');
27 goog.require('goog.events.EventType');
28 goog.require('goog.math.Coordinate');
29 goog.require('goog.style');
30
31
32
33 /**
34 * A scroll support class. Currently this class will automatically scroll
35 * a scrollable container node and scroll it by a fixed amount at a timed
36 * interval when the mouse is moved above or below the container or in vertical
37 * margin areas. Intended for use in drag and drop. This could potentially be
38 * made more general and could support horizontal scrolling.
39 *
40 * @param {Element} containerNode A container that can be scrolled.
41 * @param {number=} opt_margin Optional margin to use while scrolling.
42 * @param {boolean=} opt_externalMouseMoveTracking Whether mouse move events
43 * are tracked externally by the client object which calls the mouse move
44 * event handler, useful when events are generated for more than one source
45 * element and/or are not real mousemove events.
46 * @constructor
47 * @struct
48 * @extends {goog.Disposable}
49 * @see ../demos/dragscrollsupport.html
50 */
51 goog.fx.DragScrollSupport = function(
52 containerNode, opt_margin, opt_externalMouseMoveTracking) {
53 goog.fx.DragScrollSupport.base(this, 'constructor');
54
55 /**
56 * Whether scrolling should be constrained to happen only when the cursor is
57 * inside the container node.
58 * @private {boolean}
59 */
60 this.constrainScroll_ = false;
61
62 /**
63 * Whether horizontal scrolling is allowed.
64 * @private {boolean}
65 */
66 this.horizontalScrolling_ = true;
67
68 /**
69 * The container to be scrolled.
70 * @type {Element}
71 * @private
72 */
73 this.containerNode_ = containerNode;
74
75 /**
76 * Scroll timer that will scroll the container until it is stopped.
77 * It will scroll when the mouse is outside the scrolling area of the
78 * container.
79 *
80 * @type {goog.Timer}
81 * @private
82 */
83 this.scrollTimer_ = new goog.Timer(goog.fx.DragScrollSupport.TIMER_STEP_);
84
85 /**
86 * EventHandler used to set up and tear down listeners.
87 * @type {goog.events.EventHandler<!goog.fx.DragScrollSupport>}
88 * @private
89 */
90 this.eventHandler_ = new goog.events.EventHandler(this);
91
92 /**
93 * The current scroll delta.
94 * @type {goog.math.Coordinate}
95 * @private
96 */
97 this.scrollDelta_ = new goog.math.Coordinate();
98
99 /**
100 * The container bounds.
101 * @type {goog.math.Rect}
102 * @private
103 */
104 this.containerBounds_ = goog.style.getBounds(containerNode);
105 if (containerNode.tagName === 'BODY' || containerNode.tagName === 'HTML') {
106 var size = goog.dom.getViewportSize();
107 this.containerBounds_.height = size.height;
108 this.containerBounds_.width = size.width;
109 }
110
111 /**
112 * The margin for triggering a scroll.
113 * @type {number}
114 * @private
115 */
116 this.margin_ = opt_margin || 0;
117
118 /**
119 * The bounding rectangle which if left triggers scrolling.
120 * @type {goog.math.Rect}
121 * @private
122 */
123 this.scrollBounds_ = opt_margin ?
124 this.constrainBounds_(this.containerBounds_.clone()) :
125 this.containerBounds_;
126
127 this.setupListeners_(!!opt_externalMouseMoveTracking);
128 };
129 goog.inherits(goog.fx.DragScrollSupport, goog.Disposable);
130
131
132 /**
133 * The scroll timer step in ms.
134 * @type {number}
135 * @private
136 */
137 goog.fx.DragScrollSupport.TIMER_STEP_ = 50;
138
139
140 /**
141 * The scroll step in pixels.
142 * @type {number}
143 * @private
144 */
145 goog.fx.DragScrollSupport.SCROLL_STEP_ = 8;
146
147
148 /**
149 * The suggested scrolling margin.
150 * @type {number}
151 */
152 goog.fx.DragScrollSupport.MARGIN = 32;
153
154
155 /**
156 * Sets whether scrolling should be constrained to happen only when the cursor
157 * is inside the container node.
158 * NOTE: If a margin is not set, then it does not make sense to
159 * contain the scroll, because in that case scroll will never be triggered.
160 * @param {boolean} constrain Whether scrolling should be constrained to happen
161 * only when the cursor is inside the container node.
162 */
163 goog.fx.DragScrollSupport.prototype.setConstrainScroll = function(constrain) {
164 this.constrainScroll_ = !!this.margin_ && constrain;
165 };
166
167
168 /**
169 * Sets whether horizontal scrolling is allowed.
170 * @param {boolean} scrolling Whether horizontal scrolling is allowed.
171 */
172 goog.fx.DragScrollSupport.prototype.setHorizontalScrolling = function(
173 scrolling) {
174 this.horizontalScrolling_ = scrolling;
175 };
176
177
178 /**
179 * Constrains the container bounds with respect to the margin.
180 *
181 * @param {goog.math.Rect} bounds The container element.
182 * @return {goog.math.Rect} The bounding rectangle used to calculate scrolling
183 * direction.
184 * @private
185 */
186 goog.fx.DragScrollSupport.prototype.constrainBounds_ = function(bounds) {
187 var margin = this.margin_;
188 if (margin) {
189 var quarterHeight = bounds.height * 0.25;
190 var yMargin = Math.min(margin, quarterHeight);
191 bounds.top += yMargin;
192 bounds.height -= 2 * yMargin;
193
194 var quarterWidth = bounds.width * 0.25;
195 var xMargin = Math.min(margin, quarterWidth);
196 bounds.left += xMargin;
197 bounds.width -= 2 * xMargin;
198 }
199 return bounds;
200 };
201
202
203 /**
204 * Attaches listeners and activates automatic scrolling.
205 * @param {boolean} externalMouseMoveTracking Whether to enable internal
206 * mouse move event handling.
207 * @private
208 */
209 goog.fx.DragScrollSupport.prototype.setupListeners_ = function(
210 externalMouseMoveTracking) {
211 if (!externalMouseMoveTracking) {
212 // Track mouse pointer position to determine scroll direction.
213 this.eventHandler_.listen(
214 goog.dom.getOwnerDocument(this.containerNode_),
215 goog.events.EventType.MOUSEMOVE, this.onMouseMove);
216 }
217
218 // Scroll with a constant speed.
219 this.eventHandler_.listen(this.scrollTimer_, goog.Timer.TICK, this.onTick_);
220 };
221
222
223 /**
224 * Handler for timer tick event, scrolls the container by one scroll step if
225 * needed.
226 * @param {goog.events.Event} event Timer tick event.
227 * @private
228 */
229 goog.fx.DragScrollSupport.prototype.onTick_ = function(event) {
230 this.containerNode_.scrollTop += this.scrollDelta_.y;
231 this.containerNode_.scrollLeft += this.scrollDelta_.x;
232 };
233
234
235 /**
236 * Handler for mouse moves events.
237 * @param {goog.events.Event} event Mouse move event.
238 */
239 goog.fx.DragScrollSupport.prototype.onMouseMove = function(event) {
240 var deltaX = this.horizontalScrolling_ ?
241 this.calculateScrollDelta(
242 event.clientX, this.scrollBounds_.left, this.scrollBounds_.width) :
243 0;
244 var deltaY = this.calculateScrollDelta(
245 event.clientY, this.scrollBounds_.top, this.scrollBounds_.height);
246 this.scrollDelta_.x = deltaX;
247 this.scrollDelta_.y = deltaY;
248
249 // If the scroll data is 0 or the event fired outside of the
250 // bounds of the container node.
251 if ((!deltaX && !deltaY) ||
252 (this.constrainScroll_ &&
253 !this.isInContainerBounds_(event.clientX, event.clientY))) {
254 this.scrollTimer_.stop();
255 } else if (!this.scrollTimer_.enabled) {
256 this.scrollTimer_.start();
257 }
258 };
259
260
261 /**
262 * Gets whether the input coordinate is in the container bounds.
263 * @param {number} x The x coordinate.
264 * @param {number} y The y coordinate.
265 * @return {boolean} Whether the input coordinate is in the container bounds.
266 * @private
267 */
268 goog.fx.DragScrollSupport.prototype.isInContainerBounds_ = function(x, y) {
269 var containerBounds = this.containerBounds_;
270 return containerBounds.left <= x &&
271 containerBounds.left + containerBounds.width >= x &&
272 containerBounds.top <= y &&
273 containerBounds.top + containerBounds.height >= y;
274 };
275
276
277 /**
278 * Calculates scroll delta.
279 *
280 * @param {number} coordinate Current mouse pointer coordinate.
281 * @param {number} min The coordinate value below which scrolling up should be
282 * started.
283 * @param {number} rangeLength The length of the range in which scrolling should
284 * be disabled and above which scrolling down should be started.
285 * @return {number} The calculated scroll delta.
286 * @protected
287 */
288 goog.fx.DragScrollSupport.prototype.calculateScrollDelta = function(
289 coordinate, min, rangeLength) {
290 var delta = 0;
291 if (coordinate < min) {
292 delta = -goog.fx.DragScrollSupport.SCROLL_STEP_;
293 } else if (coordinate > min + rangeLength) {
294 delta = goog.fx.DragScrollSupport.SCROLL_STEP_;
295 }
296 return delta;
297 };
298
299
300 /** @override */
301 goog.fx.DragScrollSupport.prototype.disposeInternal = function() {
302 goog.fx.DragScrollSupport.superClass_.disposeInternal.call(this);
303 this.eventHandler_.dispose();
304 this.scrollTimer_.dispose();
305 };