lib/goog/math/box.js

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