Debian Codegraph @

closure-library/closure/goog/graphics/ext/coordinates.js

raw
1 // Copyright 2007 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 /**
17 * @fileoverview Graphics utility functions for advanced coordinates.
18 *
19 * This file assists the use of advanced coordinates in goog.graphics. Coords
20 * can be specified as simple numbers which will correspond to units in the
21 * graphics element's coordinate space. Alternately, coords can be expressed
22 * in pixels, meaning no matter what tranformations or coordinate system changes
23 * are present, the number of pixel changes will remain constant. Coords can
24 * also be expressed as percentages of their parent's size.
25 *
26 * This file also allows for elements to have margins, expressable in any of
27 * the ways described above.
28 *
29 * Additional pieces of advanced coordinate functionality can (soon) be found in
30 * element.js and groupelement.js.
31 *
32 * @author [email protected] (Robby Walker)
33 */
34
35 goog.provide('goog.graphics.ext.coordinates');
36
37 goog.require('goog.string');
38
39
40 /**
41 * Cache of boolean values. For a given string (key), is it special? (value)
42 * @type {Object}
43 * @private
44 */
45 goog.graphics.ext.coordinates.specialCoordinateCache_ = {};
46
47
48 /**
49 * Determines if the given coordinate is a percent based coordinate or an
50 * expression with a percent based component.
51 * @param {string} coord The coordinate to test.
52 * @return {boolean} Whether the coordinate contains the string '%'.
53 * @private
54 */
55 goog.graphics.ext.coordinates.isPercent_ = function(coord) {
56 return goog.string.contains(coord, '%');
57 };
58
59
60 /**
61 * Determines if the given coordinate is a pixel based coordinate or an
62 * expression with a pixel based component.
63 * @param {string} coord The coordinate to test.
64 * @return {boolean} Whether the coordinate contains the string 'px'.
65 * @private
66 */
67 goog.graphics.ext.coordinates.isPixels_ = function(coord) {
68 return goog.string.contains(coord, 'px');
69 };
70
71
72 /**
73 * Determines if the given coordinate is special - i.e. not just a number.
74 * @param {string|number|null} coord The coordinate to test.
75 * @return {boolean} Whether the coordinate is special.
76 */
77 goog.graphics.ext.coordinates.isSpecial = function(coord) {
78 var cache = goog.graphics.ext.coordinates.specialCoordinateCache_;
79
80 if (!(coord in cache)) {
81 cache[coord] = goog.isString(coord) &&
82 (goog.graphics.ext.coordinates.isPercent_(coord) ||
83 goog.graphics.ext.coordinates.isPixels_(coord));
84 }
85
86 return cache[coord];
87 };
88
89
90 /**
91 * Returns the value of the given expression in the given context.
92 *
93 * Should be treated as package scope.
94 *
95 * @param {string|number} coord The coordinate to convert.
96 * @param {number} size The size of the parent element.
97 * @param {number} scale The ratio of pixels to units.
98 * @return {number} The number of coordinate space units that corresponds to
99 * this coordinate.
100 */
101 goog.graphics.ext.coordinates.computeValue = function(coord, size, scale) {
102 var number = parseFloat(String(coord));
103 if (goog.isString(coord)) {
104 if (goog.graphics.ext.coordinates.isPercent_(coord)) {
105 return number * size / 100;
106 } else if (goog.graphics.ext.coordinates.isPixels_(coord)) {
107 return number / scale;
108 }
109 }
110
111 return number;
112 };
113
114
115 /**
116 * Converts the given coordinate to a number value in units.
117 *
118 * Should be treated as package scope.
119 *
120 * @param {string|number} coord The coordinate to retrieve the value for.
121 * @param {boolean|undefined} forMaximum Whether we are computing the largest
122 * value this coordinate would be in a parent of no size. The container
123 * size in this case should be set to the size of the current element.
124 * @param {number} containerSize The unit value of the size of the container of
125 * this element. Should be set to the minimum width of this element if
126 * forMaximum is true.
127 * @param {number} scale The ratio of pixels to units.
128 * @param {Object=} opt_cache Optional (but highly recommend) object to store
129 * cached computations in. The calling class should manage clearing out
130 * the cache when the scale or containerSize changes.
131 * @return {number} The correct number of coordinate space units.
132 */
133 goog.graphics.ext.coordinates.getValue = function(
134 coord, forMaximum, containerSize, scale, opt_cache) {
135 if (!goog.isNumber(coord)) {
136 var cacheString = opt_cache && ((forMaximum ? 'X' : '') + coord);
137
138 if (opt_cache && cacheString in opt_cache) {
139 coord = opt_cache[cacheString];
140 } else {
141 if (goog.graphics.ext.coordinates.isSpecial(
142 /** @type {string} */ (coord))) {
143 coord = goog.graphics.ext.coordinates.computeValue(
144 coord, containerSize, scale);
145 } else {
146 // Simple coordinates just need to be converted from a string to a
147 // number.
148 coord = parseFloat(/** @type {string} */ (coord));
149 }
150
151 // Cache the result.
152 if (opt_cache) {
153 opt_cache[cacheString] = coord;
154 }
155 }
156 }
157
158 return coord;
159 };