Debian Codegraph @

closure-library/closure/goog/math/box.js

raw
1 // Copyright 2006 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 A utility class for representing a numeric box.
17 */
18
19
20 goog.provide('goog.math.Box');
21
22 goog.require('goog.asserts');
23 goog.require('goog.math.Coordinate');
24
25
26
27 /**
28 * Class for representing a box. A box is specified as a top, right, bottom,
29 * and left. A box is useful for representing margins and padding.
30 *
31 * This class assumes 'screen coordinates': larger Y coordinates are further
32 * from the top of the screen.
33 *
34 * @param {number} top Top.
35 * @param {number} right Right.
36 * @param {number} bottom Bottom.
37 * @param {number} left Left.
38 * @struct
39 * @constructor
40 */
41 goog.math.Box = function(top, right, bottom, left) {
42 /**
43 * Top
44 * @type {number}
45 */
46 this.top = top;
47
48 /**
49 * Right
50 * @type {number}
51 */
52 this.right = right;
53
54 /**
55 * Bottom
56 * @type {number}
57 */
58 this.bottom = bottom;
59
60 /**
61 * Left
62 * @type {number}
63 */
64 this.left = left;
65 };
66
67
68 /**
69 * Creates a Box by bounding a collection of goog.math.Coordinate objects
70 * @param {...goog.math.Coordinate} var_args Coordinates to be included inside
71 * the box.
72 * @return {!goog.math.Box} A Box containing all the specified Coordinates.
73 */
74 goog.math.Box.boundingBox = function(var_args) {
75 var box = new goog.math.Box(
76 arguments[0].y, arguments[0].x, arguments[0].y, arguments[0].x);
77 for (var i = 1; i < arguments.length; i++) {
78 box.expandToIncludeCoordinate(arguments[i]);
79 }
80 return box;
81 };
82
83
84 /**
85 * @return {number} width The width of this Box.
86 */
87 goog.math.Box.prototype.getWidth = function() {
88 return this.right - this.left;
89 };
90
91
92 /**
93 * @return {number} height The height of this Box.
94 */
95 goog.math.Box.prototype.getHeight = function() {
96 return this.bottom - this.top;
97 };
98
99
100 /**
101 * Creates a copy of the box with the same dimensions.
102 * @return {!goog.math.Box} A clone of this Box.
103 */
104 goog.math.Box.prototype.clone = function() {
105 return new goog.math.Box(this.top, this.right, this.bottom, this.left);
106 };
107
108
109 if (goog.DEBUG) {
110 /**
111 * Returns a nice string representing the box.
112 * @return {string} In the form (50t, 73r, 24b, 13l).
113 * @override
114 */
115 goog.math.Box.prototype.toString = function() {
116 return '(' + this.top + 't, ' + this.right + 'r, ' + this.bottom + 'b, ' +
117 this.left + 'l)';
118 };
119 }
120
121
122 /**
123 * Returns whether the box contains a coordinate or another box.
124 *
125 * @param {goog.math.Coordinate|goog.math.Box} other A Coordinate or a Box.
126 * @return {boolean} Whether the box contains the coordinate or other box.
127 */
128 goog.math.Box.prototype.contains = function(other) {
129 return goog.math.Box.contains(this, other);
130 };
131
132
133 /**
134 * Expands box with the given margins.
135 *
136 * @param {number|goog.math.Box} top Top margin or box with all margins.
137 * @param {number=} opt_right Right margin.
138 * @param {number=} opt_bottom Bottom margin.
139 * @param {number=} opt_left Left margin.
140 * @return {!goog.math.Box} A reference to this Box.
141 */
142 goog.math.Box.prototype.expand = function(
143 top, opt_right, opt_bottom, opt_left) {
144 if (goog.isObject(top)) {
145 this.top -= top.top;
146 this.right += top.right;
147 this.bottom += top.bottom;
148 this.left -= top.left;
149 } else {
150 this.top -= /** @type {number} */ (top);
151 this.right += Number(opt_right);
152 this.bottom += Number(opt_bottom);
153 this.left -= Number(opt_left);
154 }
155
156 return this;
157 };
158
159
160 /**
161 * Expand this box to include another box.
162 * NOTE(user): This is used in code that needs to be very fast, please don't
163 * add functionality to this function at the expense of speed (variable
164 * arguments, accepting multiple argument types, etc).
165 * @param {goog.math.Box} box The box to include in this one.
166 */
167 goog.math.Box.prototype.expandToInclude = function(box) {
168 this.left = Math.min(this.left, box.left);
169 this.top = Math.min(this.top, box.top);
170 this.right = Math.max(this.right, box.right);
171 this.bottom = Math.max(this.bottom, box.bottom);
172 };
173
174
175 /**
176 * Expand this box to include the coordinate.
177 * @param {!goog.math.Coordinate} coord The coordinate to be included
178 * inside the box.
179 */
180 goog.math.Box.prototype.expandToIncludeCoordinate = function(coord) {
181 this.top = Math.min(this.top, coord.y);
182 this.right = Math.max(this.right, coord.x);
183 this.bottom = Math.max(this.bottom, coord.y);
184 this.left = Math.min(this.left, coord.x);
185 };
186
187
188 /**
189 * Compares boxes for equality.
190 * @param {goog.math.Box} a A Box.
191 * @param {goog.math.Box} b A Box.
192 * @return {boolean} True iff the boxes are equal, or if both are null.
193 */
194 goog.math.Box.equals = function(a, b) {
195 if (a == b) {
196 return true;
197 }
198 if (!a || !b) {
199 return false;
200 }
201 return a.top == b.top && a.right == b.right && a.bottom == b.bottom &&
202 a.left == b.left;
203 };
204
205
206 /**
207 * Returns whether a box contains a coordinate or another box.
208 *
209 * @param {goog.math.Box} box A Box.
210 * @param {goog.math.Coordinate|goog.math.Box} other A Coordinate or a Box.
211 * @return {boolean} Whether the box contains the coordinate or other box.
212 */
213 goog.math.Box.contains = function(box, other) {
214 if (!box || !other) {
215 return false;
216 }
217
218 if (other instanceof goog.math.Box) {
219 return other.left >= box.left && other.right <= box.right &&
220 other.top >= box.top && other.bottom <= box.bottom;
221 }
222
223 // other is a Coordinate.
224 return other.x >= box.left && other.x <= box.right && other.y >= box.top &&
225 other.y <= box.bottom;
226 };
227
228
229 /**
230 * Returns the relative x position of a coordinate compared to a box. Returns
231 * zero if the coordinate is inside the box.
232 *
233 * @param {goog.math.Box} box A Box.
234 * @param {goog.math.Coordinate} coord A Coordinate.
235 * @return {number} The x position of {@code coord} relative to the nearest
236 * side of {@code box}, or zero if {@code coord} is inside {@code box}.
237 */
238 goog.math.Box.relativePositionX = function(box, coord) {
239 if (coord.x < box.left) {
240 return coord.x - box.left;
241 } else if (coord.x > box.right) {
242 return coord.x - box.right;
243 }
244 return 0;
245 };
246
247
248 /**
249 * Returns the relative y position of a coordinate compared to a box. Returns
250 * zero if the coordinate is inside the box.
251 *
252 * @param {goog.math.Box} box A Box.
253 * @param {goog.math.Coordinate} coord A Coordinate.
254 * @return {number} The y position of {@code coord} relative to the nearest
255 * side of {@code box}, or zero if {@code coord} is inside {@code box}.
256 */
257 goog.math.Box.relativePositionY = function(box, coord) {
258 if (coord.y < box.top) {
259 return coord.y - box.top;
260 } else if (coord.y > box.bottom) {
261 return coord.y - box.bottom;
262 }
263 return 0;
264 };
265
266
267 /**
268 * Returns the distance between a coordinate and the nearest corner/side of a
269 * box. Returns zero if the coordinate is inside the box.
270 *
271 * @param {goog.math.Box} box A Box.
272 * @param {goog.math.Coordinate} coord A Coordinate.
273 * @return {number} The distance between {@code coord} and the nearest
274 * corner/side of {@code box}, or zero if {@code coord} is inside
275 * {@code box}.
276 */
277 goog.math.Box.distance = function(box, coord) {
278 var x = goog.math.Box.relativePositionX(box, coord);
279 var y = goog.math.Box.relativePositionY(box, coord);
280 return Math.sqrt(x * x + y * y);
281 };
282
283
284 /**
285 * Returns whether two boxes intersect.
286 *
287 * @param {goog.math.Box} a A Box.
288 * @param {goog.math.Box} b A second Box.
289 * @return {boolean} Whether the boxes intersect.
290 */
291 goog.math.Box.intersects = function(a, b) {
292 return (
293 a.left <= b.right && b.left <= a.right && a.top <= b.bottom &&
294 b.top <= a.bottom);
295 };
296
297
298 /**
299 * Returns whether two boxes would intersect with additional padding.
300 *
301 * @param {goog.math.Box} a A Box.
302 * @param {goog.math.Box} b A second Box.
303 * @param {number} padding The additional padding.
304 * @return {boolean} Whether the boxes intersect.
305 */
306 goog.math.Box.intersectsWithPadding = function(a, b, padding) {
307 return (
308 a.left <= b.right + padding && b.left <= a.right + padding &&
309 a.top <= b.bottom + padding && b.top <= a.bottom + padding);
310 };
311
312
313 /**
314 * Rounds the fields to the next larger integer values.
315 *
316 * @return {!goog.math.Box} This box with ceil'd fields.
317 */
318 goog.math.Box.prototype.ceil = function() {
319 this.top = Math.ceil(this.top);
320 this.right = Math.ceil(this.right);
321 this.bottom = Math.ceil(this.bottom);
322 this.left = Math.ceil(this.left);
323 return this;
324 };
325
326
327 /**
328 * Rounds the fields to the next smaller integer values.
329 *
330 * @return {!goog.math.Box} This box with floored fields.
331 */
332 goog.math.Box.prototype.floor = function() {
333 this.top = Math.floor(this.top);
334 this.right = Math.floor(this.right);
335 this.bottom = Math.floor(this.bottom);
336 this.left = Math.floor(this.left);
337 return this;
338 };
339
340
341 /**
342 * Rounds the fields to nearest integer values.
343 *
344 * @return {!goog.math.Box} This box with rounded fields.
345 */
346 goog.math.Box.prototype.round = function() {
347 this.top = Math.round(this.top);
348 this.right = Math.round(this.right);
349 this.bottom = Math.round(this.bottom);
350 this.left = Math.round(this.left);
351 return this;
352 };
353
354
355 /**
356 * Translates this box by the given offsets. If a {@code goog.math.Coordinate}
357 * is given, then the left and right values are translated by the coordinate's
358 * x value and the top and bottom values are translated by the coordinate's y
359 * value. Otherwise, {@code tx} and {@code opt_ty} are used to translate the x
360 * and y dimension values.
361 *
362 * @param {number|goog.math.Coordinate} tx The value to translate the x
363 * dimension values by or the the coordinate to translate this box by.
364 * @param {number=} opt_ty The value to translate y dimension values by.
365 * @return {!goog.math.Box} This box after translating.
366 */
367 goog.math.Box.prototype.translate = function(tx, opt_ty) {
368 if (tx instanceof goog.math.Coordinate) {
369 this.left += tx.x;
370 this.right += tx.x;
371 this.top += tx.y;
372 this.bottom += tx.y;
373 } else {
374 goog.asserts.assertNumber(tx);
375 this.left += tx;
376 this.right += tx;
377 if (goog.isNumber(opt_ty)) {
378 this.top += opt_ty;
379 this.bottom += opt_ty;
380 }
381 }
382 return this;
383 };
384
385
386 /**
387 * Scales this coordinate by the given scale factors. The x and y dimension
388 * values are scaled by {@code sx} and {@code opt_sy} respectively.
389 * If {@code opt_sy} is not given, then {@code sx} is used for both x and y.
390 *
391 * @param {number} sx The scale factor to use for the x dimension.
392 * @param {number=} opt_sy The scale factor to use for the y dimension.
393 * @return {!goog.math.Box} This box after scaling.
394 */
395 goog.math.Box.prototype.scale = function(sx, opt_sy) {
396 var sy = goog.isNumber(opt_sy) ? opt_sy : sx;
397 this.left *= sx;
398 this.right *= sx;
399 this.top *= sy;
400 this.bottom *= sy;
401 return this;
402 };