Debian Codegraph @

closure-library/closure/goog/math/rect.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 rectangles. Some of these
17 * functions should be migrated over to non-nullable params.
18 */
19
20 goog.provide('goog.math.Rect');
21
22 goog.require('goog.asserts');
23 goog.require('goog.math.Box');
24 goog.require('goog.math.Coordinate');
25 goog.require('goog.math.IRect');
26 goog.require('goog.math.Size');
27
28
29
30 /**
31 * Class for representing rectangular regions.
32 * @param {number} x Left.
33 * @param {number} y Top.
34 * @param {number} w Width.
35 * @param {number} h Height.
36 * @struct
37 * @constructor
38 * @implements {goog.math.IRect}
39 */
40 goog.math.Rect = function(x, y, w, h) {
41 /** @type {number} */
42 this.left = x;
43
44 /** @type {number} */
45 this.top = y;
46
47 /** @type {number} */
48 this.width = w;
49
50 /** @type {number} */
51 this.height = h;
52 };
53
54
55 /**
56 * @return {!goog.math.Rect} A new copy of this Rectangle.
57 */
58 goog.math.Rect.prototype.clone = function() {
59 return new goog.math.Rect(this.left, this.top, this.width, this.height);
60 };
61
62
63 /**
64 * Returns a new Box object with the same position and dimensions as this
65 * rectangle.
66 * @return {!goog.math.Box} A new Box representation of this Rectangle.
67 */
68 goog.math.Rect.prototype.toBox = function() {
69 var right = this.left + this.width;
70 var bottom = this.top + this.height;
71 return new goog.math.Box(this.top, right, bottom, this.left);
72 };
73
74
75 /**
76 * Creates a new Rect object with the position and size given.
77 * @param {!goog.math.Coordinate} position The top-left coordinate of the Rect
78 * @param {!goog.math.Size} size The size of the Rect
79 * @return {!goog.math.Rect} A new Rect initialized with the given position and
80 * size.
81 */
82 goog.math.Rect.createFromPositionAndSize = function(position, size) {
83 return new goog.math.Rect(position.x, position.y, size.width, size.height);
84 };
85
86
87 /**
88 * Creates a new Rect object with the same position and dimensions as a given
89 * Box. Note that this is only the inverse of toBox if left/top are defined.
90 * @param {goog.math.Box} box A box.
91 * @return {!goog.math.Rect} A new Rect initialized with the box's position
92 * and size.
93 */
94 goog.math.Rect.createFromBox = function(box) {
95 return new goog.math.Rect(
96 box.left, box.top, box.right - box.left, box.bottom - box.top);
97 };
98
99
100 if (goog.DEBUG) {
101 /**
102 * Returns a nice string representing size and dimensions of rectangle.
103 * @return {string} In the form (50, 73 - 75w x 25h).
104 * @override
105 */
106 goog.math.Rect.prototype.toString = function() {
107 return '(' + this.left + ', ' + this.top + ' - ' + this.width + 'w x ' +
108 this.height + 'h)';
109 };
110 }
111
112
113 /**
114 * Compares rectangles for equality.
115 * @param {goog.math.IRect} a A Rectangle.
116 * @param {goog.math.IRect} b A Rectangle.
117 * @return {boolean} True iff the rectangles have the same left, top, width,
118 * and height, or if both are null.
119 */
120 goog.math.Rect.equals = function(a, b) {
121 if (a == b) {
122 return true;
123 }
124 if (!a || !b) {
125 return false;
126 }
127 return a.left == b.left && a.width == b.width && a.top == b.top &&
128 a.height == b.height;
129 };
130
131
132 /**
133 * Computes the intersection of this rectangle and the rectangle parameter. If
134 * there is no intersection, returns false and leaves this rectangle as is.
135 * @param {goog.math.IRect} rect A Rectangle.
136 * @return {boolean} True iff this rectangle intersects with the parameter.
137 */
138 goog.math.Rect.prototype.intersection = function(rect) {
139 var x0 = Math.max(this.left, rect.left);
140 var x1 = Math.min(this.left + this.width, rect.left + rect.width);
141
142 if (x0 <= x1) {
143 var y0 = Math.max(this.top, rect.top);
144 var y1 = Math.min(this.top + this.height, rect.top + rect.height);
145
146 if (y0 <= y1) {
147 this.left = x0;
148 this.top = y0;
149 this.width = x1 - x0;
150 this.height = y1 - y0;
151
152 return true;
153 }
154 }
155 return false;
156 };
157
158
159 /**
160 * Returns the intersection of two rectangles. Two rectangles intersect if they
161 * touch at all, for example, two zero width and height rectangles would
162 * intersect if they had the same top and left.
163 * @param {goog.math.IRect} a A Rectangle.
164 * @param {goog.math.IRect} b A Rectangle.
165 * @return {goog.math.Rect} A new intersection rect (even if width and height
166 * are 0), or null if there is no intersection.
167 */
168 goog.math.Rect.intersection = function(a, b) {
169 // There is no nice way to do intersection via a clone, because any such
170 // clone might be unnecessary if this function returns null. So, we duplicate
171 // code from above.
172
173 var x0 = Math.max(a.left, b.left);
174 var x1 = Math.min(a.left + a.width, b.left + b.width);
175
176 if (x0 <= x1) {
177 var y0 = Math.max(a.top, b.top);
178 var y1 = Math.min(a.top + a.height, b.top + b.height);
179
180 if (y0 <= y1) {
181 return new goog.math.Rect(x0, y0, x1 - x0, y1 - y0);
182 }
183 }
184 return null;
185 };
186
187
188 /**
189 * Returns whether two rectangles intersect. Two rectangles intersect if they
190 * touch at all, for example, two zero width and height rectangles would
191 * intersect if they had the same top and left.
192 * @param {goog.math.IRect} a A Rectangle.
193 * @param {goog.math.IRect} b A Rectangle.
194 * @return {boolean} Whether a and b intersect.
195 */
196 goog.math.Rect.intersects = function(a, b) {
197 return (
198 a.left <= b.left + b.width && b.left <= a.left + a.width &&
199 a.top <= b.top + b.height && b.top <= a.top + a.height);
200 };
201
202
203 /**
204 * Returns whether a rectangle intersects this rectangle.
205 * @param {goog.math.IRect} rect A rectangle.
206 * @return {boolean} Whether rect intersects this rectangle.
207 */
208 goog.math.Rect.prototype.intersects = function(rect) {
209 return goog.math.Rect.intersects(this, rect);
210 };
211
212
213 /**
214 * Computes the difference regions between two rectangles. The return value is
215 * an array of 0 to 4 rectangles defining the remaining regions of the first
216 * rectangle after the second has been subtracted.
217 * @param {goog.math.Rect} a A Rectangle.
218 * @param {goog.math.IRect} b A Rectangle.
219 * @return {!Array<!goog.math.Rect>} An array with 0 to 4 rectangles which
220 * together define the difference area of rectangle a minus rectangle b.
221 */
222 goog.math.Rect.difference = function(a, b) {
223 var intersection = goog.math.Rect.intersection(a, b);
224 if (!intersection || !intersection.height || !intersection.width) {
225 return [a.clone()];
226 }
227
228 var result = [];
229
230 var top = a.top;
231 var height = a.height;
232
233 var ar = a.left + a.width;
234 var ab = a.top + a.height;
235
236 var br = b.left + b.width;
237 var bb = b.top + b.height;
238
239 // Subtract off any area on top where A extends past B
240 if (b.top > a.top) {
241 result.push(new goog.math.Rect(a.left, a.top, a.width, b.top - a.top));
242 top = b.top;
243 // If we're moving the top down, we also need to subtract the height diff.
244 height -= b.top - a.top;
245 }
246 // Subtract off any area on bottom where A extends past B
247 if (bb < ab) {
248 result.push(new goog.math.Rect(a.left, bb, a.width, ab - bb));
249 height = bb - top;
250 }
251 // Subtract any area on left where A extends past B
252 if (b.left > a.left) {
253 result.push(new goog.math.Rect(a.left, top, b.left - a.left, height));
254 }
255 // Subtract any area on right where A extends past B
256 if (br < ar) {
257 result.push(new goog.math.Rect(br, top, ar - br, height));
258 }
259
260 return result;
261 };
262
263
264 /**
265 * Computes the difference regions between this rectangle and {@code rect}. The
266 * return value is an array of 0 to 4 rectangles defining the remaining regions
267 * of this rectangle after the other has been subtracted.
268 * @param {goog.math.IRect} rect A Rectangle.
269 * @return {!Array<!goog.math.Rect>} An array with 0 to 4 rectangles which
270 * together define the difference area of rectangle a minus rectangle b.
271 */
272 goog.math.Rect.prototype.difference = function(rect) {
273 return goog.math.Rect.difference(this, rect);
274 };
275
276
277 /**
278 * Expand this rectangle to also include the area of the given rectangle.
279 * @param {goog.math.IRect} rect The other rectangle.
280 */
281 goog.math.Rect.prototype.boundingRect = function(rect) {
282 // We compute right and bottom before we change left and top below.
283 var right = Math.max(this.left + this.width, rect.left + rect.width);
284 var bottom = Math.max(this.top + this.height, rect.top + rect.height);
285
286 this.left = Math.min(this.left, rect.left);
287 this.top = Math.min(this.top, rect.top);
288
289 this.width = right - this.left;
290 this.height = bottom - this.top;
291 };
292
293
294 /**
295 * Returns a new rectangle which completely contains both input rectangles.
296 * @param {goog.math.IRect} a A rectangle.
297 * @param {goog.math.IRect} b A rectangle.
298 * @return {goog.math.Rect} A new bounding rect, or null if either rect is
299 * null.
300 */
301 goog.math.Rect.boundingRect = function(a, b) {
302 if (!a || !b) {
303 return null;
304 }
305
306 var newRect = new goog.math.Rect(a.left, a.top, a.width, a.height);
307 newRect.boundingRect(b);
308
309 return newRect;
310 };
311
312
313 /**
314 * Tests whether this rectangle entirely contains another rectangle or
315 * coordinate.
316 *
317 * @param {goog.math.IRect|goog.math.Coordinate} another The rectangle or
318 * coordinate to test for containment.
319 * @return {boolean} Whether this rectangle contains given rectangle or
320 * coordinate.
321 */
322 goog.math.Rect.prototype.contains = function(another) {
323 if (another instanceof goog.math.Coordinate) {
324 return another.x >= this.left && another.x <= this.left + this.width &&
325 another.y >= this.top && another.y <= this.top + this.height;
326 } else { // (another instanceof goog.math.IRect)
327 return this.left <= another.left &&
328 this.left + this.width >= another.left + another.width &&
329 this.top <= another.top &&
330 this.top + this.height >= another.top + another.height;
331 }
332 };
333
334
335 /**
336 * @param {!goog.math.Coordinate} point A coordinate.
337 * @return {number} The squared distance between the point and the closest
338 * point inside the rectangle. Returns 0 if the point is inside the
339 * rectangle.
340 */
341 goog.math.Rect.prototype.squaredDistance = function(point) {
342 var dx = point.x < this.left ?
343 this.left - point.x :
344 Math.max(point.x - (this.left + this.width), 0);
345 var dy = point.y < this.top ? this.top - point.y :
346 Math.max(point.y - (this.top + this.height), 0);
347 return dx * dx + dy * dy;
348 };
349
350
351 /**
352 * @param {!goog.math.Coordinate} point A coordinate.
353 * @return {number} The distance between the point and the closest point
354 * inside the rectangle. Returns 0 if the point is inside the rectangle.
355 */
356 goog.math.Rect.prototype.distance = function(point) {
357 return Math.sqrt(this.squaredDistance(point));
358 };
359
360
361 /**
362 * @return {!goog.math.Size} The size of this rectangle.
363 */
364 goog.math.Rect.prototype.getSize = function() {
365 return new goog.math.Size(this.width, this.height);
366 };
367
368
369 /**
370 * @return {!goog.math.Coordinate} A new coordinate for the top-left corner of
371 * the rectangle.
372 */
373 goog.math.Rect.prototype.getTopLeft = function() {
374 return new goog.math.Coordinate(this.left, this.top);
375 };
376
377
378 /**
379 * @return {!goog.math.Coordinate} A new coordinate for the center of the
380 * rectangle.
381 */
382 goog.math.Rect.prototype.getCenter = function() {
383 return new goog.math.Coordinate(
384 this.left + this.width / 2, this.top + this.height / 2);
385 };
386
387
388 /**
389 * @return {!goog.math.Coordinate} A new coordinate for the bottom-right corner
390 * of the rectangle.
391 */
392 goog.math.Rect.prototype.getBottomRight = function() {
393 return new goog.math.Coordinate(
394 this.left + this.width, this.top + this.height);
395 };
396
397
398 /**
399 * Rounds the fields to the next larger integer values.
400 * @return {!goog.math.Rect} This rectangle with ceil'd fields.
401 */
402 goog.math.Rect.prototype.ceil = function() {
403 this.left = Math.ceil(this.left);
404 this.top = Math.ceil(this.top);
405 this.width = Math.ceil(this.width);
406 this.height = Math.ceil(this.height);
407 return this;
408 };
409
410
411 /**
412 * Rounds the fields to the next smaller integer values.
413 * @return {!goog.math.Rect} This rectangle with floored fields.
414 */
415 goog.math.Rect.prototype.floor = function() {
416 this.left = Math.floor(this.left);
417 this.top = Math.floor(this.top);
418 this.width = Math.floor(this.width);
419 this.height = Math.floor(this.height);
420 return this;
421 };
422
423
424 /**
425 * Rounds the fields to nearest integer values.
426 * @return {!goog.math.Rect} This rectangle with rounded fields.
427 */
428 goog.math.Rect.prototype.round = function() {
429 this.left = Math.round(this.left);
430 this.top = Math.round(this.top);
431 this.width = Math.round(this.width);
432 this.height = Math.round(this.height);
433 return this;
434 };
435
436
437 /**
438 * Translates this rectangle by the given offsets. If a
439 * {@code goog.math.Coordinate} is given, then the left and top values are
440 * translated by the coordinate's x and y values. Otherwise, top and left are
441 * translated by {@code tx} and {@code opt_ty} respectively.
442 * @param {number|goog.math.Coordinate} tx The value to translate left by or the
443 * the coordinate to translate this rect by.
444 * @param {number=} opt_ty The value to translate top by.
445 * @return {!goog.math.Rect} This rectangle after translating.
446 */
447 goog.math.Rect.prototype.translate = function(tx, opt_ty) {
448 if (tx instanceof goog.math.Coordinate) {
449 this.left += tx.x;
450 this.top += tx.y;
451 } else {
452 this.left += goog.asserts.assertNumber(tx);
453 if (goog.isNumber(opt_ty)) {
454 this.top += opt_ty;
455 }
456 }
457 return this;
458 };
459
460
461 /**
462 * Scales this rectangle by the given scale factors. The left and width values
463 * are scaled by {@code sx} and the top and height values are scaled by
464 * {@code opt_sy}. If {@code opt_sy} is not given, then all fields are scaled
465 * by {@code sx}.
466 * @param {number} sx The scale factor to use for the x dimension.
467 * @param {number=} opt_sy The scale factor to use for the y dimension.
468 * @return {!goog.math.Rect} This rectangle after scaling.
469 */
470 goog.math.Rect.prototype.scale = function(sx, opt_sy) {
471 var sy = goog.isNumber(opt_sy) ? opt_sy : sx;
472 this.left *= sx;
473 this.width *= sx;
474 this.top *= sy;
475 this.height *= sy;
476 return this;
477 };