# 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 |
20 | goog.provide('goog.math.Box');
21 |
22 | goog.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 | */
40 | goog.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 | */
73 | goog.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 | */
86 | goog.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 | */
94 | goog.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 | */
103 | goog.math.Box.prototype.clone = function() {
104 | return new goog.math.Box(this.top, this.right, this.bottom, this.left);
105 | };
106 |
107 |
108 | if (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 | */
127 | goog.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 | */
141 | goog.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 | */
166 | goog.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 | */
179 | goog.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 | */
193 | goog.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 | */
212 | goog.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 | */
237 | goog.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 | */
256 | goog.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 | */
276 | goog.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 | */
290 | goog.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 | */
304 | goog.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 | */
315 | goog.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 | */
329 | goog.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 | */
343 | goog.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 | */
364 | goog.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 | */
391 | goog.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 | };