Debian Codegraph @

closure-library/closure/goog/graphics/abstractgraphics.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 and factory methods.
18 * @author [email protected] (Erik Arvidsson)
19 */
20
21
22 goog.provide('goog.graphics.AbstractGraphics');
23
24 goog.require('goog.dom');
25 goog.require('goog.graphics.AffineTransform');
26 goog.require('goog.graphics.Element');
27 goog.require('goog.graphics.EllipseElement');
28 goog.require('goog.graphics.Fill');
29 goog.require('goog.graphics.Font');
30 goog.require('goog.graphics.GroupElement');
31 goog.require('goog.graphics.Path');
32 goog.require('goog.graphics.PathElement');
33 goog.require('goog.graphics.RectElement');
34 goog.require('goog.graphics.Stroke');
35 goog.require('goog.graphics.StrokeAndFillElement');
36 goog.require('goog.graphics.TextElement');
37 goog.require('goog.math.Coordinate');
38 goog.require('goog.math.Size');
39 goog.require('goog.style');
40 goog.require('goog.ui.Component');
41
42
43
44 /**
45 * Base class for the different graphics. You should never construct objects
46 * of this class. Instead us goog.graphics.createGraphics
47 * @param {number|string} width The width in pixels or percent.
48 * @param {number|string} height The height in pixels or percent.
49 * @param {?number=} opt_coordWidth Optional coordinate system width - if
50 * omitted or null, defaults to same as width.
51 * @param {?number=} opt_coordHeight Optional coordinate system height - if
52 * omitted or null, defaults to same as height.
53 * @param {goog.dom.DomHelper=} opt_domHelper The DOM helper object for the
54 * document we want to render in.
55 * @constructor
56 * @extends {goog.ui.Component}
57 */
58 goog.graphics.AbstractGraphics = function(
59 width, height, opt_coordWidth, opt_coordHeight, opt_domHelper) {
60 goog.ui.Component.call(this, opt_domHelper);
61
62 /**
63 * Width of graphics in pixels or percentage points.
64 * @type {number|string}
65 * @protected
66 */
67 this.width = width;
68
69 /**
70 * Height of graphics in pixels or percentage points.
71 * @type {number|string}
72 * @protected
73 */
74 this.height = height;
75
76 /**
77 * Width of coordinate system in units.
78 * @type {?number}
79 * @protected
80 */
81 this.coordWidth = opt_coordWidth || null;
82
83 /**
84 * Height of coordinate system in units.
85 * @type {?number}
86 * @protected
87 */
88 this.coordHeight = opt_coordHeight || null;
89 };
90 goog.inherits(goog.graphics.AbstractGraphics, goog.ui.Component);
91
92
93 /**
94 * The root level group element.
95 * @type {goog.graphics.GroupElement?}
96 * @protected
97 */
98 goog.graphics.AbstractGraphics.prototype.canvasElement = null;
99
100
101 /**
102 * Left coordinate of the view box
103 * @type {number}
104 * @protected
105 */
106 goog.graphics.AbstractGraphics.prototype.coordLeft = 0;
107
108
109 /**
110 * Top coordinate of the view box
111 * @type {number}
112 * @protected
113 */
114 goog.graphics.AbstractGraphics.prototype.coordTop = 0;
115
116
117 /**
118 * @return {goog.graphics.GroupElement} The root level canvas element.
119 */
120 goog.graphics.AbstractGraphics.prototype.getCanvasElement = function() {
121 return this.canvasElement;
122 };
123
124
125 /**
126 * Changes the coordinate size.
127 * @param {number} coordWidth The coordinate width.
128 * @param {number} coordHeight The coordinate height.
129 */
130 goog.graphics.AbstractGraphics.prototype.setCoordSize = function(
131 coordWidth, coordHeight) {
132 this.coordWidth = coordWidth;
133 this.coordHeight = coordHeight;
134 };
135
136
137 /**
138 * @return {goog.math.Size} The coordinate size.
139 */
140 goog.graphics.AbstractGraphics.prototype.getCoordSize = function() {
141 if (this.coordWidth) {
142 return new goog.math.Size(
143 this.coordWidth,
144 /** @type {number} */ (this.coordHeight));
145 } else {
146 return this.getPixelSize();
147 }
148 };
149
150
151 /**
152 * Changes the coordinate system position.
153 * @param {number} left The coordinate system left bound.
154 * @param {number} top The coordinate system top bound.
155 */
156 goog.graphics.AbstractGraphics.prototype.setCoordOrigin = goog.abstractMethod;
157
158
159 /**
160 * @return {!goog.math.Coordinate} The coordinate system position.
161 */
162 goog.graphics.AbstractGraphics.prototype.getCoordOrigin = function() {
163 return new goog.math.Coordinate(this.coordLeft, this.coordTop);
164 };
165
166
167 /**
168 * Change the size of the canvas.
169 * @param {number} pixelWidth The width in pixels.
170 * @param {number} pixelHeight The height in pixels.
171 */
172 goog.graphics.AbstractGraphics.prototype.setSize = goog.abstractMethod;
173
174
175 /**
176 * @return {goog.math.Size} The size of canvas.
177 * @deprecated Use getPixelSize.
178 */
179 goog.graphics.AbstractGraphics.prototype.getSize = function() {
180 return this.getPixelSize();
181 };
182
183
184 /**
185 * @return {goog.math.Size?} Returns the number of pixels spanned by the
186 * surface, or null if the size could not be computed due to the size being
187 * specified in percentage points and the component not being in the
188 * document.
189 */
190 goog.graphics.AbstractGraphics.prototype.getPixelSize = function() {
191 if (this.isInDocument()) {
192 return goog.style.getSize(this.getElement());
193 }
194 if (goog.isNumber(this.width) && goog.isNumber(this.height)) {
195 return new goog.math.Size(this.width, this.height);
196 }
197 return null;
198 };
199
200
201 /**
202 * @return {number} Returns the number of pixels per unit in the x direction.
203 */
204 goog.graphics.AbstractGraphics.prototype.getPixelScaleX = function() {
205 var pixelSize = this.getPixelSize();
206 return pixelSize ? pixelSize.width / this.getCoordSize().width : 0;
207 };
208
209
210 /**
211 * @return {number} Returns the number of pixels per unit in the y direction.
212 */
213 goog.graphics.AbstractGraphics.prototype.getPixelScaleY = function() {
214 var pixelSize = this.getPixelSize();
215 return pixelSize ? pixelSize.height / this.getCoordSize().height : 0;
216 };
217
218
219 /**
220 * Remove all drawing elements from the graphics.
221 */
222 goog.graphics.AbstractGraphics.prototype.clear = goog.abstractMethod;
223
224
225 /**
226 * Remove a single drawing element from the surface. The default implementation
227 * assumes a DOM based drawing surface.
228 * @param {goog.graphics.Element} element The element to remove.
229 */
230 goog.graphics.AbstractGraphics.prototype.removeElement = function(element) {
231 goog.dom.removeNode(element.getElement());
232 };
233
234
235 /**
236 * Sets the fill for the given element.
237 * @param {goog.graphics.StrokeAndFillElement} element The element wrapper.
238 * @param {goog.graphics.Fill?} fill The fill object.
239 */
240 goog.graphics.AbstractGraphics.prototype.setElementFill = goog.abstractMethod;
241
242
243 /**
244 * Sets the stroke for the given element.
245 * @param {goog.graphics.StrokeAndFillElement} element The element wrapper.
246 * @param {goog.graphics.Stroke?} stroke The stroke object.
247 */
248 goog.graphics.AbstractGraphics.prototype.setElementStroke = goog.abstractMethod;
249
250
251 /**
252 * Set the transformation of an element.
253 *
254 * If a more general affine transform is needed than this provides
255 * (e.g. skew and scale) then use setElementAffineTransform.
256 * @param {goog.graphics.Element} element The element wrapper.
257 * @param {number} x The x coordinate of the translation transform.
258 * @param {number} y The y coordinate of the translation transform.
259 * @param {number} angle The angle of the rotation transform.
260 * @param {number} centerX The horizontal center of the rotation transform.
261 * @param {number} centerY The vertical center of the rotation transform.
262 */
263 goog.graphics.AbstractGraphics.prototype.setElementTransform =
264 goog.abstractMethod;
265
266
267 /**
268 * Set the affine transform of an element.
269 * @param {!goog.graphics.Element} element The element wrapper.
270 * @param {!goog.graphics.AffineTransform} affineTransform The
271 * transformation applied to this element.
272 */
273 goog.graphics.AbstractGraphics.prototype.setElementAffineTransform =
274 goog.abstractMethod;
275
276
277 /**
278 * Draw a circle
279 *
280 * @param {number} cx Center X coordinate.
281 * @param {number} cy Center Y coordinate.
282 * @param {number} r Radius length.
283 * @param {goog.graphics.Stroke?} stroke Stroke object describing the
284 * stroke.
285 * @param {goog.graphics.Fill?} fill Fill object describing the fill.
286 * @param {goog.graphics.GroupElement=} opt_group The group wrapper element to
287 * append to. If not specified, appends to the main canvas.
288 *
289 * @return {goog.graphics.EllipseElement} The newly created element.
290 */
291 goog.graphics.AbstractGraphics.prototype.drawCircle = function(
292 cx, cy, r, stroke, fill, opt_group) {
293 return this.drawEllipse(cx, cy, r, r, stroke, fill, opt_group);
294 };
295
296
297 /**
298 * Draw an ellipse
299 *
300 * @param {number} cx Center X coordinate.
301 * @param {number} cy Center Y coordinate.
302 * @param {number} rx Radius length for the x-axis.
303 * @param {number} ry Radius length for the y-axis.
304 * @param {goog.graphics.Stroke?} stroke Stroke object describing the
305 * stroke.
306 * @param {goog.graphics.Fill?} fill Fill object describing the fill.
307 * @param {goog.graphics.GroupElement=} opt_group The group wrapper element to
308 * append to. If not specified, appends to the main canvas.
309 *
310 * @return {goog.graphics.EllipseElement} The newly created element.
311 */
312 goog.graphics.AbstractGraphics.prototype.drawEllipse = goog.abstractMethod;
313
314
315 /**
316 * Draw a rectangle
317 *
318 * @param {number} x X coordinate (left).
319 * @param {number} y Y coordinate (top).
320 * @param {number} width Width of rectangle.
321 * @param {number} height Height of rectangle.
322 * @param {goog.graphics.Stroke?} stroke Stroke object describing the
323 * stroke.
324 * @param {goog.graphics.Fill?} fill Fill object describing the fill.
325 * @param {goog.graphics.GroupElement=} opt_group The group wrapper element to
326 * append to. If not specified, appends to the main canvas.
327 *
328 * @return {goog.graphics.RectElement} The newly created element.
329 */
330 goog.graphics.AbstractGraphics.prototype.drawRect = goog.abstractMethod;
331
332
333 /**
334 * Draw a text string within a rectangle (drawing is horizontal)
335 *
336 * @param {string} text The text to draw.
337 * @param {number} x X coordinate (left).
338 * @param {number} y Y coordinate (top).
339 * @param {number} width Width of rectangle.
340 * @param {number} height Height of rectangle.
341 * @param {string} align Horizontal alignment: left (default), center, right.
342 * @param {string} vAlign Vertical alignment: top (default), center, bottom.
343 * @param {goog.graphics.Font} font Font describing the font properties.
344 * @param {goog.graphics.Stroke?} stroke Stroke object describing the
345 * stroke.
346 * @param {goog.graphics.Fill?} fill Fill object describing the fill.
347 * @param {goog.graphics.GroupElement=} opt_group The group wrapper element to
348 * append to. If not specified, appends to the main canvas.
349 *
350 * @return {goog.graphics.TextElement} The newly created element.
351 */
352 goog.graphics.AbstractGraphics.prototype.drawText = function(
353 text, x, y, width, height, align, vAlign, font, stroke, fill, opt_group) {
354 var baseline = font.size / 2; // Baseline is middle of line
355 var textY;
356 if (vAlign == 'bottom') {
357 textY = y + height - baseline;
358 } else if (vAlign == 'center') {
359 textY = y + height / 2;
360 } else {
361 textY = y + baseline;
362 }
363
364 return this.drawTextOnLine(
365 text, x, textY, x + width, textY, align, font, stroke, fill, opt_group);
366 };
367
368
369 /**
370 * Draw a text string vertically centered on a given line.
371 *
372 * @param {string} text The text to draw.
373 * @param {number} x1 X coordinate of start of line.
374 * @param {number} y1 Y coordinate of start of line.
375 * @param {number} x2 X coordinate of end of line.
376 * @param {number} y2 Y coordinate of end of line.
377 * @param {string} align Horizontal alingnment: left (default), center, right.
378 * @param {goog.graphics.Font} font Font describing the font properties.
379 * @param {goog.graphics.Stroke?} stroke Stroke object describing the
380 * stroke.
381 * @param {goog.graphics.Fill?} fill Fill object describing the fill.
382 * @param {goog.graphics.GroupElement=} opt_group The group wrapper element to
383 * append to. If not specified, appends to the main canvas.
384 *
385 * @return {goog.graphics.TextElement} The newly created element.
386 */
387 goog.graphics.AbstractGraphics.prototype.drawTextOnLine = goog.abstractMethod;
388
389
390 /**
391 * Draw a path.
392 *
393 * @param {!goog.graphics.Path} path The path object to draw.
394 * @param {goog.graphics.Stroke?} stroke Stroke object describing the
395 * stroke.
396 * @param {goog.graphics.Fill?} fill Fill object describing the fill.
397 * @param {goog.graphics.GroupElement=} opt_group The group wrapper element to
398 * append to. If not specified, appends to the main canvas.
399 *
400 * @return {goog.graphics.PathElement} The newly created element.
401 */
402 goog.graphics.AbstractGraphics.prototype.drawPath = goog.abstractMethod;
403
404
405 /**
406 * Create an empty group of drawing elements.
407 *
408 * @param {goog.graphics.GroupElement=} opt_group The group wrapper element to
409 * append to. If not specified, appends to the main canvas.
410 *
411 * @return {goog.graphics.GroupElement} The newly created group.
412 */
413 goog.graphics.AbstractGraphics.prototype.createGroup = goog.abstractMethod;
414
415
416 /**
417 * Create an empty path.
418 *
419 * @return {!goog.graphics.Path} The path.
420 * @deprecated Use {@code new goog.graphics.Path()}.
421 */
422 goog.graphics.AbstractGraphics.prototype.createPath = function() {
423 return new goog.graphics.Path();
424 };
425
426
427 /**
428 * Measure and return the width (in pixels) of a given text string.
429 * Text measurement is needed to make sure a text can fit in the allocated
430 * area. The way text length is measured is by writing it into a div that is
431 * after the visible area, measure the div width, and immediately erase the
432 * written value.
433 *
434 * @param {string} text The text string to measure.
435 * @param {goog.graphics.Font} font The font object describing the font style.
436 *
437 * @return {number} The width in pixels of the text strings.
438 */
439 goog.graphics.AbstractGraphics.prototype.getTextWidth = goog.abstractMethod;
440
441
442 /**
443 * @return {boolean} Whether the underlying element can be cloned resulting in
444 * an accurate reproduction of the graphics contents.
445 */
446 goog.graphics.AbstractGraphics.prototype.isDomClonable = function() {
447 return false;
448 };
449
450
451 /**
452 * Start preventing redraws - useful for chaining large numbers of changes
453 * together. Not guaranteed to do anything - i.e. only use this for
454 * optimization of a single code path.
455 */
456 goog.graphics.AbstractGraphics.prototype.suspend = function() {};
457
458
459 /**
460 * Stop preventing redraws. If any redraws had been prevented, a redraw will
461 * be done now.
462 */
463 goog.graphics.AbstractGraphics.prototype.resume = function() {};