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
};
160

161