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() {};
464

465