Debian Codegraph @

closure-library/closure/goog/ui/gauge.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 Gauge UI component, using browser vector graphics.
18 * @see ../demos/gauge.html
19 */
20
21
22 goog.provide('goog.ui.Gauge');
23 goog.provide('goog.ui.GaugeColoredRange');
24
25
26 goog.require('goog.a11y.aria');
27 goog.require('goog.asserts');
28 goog.require('goog.dom.TagName');
29 goog.require('goog.events');
30 goog.require('goog.fx.Animation');
31 goog.require('goog.fx.Transition');
32 goog.require('goog.fx.easing');
33 goog.require('goog.graphics');
34 goog.require('goog.graphics.Font');
35 goog.require('goog.graphics.Path');
36 goog.require('goog.graphics.SolidFill');
37 goog.require('goog.math');
38 goog.require('goog.ui.Component');
39 goog.require('goog.ui.GaugeTheme');
40
41
42
43 /**
44 * Information on how to decorate a range in the gauge.
45 * This is an internal-only class.
46 * @param {number} fromValue The range start (minimal) value.
47 * @param {number} toValue The range end (maximal) value.
48 * @param {string} backgroundColor Color to fill the range background with.
49 * @constructor
50 * @final
51 */
52 goog.ui.GaugeColoredRange = function(fromValue, toValue, backgroundColor) {
53
54 /**
55 * The range start (minimal) value.
56 * @type {number}
57 */
58 this.fromValue = fromValue;
59
60
61 /**
62 * The range end (maximal) value.
63 * @type {number}
64 */
65 this.toValue = toValue;
66
67
68 /**
69 * Color to fill the range background with.
70 * @type {string}
71 */
72 this.backgroundColor = backgroundColor;
73 };
74
75
76
77 /**
78 * A UI component that displays a gauge.
79 * A gauge displayes a current value within a round axis that represents a
80 * given range.
81 * The gauge is built from an external border, and internal border inside it,
82 * ticks and labels inside the internal border, and a needle that points to
83 * the current value.
84 * @param {number} width The width in pixels.
85 * @param {number} height The height in pixels.
86 * @param {goog.dom.DomHelper=} opt_domHelper The DOM helper object for the
87 * document we want to render in.
88 * @constructor
89 * @extends {goog.ui.Component}
90 * @final
91 */
92 goog.ui.Gauge = function(width, height, opt_domHelper) {
93 goog.ui.Component.call(this, opt_domHelper);
94
95 /**
96 * The width in pixels of this component.
97 * @type {number}
98 * @private
99 */
100 this.width_ = width;
101
102
103 /**
104 * The height in pixels of this component.
105 * @type {number}
106 * @private
107 */
108 this.height_ = height;
109
110
111 /**
112 * The underlying graphics.
113 * @type {goog.graphics.AbstractGraphics}
114 * @private
115 */
116 this.graphics_ =
117 goog.graphics.createGraphics(width, height, null, null, opt_domHelper);
118
119
120 /**
121 * Colors to paint the background of certain ranges (optional).
122 * @type {Array<goog.ui.GaugeColoredRange>}
123 * @private
124 */
125 this.rangeColors_ = [];
126 };
127 goog.inherits(goog.ui.Gauge, goog.ui.Component);
128
129
130 /**
131 * Constant for a background color for a gauge area.
132 */
133 goog.ui.Gauge.RED = '#ffc0c0';
134
135
136 /**
137 * Constant for a background color for a gauge area.
138 */
139 goog.ui.Gauge.GREEN = '#c0ffc0';
140
141
142 /**
143 * Constant for a background color for a gauge area.
144 */
145 goog.ui.Gauge.YELLOW = '#ffffa0';
146
147
148 /**
149 * The radius of the entire gauge from the canvas size.
150 * @type {number}
151 */
152 goog.ui.Gauge.FACTOR_RADIUS_FROM_SIZE = 0.45;
153
154
155 /**
156 * The ratio of internal gauge radius from entire radius.
157 * The remaining area is the border around the gauge.
158 * @type {number}
159 */
160 goog.ui.Gauge.FACTOR_MAIN_AREA = 0.9;
161
162
163 /**
164 * The ratio of the colored background area for value ranges.
165 * The colored area width is computed as
166 * InternalRadius * (1 - FACTOR_COLOR_RADIUS)
167 * @type {number}
168 */
169 goog.ui.Gauge.FACTOR_COLOR_RADIUS = 0.75;
170
171
172 /**
173 * The ratio of the major ticks length start position, from the radius.
174 * The major ticks length width is computed as
175 * InternalRadius * (1 - FACTOR_MAJOR_TICKS)
176 * @type {number}
177 */
178 goog.ui.Gauge.FACTOR_MAJOR_TICKS = 0.8;
179
180
181 /**
182 * The ratio of the minor ticks length start position, from the radius.
183 * The minor ticks length width is computed as
184 * InternalRadius * (1 - FACTOR_MINOR_TICKS)
185 * @type {number}
186 */
187 goog.ui.Gauge.FACTOR_MINOR_TICKS = 0.9;
188
189
190 /**
191 * The length of the needle front (value facing) from the internal radius.
192 * The needle front is the part of the needle that points to the value.
193 * @type {number}
194 */
195 goog.ui.Gauge.FACTOR_NEEDLE_FRONT = 0.95;
196
197
198 /**
199 * The length of the needle back relative to the internal radius.
200 * The needle back is the part of the needle that points away from the value.
201 * @type {number}
202 */
203 goog.ui.Gauge.FACTOR_NEEDLE_BACK = 0.3;
204
205
206 /**
207 * The width of the needle front at the hinge.
208 * This is the width of the curve control point, the actual width is
209 * computed by the curve itself.
210 * @type {number}
211 */
212 goog.ui.Gauge.FACTOR_NEEDLE_WIDTH = 0.07;
213
214
215 /**
216 * The width (radius) of the needle hinge from the gauge radius.
217 * @type {number}
218 */
219 goog.ui.Gauge.FACTOR_NEEDLE_HINGE = 0.15;
220
221
222 /**
223 * The title font size (height) for titles relative to the internal radius.
224 * @type {number}
225 */
226 goog.ui.Gauge.FACTOR_TITLE_FONT_SIZE = 0.16;
227
228
229 /**
230 * The offset of the title from the center, relative to the internal radius.
231 * @type {number}
232 */
233 goog.ui.Gauge.FACTOR_TITLE_OFFSET = 0.35;
234
235
236 /**
237 * The formatted value font size (height) relative to the internal radius.
238 * @type {number}
239 */
240 goog.ui.Gauge.FACTOR_VALUE_FONT_SIZE = 0.18;
241
242
243 /**
244 * The title font size (height) for tick labels relative to the internal radius.
245 * @type {number}
246 */
247 goog.ui.Gauge.FACTOR_TICK_LABEL_FONT_SIZE = 0.14;
248
249
250 /**
251 * The offset of the formatted value down from the center, relative to the
252 * internal radius.
253 * @type {number}
254 */
255 goog.ui.Gauge.FACTOR_VALUE_OFFSET = 0.75;
256
257
258 /**
259 * The font name for title text.
260 * @type {string}
261 */
262 goog.ui.Gauge.TITLE_FONT_NAME = 'arial';
263
264
265 /**
266 * The maximal size of a step the needle can move (percent from size of range).
267 * If the needle needs to move more, it will be moved in animated steps, to
268 * show a smooth transition between values.
269 * @type {number}
270 */
271 goog.ui.Gauge.NEEDLE_MOVE_MAX_STEP = 0.02;
272
273
274 /**
275 * Time in miliseconds for animating a move of the value pointer.
276 * @type {number}
277 */
278 goog.ui.Gauge.NEEDLE_MOVE_TIME = 400;
279
280
281 /**
282 * Tolerance factor for how much values can exceed the range (being too
283 * low or too high). The value is presented as a position (percentage).
284 * @type {number}
285 */
286 goog.ui.Gauge.MAX_EXCEED_POSITION_POSITION = 0.02;
287
288
289 /**
290 * The minimal value that can be displayed.
291 * @private
292 * @type {number}
293 */
294 goog.ui.Gauge.prototype.minValue_ = 0;
295
296
297 /**
298 * The maximal value that can be displayed.
299 * @private
300 * @type {number}
301 */
302 goog.ui.Gauge.prototype.maxValue_ = 100;
303
304
305 /**
306 * The number of major tick sections.
307 * @private
308 * @type {number}
309 */
310 goog.ui.Gauge.prototype.majorTicks_ = 5;
311
312
313 /**
314 * The number of minor tick sections in each major tick section.
315 * @private
316 * @type {number}
317 */
318 goog.ui.Gauge.prototype.minorTicks_ = 2;
319
320
321 /**
322 * The current value that needs to be displayed in the gauge.
323 * @private
324 * @type {number}
325 */
326 goog.ui.Gauge.prototype.value_ = 0;
327
328
329 /**
330 * The current value formatted into a String.
331 * @private
332 * @type {?string}
333 */
334 goog.ui.Gauge.prototype.formattedValue_ = null;
335
336
337 /**
338 * The current colors theme.
339 * @private
340 * @type {goog.ui.GaugeTheme?}
341 */
342 goog.ui.Gauge.prototype.theme_ = null;
343
344
345 /**
346 * Title to display above the gauge center.
347 * @private
348 * @type {?string}
349 */
350 goog.ui.Gauge.prototype.titleTop_ = null;
351
352
353 /**
354 * Title to display below the gauge center.
355 * @private
356 * @type {?string}
357 */
358 goog.ui.Gauge.prototype.titleBottom_ = null;
359
360
361 /**
362 * Font to use for drawing titles.
363 * If null (default), computed dynamically with a size relative to the
364 * gauge radius.
365 * @private
366 * @type {goog.graphics.Font?}
367 */
368 goog.ui.Gauge.prototype.titleFont_ = null;
369
370
371 /**
372 * Font to use for drawing the formatted value.
373 * If null (default), computed dynamically with a size relative to the
374 * gauge radius.
375 * @private
376 * @type {goog.graphics.Font?}
377 */
378 goog.ui.Gauge.prototype.valueFont_ = null;
379
380
381 /**
382 * Font to use for drawing tick labels.
383 * If null (default), computed dynamically with a size relative to the
384 * gauge radius.
385 * @private
386 * @type {goog.graphics.Font?}
387 */
388 goog.ui.Gauge.prototype.tickLabelFont_ = null;
389
390
391 /**
392 * The size in angles of the gauge axis area.
393 * @private
394 * @type {number}
395 */
396 goog.ui.Gauge.prototype.angleSpan_ = 270;
397
398
399 /**
400 * The radius for drawing the needle.
401 * Computed on full redraw, and used on every animation step of moving
402 * the needle.
403 * @type {number}
404 * @private
405 */
406 goog.ui.Gauge.prototype.needleRadius_ = 0;
407
408
409 /**
410 * The group elemnt of the needle. Contains all elements that change when the
411 * gauge value changes.
412 * @type {goog.graphics.GroupElement?}
413 * @private
414 */
415 goog.ui.Gauge.prototype.needleGroup_ = null;
416
417
418 /**
419 * The current position (0-1) of the visible needle.
420 * Initially set to null to prevent animation on first opening of the gauge.
421 * @type {?number}
422 * @private
423 */
424 goog.ui.Gauge.prototype.needleValuePosition_ = null;
425
426
427 /**
428 * Text labels to display by major tick marks.
429 * @type {Array<string>?}
430 * @private
431 */
432 goog.ui.Gauge.prototype.majorTickLabels_ = null;
433
434
435 /**
436 * Animation object while needle is being moved (animated).
437 * @type {goog.fx.Animation?}
438 * @private
439 */
440 goog.ui.Gauge.prototype.animation_ = null;
441
442
443 /**
444 * @return {number} The minimum value of the range.
445 */
446 goog.ui.Gauge.prototype.getMinimum = function() {
447 return this.minValue_;
448 };
449
450
451 /**
452 * Sets the minimum value of the range
453 * @param {number} min The minimum value of the range.
454 */
455 goog.ui.Gauge.prototype.setMinimum = function(min) {
456 this.minValue_ = min;
457 var element = this.getElement();
458 if (element) {
459 goog.a11y.aria.setState(element, 'valuemin', min);
460 }
461 };
462
463
464 /**
465 * @return {number} The maximum value of the range.
466 */
467 goog.ui.Gauge.prototype.getMaximum = function() {
468 return this.maxValue_;
469 };
470
471
472 /**
473 * Sets the maximum number of the range
474 * @param {number} max The maximum value of the range.
475 */
476 goog.ui.Gauge.prototype.setMaximum = function(max) {
477 this.maxValue_ = max;
478
479 var element = this.getElement();
480 if (element) {
481 goog.a11y.aria.setState(element, 'valuemax', max);
482 }
483 };
484
485
486 /**
487 * Sets the current value range displayed by the gauge.
488 * @param {number} value The current value for the gauge. This value
489 * determines the position of the needle of the gauge.
490 * @param {string=} opt_formattedValue The string value to show in the gauge.
491 * If not specified, no string value will be displayed.
492 */
493 goog.ui.Gauge.prototype.setValue = function(value, opt_formattedValue) {
494 this.value_ = value;
495 this.formattedValue_ = opt_formattedValue || null;
496
497 this.stopAnimation_(); // Stop the active animation if exists
498
499 // Compute desired value position (normalize value to range 0-1)
500 var valuePosition = this.valueToRangePosition_(value);
501 if (this.needleValuePosition_ == null) {
502 // No animation on initial display
503 this.needleValuePosition_ = valuePosition;
504 this.drawValue_();
505 } else {
506 // Animate move
507 this.animation_ = new goog.fx.Animation(
508 [this.needleValuePosition_], [valuePosition],
509 goog.ui.Gauge.NEEDLE_MOVE_TIME, goog.fx.easing.inAndOut);
510
511 var events = [
512 goog.fx.Transition.EventType.BEGIN, goog.fx.Animation.EventType.ANIMATE,
513 goog.fx.Transition.EventType.END
514 ];
515 goog.events.listen(this.animation_, events, this.onAnimate_, false, this);
516 goog.events.listen(
517 this.animation_, goog.fx.Transition.EventType.END, this.onAnimateEnd_,
518 false, this);
519
520 // Start animation
521 this.animation_.play(false);
522 }
523
524 var element = this.getElement();
525 if (element) {
526 goog.a11y.aria.setState(element, 'valuenow', this.value_);
527 }
528 };
529
530
531 /**
532 * Sets the number of major tick sections and minor tick sections.
533 * @param {number} majorUnits The number of major tick sections.
534 * @param {number} minorUnits The number of minor tick sections for each major
535 * tick section.
536 */
537 goog.ui.Gauge.prototype.setTicks = function(majorUnits, minorUnits) {
538 this.majorTicks_ = Math.max(1, majorUnits);
539 this.minorTicks_ = Math.max(1, minorUnits);
540 this.draw_();
541 };
542
543
544 /**
545 * Sets the labels of the major ticks.
546 * @param {Array<string>} tickLabels A text label for each major tick value.
547 */
548 goog.ui.Gauge.prototype.setMajorTickLabels = function(tickLabels) {
549 this.majorTickLabels_ = tickLabels;
550 this.draw_();
551 };
552
553
554 /**
555 * Sets the top title of the gauge.
556 * The top title is displayed above the center.
557 * @param {string} text The top title text.
558 */
559 goog.ui.Gauge.prototype.setTitleTop = function(text) {
560 this.titleTop_ = text;
561 this.draw_();
562 };
563
564
565 /**
566 * Sets the bottom title of the gauge.
567 * The top title is displayed below the center.
568 * @param {string} text The bottom title text.
569 */
570 goog.ui.Gauge.prototype.setTitleBottom = function(text) {
571 this.titleBottom_ = text;
572 this.draw_();
573 };
574
575
576 /**
577 * Sets the font for displaying top and bottom titles.
578 * @param {goog.graphics.Font} font The font for titles.
579 */
580 goog.ui.Gauge.prototype.setTitleFont = function(font) {
581 this.titleFont_ = font;
582 this.draw_();
583 };
584
585
586 /**
587 * Sets the font for displaying the formatted value.
588 * @param {goog.graphics.Font} font The font for displaying the value.
589 */
590 goog.ui.Gauge.prototype.setValueFont = function(font) {
591 this.valueFont_ = font;
592 this.drawValue_();
593 };
594
595
596 /**
597 * Sets the color theme for drawing the gauge.
598 * @param {goog.ui.GaugeTheme} theme The color theme to use.
599 */
600 goog.ui.Gauge.prototype.setTheme = function(theme) {
601 this.theme_ = theme;
602 this.draw_();
603 };
604
605
606 /**
607 * Set the background color for a range of values on the gauge.
608 * @param {number} fromValue The lower (start) value of the colored range.
609 * @param {number} toValue The higher (end) value of the colored range.
610 * @param {string} color The color name to paint the range with. For example
611 * 'red', '#ffcc00' or constants like goog.ui.Gauge.RED.
612 */
613 goog.ui.Gauge.prototype.addBackgroundColor = function(
614 fromValue, toValue, color) {
615 this.rangeColors_.push(
616 new goog.ui.GaugeColoredRange(fromValue, toValue, color));
617 this.draw_();
618 };
619
620
621 /**
622 * Creates the DOM representation of the graphics area.
623 * @override
624 */
625 goog.ui.Gauge.prototype.createDom = function() {
626 this.setElementInternal(
627 this.getDomHelper().createDom(
628 goog.dom.TagName.DIV, goog.getCssName('goog-gauge'),
629 this.graphics_.getElement()));
630 };
631
632
633 /**
634 * Clears the entire graphics area.
635 * @private
636 */
637 goog.ui.Gauge.prototype.clear_ = function() {
638 this.graphics_.clear();
639 this.needleGroup_ = null;
640 };
641
642
643 /**
644 * Redraw the entire gauge.
645 * @private
646 */
647 goog.ui.Gauge.prototype.draw_ = function() {
648 if (!this.isInDocument()) {
649 return;
650 }
651
652 this.clear_();
653
654 var x, y;
655 var size = Math.min(this.width_, this.height_);
656 var r = Math.round(goog.ui.Gauge.FACTOR_RADIUS_FROM_SIZE * size);
657 var cx = this.width_ / 2;
658 var cy = this.height_ / 2;
659
660 var theme = this.theme_;
661 if (!theme) {
662 // Lazy allocation of default theme, common to all instances
663 theme = goog.ui.Gauge.prototype.theme_ = new goog.ui.GaugeTheme();
664 }
665
666 // Draw main circle frame around gauge
667 var graphics = this.graphics_;
668 var stroke = this.theme_.getExternalBorderStroke();
669 var fill = theme.getExternalBorderFill(cx, cy, r);
670 graphics.drawCircle(cx, cy, r, stroke, fill);
671
672 r -= stroke.getWidth();
673 r = Math.round(r * goog.ui.Gauge.FACTOR_MAIN_AREA);
674 stroke = theme.getInternalBorderStroke();
675 fill = theme.getInternalBorderFill(cx, cy, r);
676 graphics.drawCircle(cx, cy, r, stroke, fill);
677 r -= stroke.getWidth() * 2;
678
679 // Draw Background with external and internal borders
680 var rBackgroundInternal = r * goog.ui.Gauge.FACTOR_COLOR_RADIUS;
681 for (var i = 0; i < this.rangeColors_.length; i++) {
682 var rangeColor = this.rangeColors_[i];
683 var fromValue = rangeColor.fromValue;
684 var toValue = rangeColor.toValue;
685 var path = new goog.graphics.Path();
686 var fromAngle = this.valueToAngle_(fromValue);
687 var toAngle = this.valueToAngle_(toValue);
688 // Move to outer point at "from" angle
689 path.moveTo(
690 cx + goog.math.angleDx(fromAngle, r),
691 cy + goog.math.angleDy(fromAngle, r));
692 // Arc to outer point at "to" angle
693 path.arcTo(r, r, fromAngle, toAngle - fromAngle);
694 // Line to inner point at "to" angle
695 path.lineTo(
696 cx + goog.math.angleDx(toAngle, rBackgroundInternal),
697 cy + goog.math.angleDy(toAngle, rBackgroundInternal));
698 // Arc to inner point at "from" angle
699 path.arcTo(
700 rBackgroundInternal, rBackgroundInternal, toAngle, fromAngle - toAngle);
701 path.close();
702 fill = new goog.graphics.SolidFill(rangeColor.backgroundColor);
703 graphics.drawPath(path, null, fill);
704 }
705
706 // Draw titles
707 if (this.titleTop_ || this.titleBottom_) {
708 var font = this.titleFont_;
709 if (!font) {
710 // Lazy creation of font
711 var fontSize = Math.round(r * goog.ui.Gauge.FACTOR_TITLE_FONT_SIZE);
712 font = new goog.graphics.Font(fontSize, goog.ui.Gauge.TITLE_FONT_NAME);
713 this.titleFont_ = font;
714 }
715 fill = new goog.graphics.SolidFill(theme.getTitleColor());
716 if (this.titleTop_) {
717 y = cy - Math.round(r * goog.ui.Gauge.FACTOR_TITLE_OFFSET);
718 graphics.drawTextOnLine(
719 this.titleTop_, 0, y, this.width_, y, 'center', font, null, fill);
720 }
721 if (this.titleBottom_) {
722 y = cy + Math.round(r * goog.ui.Gauge.FACTOR_TITLE_OFFSET);
723 graphics.drawTextOnLine(
724 this.titleBottom_, 0, y, this.width_, y, 'center', font, null, fill);
725 }
726 }
727
728 // Draw tick marks
729 var majorTicks = this.majorTicks_;
730 var minorTicks = this.minorTicks_;
731 var rMajorTickInternal = r * goog.ui.Gauge.FACTOR_MAJOR_TICKS;
732 var rMinorTickInternal = r * goog.ui.Gauge.FACTOR_MINOR_TICKS;
733 var ticks = majorTicks * minorTicks;
734 var valueRange = this.maxValue_ - this.minValue_;
735 var tickValueSpan = valueRange / ticks;
736 var majorTicksPath = new goog.graphics.Path();
737 var minorTicksPath = new goog.graphics.Path();
738
739 var tickLabelFill = new goog.graphics.SolidFill(theme.getTickLabelColor());
740 var tickLabelFont = this.tickLabelFont_;
741 if (!tickLabelFont) {
742 tickLabelFont = new goog.graphics.Font(
743 Math.round(r * goog.ui.Gauge.FACTOR_TICK_LABEL_FONT_SIZE),
744 goog.ui.Gauge.TITLE_FONT_NAME);
745 }
746 var tickLabelFontSize = tickLabelFont.size;
747
748 for (var i = 0; i <= ticks; i++) {
749 var angle = this.valueToAngle_(i * tickValueSpan + this.minValue_);
750 var isMajorTick = i % minorTicks == 0;
751 var rInternal = isMajorTick ? rMajorTickInternal : rMinorTickInternal;
752 var path = isMajorTick ? majorTicksPath : minorTicksPath;
753 x = cx + goog.math.angleDx(angle, rInternal);
754 y = cy + goog.math.angleDy(angle, rInternal);
755 path.moveTo(x, y);
756 x = cx + goog.math.angleDx(angle, r);
757 y = cy + goog.math.angleDy(angle, r);
758 path.lineTo(x, y);
759
760 // Draw the tick's label for major ticks
761 if (isMajorTick && this.majorTickLabels_) {
762 var tickIndex = Math.floor(i / minorTicks);
763 var label = this.majorTickLabels_[tickIndex];
764 if (label) {
765 x = cx + goog.math.angleDx(angle, rInternal - tickLabelFontSize / 2);
766 y = cy + goog.math.angleDy(angle, rInternal - tickLabelFontSize / 2);
767 var x1, x2;
768 var align = 'center';
769 if (angle > 280 || angle < 90) {
770 align = 'right';
771 x1 = 0;
772 x2 = x;
773 } else if (angle >= 90 && angle < 260) {
774 align = 'left';
775 x1 = x;
776 x2 = this.width_;
777 } else {
778 // Values around top (angle 260-280) are centered around point
779 var dw = Math.min(x, this.width_ - x); // Nearest side border
780 x1 = x - dw;
781 x2 = x + dw;
782 y += Math.round(tickLabelFontSize / 4); // Movea bit down
783 }
784 graphics.drawTextOnLine(
785 label, x1, y, x2, y, align, tickLabelFont, null, tickLabelFill);
786 }
787 }
788 }
789 stroke = theme.getMinorTickStroke();
790 graphics.drawPath(minorTicksPath, stroke, null);
791 stroke = theme.getMajorTickStroke();
792 graphics.drawPath(majorTicksPath, stroke, null);
793
794 // Draw the needle and the value label. Stop animation when doing
795 // full redraw and jump to the final value position.
796 this.stopAnimation_();
797 this.needleRadius_ = r;
798 this.drawValue_();
799 };
800
801
802 /**
803 * Handle animation events while the hand is moving.
804 * @param {goog.fx.AnimationEvent} e The event.
805 * @private
806 */
807 goog.ui.Gauge.prototype.onAnimate_ = function(e) {
808 this.needleValuePosition_ = e.x;
809 this.drawValue_();
810 };
811
812
813 /**
814 * Handle animation events when hand move is complete.
815 * @private
816 */
817 goog.ui.Gauge.prototype.onAnimateEnd_ = function() {
818 this.stopAnimation_();
819 };
820
821
822 /**
823 * Stop the current animation, if it is active.
824 * @private
825 */
826 goog.ui.Gauge.prototype.stopAnimation_ = function() {
827 if (this.animation_) {
828 goog.events.removeAll(this.animation_);
829 this.animation_.stop(false);
830 this.animation_ = null;
831 }
832 };
833
834
835 /**
836 * Convert a value to the position in the range. The returned position
837 * is a value between 0 and 1, where 0 indicates the lowest range value,
838 * 1 is the highest range, and any value in between is proportional
839 * to mapping the range to (0-1).
840 * If the value is not within the range, the returned value may be a bit
841 * lower than 0, or a bit higher than 1. This is done so that values out
842 * of range will be displayed just a bit outside of the gauge axis.
843 * @param {number} value The value to convert.
844 * @private
845 * @return {number} The range position.
846 */
847 goog.ui.Gauge.prototype.valueToRangePosition_ = function(value) {
848 var valueRange = this.maxValue_ - this.minValue_;
849 var valuePct = (value - this.minValue_) / valueRange; // 0 to 1
850
851 // If value is out of range, trim it not to be too much out of range
852 valuePct = Math.max(valuePct, -goog.ui.Gauge.MAX_EXCEED_POSITION_POSITION);
853 valuePct = Math.min(valuePct, 1 + goog.ui.Gauge.MAX_EXCEED_POSITION_POSITION);
854
855 return valuePct;
856 };
857
858
859 /**
860 * Convert a value to an angle based on the value range and angle span
861 * @param {number} value The value.
862 * @return {number} The angle where this value is located on the round
863 * axis, based on the range and angle span.
864 * @private
865 */
866 goog.ui.Gauge.prototype.valueToAngle_ = function(value) {
867 var valuePct = this.valueToRangePosition_(value);
868 return this.valuePositionToAngle_(valuePct);
869 };
870
871
872 /**
873 * Convert a value-position (percent in the range) to an angle based on
874 * the angle span. A value-position is a value that has been proportinally
875 * adjusted to a value betwwen 0-1, proportionaly to the range.
876 * @param {number} valuePct The value.
877 * @return {number} The angle where this value is located on the round
878 * axis, based on the range and angle span.
879 * @private
880 */
881 goog.ui.Gauge.prototype.valuePositionToAngle_ = function(valuePct) {
882 var startAngle = goog.math.standardAngle((360 - this.angleSpan_) / 2 + 90);
883 return this.angleSpan_ * valuePct + startAngle;
884 };
885
886
887 /**
888 * Draw the elements that depend on the current value (the needle and
889 * the formatted value). This function is called whenever a value is changed
890 * or when the entire gauge is redrawn.
891 * @private
892 */
893 goog.ui.Gauge.prototype.drawValue_ = function() {
894 if (!this.isInDocument()) {
895 return;
896 }
897
898 var r = this.needleRadius_;
899 var graphics = this.graphics_;
900 var theme = this.theme_;
901 var cx = this.width_ / 2;
902 var cy = this.height_ / 2;
903 var angle = this.valuePositionToAngle_(
904 /** @type {number} */ (this.needleValuePosition_));
905
906 // Compute the needle path
907 var frontRadius = Math.round(r * goog.ui.Gauge.FACTOR_NEEDLE_FRONT);
908 var backRadius = Math.round(r * goog.ui.Gauge.FACTOR_NEEDLE_BACK);
909 var frontDx = goog.math.angleDx(angle, frontRadius);
910 var frontDy = goog.math.angleDy(angle, frontRadius);
911 var backDx = goog.math.angleDx(angle, backRadius);
912 var backDy = goog.math.angleDy(angle, backRadius);
913 var angleRight = goog.math.standardAngle(angle + 90);
914 var distanceControlPointBase = r * goog.ui.Gauge.FACTOR_NEEDLE_WIDTH;
915 var controlPointMidDx =
916 goog.math.angleDx(angleRight, distanceControlPointBase);
917 var controlPointMidDy =
918 goog.math.angleDy(angleRight, distanceControlPointBase);
919
920 var path = new goog.graphics.Path();
921 path.moveTo(cx + frontDx, cy + frontDy);
922 path.curveTo(
923 cx + controlPointMidDx, cy + controlPointMidDy,
924 cx - backDx + (controlPointMidDx / 2),
925 cy - backDy + (controlPointMidDy / 2), cx - backDx, cy - backDy);
926 path.curveTo(
927 cx - backDx - (controlPointMidDx / 2),
928 cy - backDy - (controlPointMidDy / 2), cx - controlPointMidDx,
929 cy - controlPointMidDy, cx + frontDx, cy + frontDy);
930
931 // Draw the needle hinge
932 var rh = Math.round(r * goog.ui.Gauge.FACTOR_NEEDLE_HINGE);
933
934 // Clean previous needle
935 var needleGroup = this.needleGroup_;
936 if (needleGroup) {
937 needleGroup.clear();
938 } else {
939 needleGroup = this.needleGroup_ = graphics.createGroup();
940 }
941
942 // Draw current formatted value if provided.
943 if (this.formattedValue_) {
944 var font = this.valueFont_;
945 if (!font) {
946 var fontSize = Math.round(r * goog.ui.Gauge.FACTOR_VALUE_FONT_SIZE);
947 font = new goog.graphics.Font(fontSize, goog.ui.Gauge.TITLE_FONT_NAME);
948 font.bold = true;
949 this.valueFont_ = font;
950 }
951 var fill = new goog.graphics.SolidFill(theme.getValueColor());
952 var y = cy + Math.round(r * goog.ui.Gauge.FACTOR_VALUE_OFFSET);
953 graphics.drawTextOnLine(
954 this.formattedValue_, 0, y, this.width_, y, 'center', font, null, fill,
955 needleGroup);
956 }
957
958 // Draw the needle
959 var stroke = theme.getNeedleStroke();
960 var fill = theme.getNeedleFill(cx, cy, rh);
961 graphics.drawPath(path, stroke, fill, needleGroup);
962 stroke = theme.getHingeStroke();
963 fill = theme.getHingeFill(cx, cy, rh);
964 graphics.drawCircle(cx, cy, rh, stroke, fill, needleGroup);
965 };
966
967
968 /**
969 * Redraws the entire gauge.
970 * Should be called after theme colors have been changed.
971 */
972 goog.ui.Gauge.prototype.redraw = function() {
973 this.draw_();
974 };
975
976
977 /** @override */
978 goog.ui.Gauge.prototype.enterDocument = function() {
979 goog.ui.Gauge.superClass_.enterDocument.call(this);
980
981 // set roles and states
982 var el = this.getElement();
983 goog.asserts.assert(el, 'The DOM element for the gauge cannot be null.');
984 goog.a11y.aria.setRole(el, 'progressbar');
985 goog.a11y.aria.setState(el, 'live', 'polite');
986 goog.a11y.aria.setState(el, 'valuemin', this.minValue_);
987 goog.a11y.aria.setState(el, 'valuemax', this.maxValue_);
988 goog.a11y.aria.setState(el, 'valuenow', this.value_);
989 this.draw_();
990 };
991
992
993 /** @override */
994 goog.ui.Gauge.prototype.exitDocument = function() {
995 goog.ui.Gauge.superClass_.exitDocument.call(this);
996 this.stopAnimation_();
997 };
998
999
1000 /** @override */
1001 goog.ui.Gauge.prototype.disposeInternal = function() {
1002 this.stopAnimation_();
1003 this.graphics_.dispose();
1004 delete this.graphics_;
1005 delete this.needleGroup_;
1006 delete this.theme_;
1007 delete this.rangeColors_;
1008 goog.ui.Gauge.superClass_.disposeInternal.call(this);
1009 };