/**
* @license
* Copyright The Closure Library Authors.
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Gauge UI component, using browser vector graphics.
* @see ../demos/gauge.html
*/
goog.module('goog.ui.Gauge');
goog.module.declareLegacyNamespace();
const AbstractGraphics = goog.requireType('goog.graphics.AbstractGraphics');
const Animation = goog.require('goog.fx.Animation');
const AnimationEvent = goog.requireType('goog.fx.AnimationEvent');
const Component = goog.require('goog.ui.Component');
const DomHelper = goog.requireType('goog.dom.DomHelper');
const Font = goog.require('goog.graphics.Font');
const GaugeTheme = goog.require('goog.ui.GaugeTheme');
const GroupElement = goog.requireType('goog.graphics.GroupElement');
const Path = goog.require('goog.graphics.Path');
const SolidFill = goog.require('goog.graphics.SolidFill');
const TagName = goog.require('goog.dom.TagName');
const Transition = goog.require('goog.fx.Transition');
const aria = goog.require('goog.a11y.aria');
const asserts = goog.require('goog.asserts');
const easing = goog.require('goog.fx.easing');
const googEvents = goog.require('goog.events');
const googGraphics = goog.require('goog.graphics');
const googMath = goog.require('goog.math');
/**
* The radius of the entire gauge from the canvas size.
* @type {number}
*/
const FACTOR_RADIUS_FROM_SIZE = 0.45;
/**
* The ratio of internal gauge radius from entire radius.
* The remaining area is the border around the gauge.
* @type {number}
*/
const FACTOR_MAIN_AREA = 0.9;
/**
* The ratio of the colored background area for value ranges.
* The colored area width is computed as
* InternalRadius * (1 - FACTOR_COLOR_RADIUS)
* @type {number}
*/
const FACTOR_COLOR_RADIUS = 0.75;
/**
* The ratio of the major ticks length start position, from the radius.
* The major ticks length width is computed as
* InternalRadius * (1 - FACTOR_MAJOR_TICKS)
* @type {number}
*/
const FACTOR_MAJOR_TICKS = 0.8;
/**
* The ratio of the minor ticks length start position, from the radius.
* The minor ticks length width is computed as
* InternalRadius * (1 - FACTOR_MINOR_TICKS)
* @type {number}
*/
const FACTOR_MINOR_TICKS = 0.9;
/**
* The length of the needle front (value facing) from the internal radius.
* The needle front is the part of the needle that points to the value.
* @type {number}
*/
const FACTOR_NEEDLE_FRONT = 0.95;
/**
* The length of the needle back relative to the internal radius.
* The needle back is the part of the needle that points away from the value.
* @type {number}
*/
const FACTOR_NEEDLE_BACK = 0.3;
/**
* The width of the needle front at the hinge.
* This is the width of the curve control point, the actual width is
* computed by the curve itself.
* @type {number}
*/
const FACTOR_NEEDLE_WIDTH = 0.07;
/**
* The width (radius) of the needle hinge from the gauge radius.
* @type {number}
*/
const FACTOR_NEEDLE_HINGE = 0.15;
/**
* The title font size (height) for titles relative to the internal radius.
* @type {number}
*/
const FACTOR_TITLE_FONT_SIZE = 0.16;
/**
* The offset of the title from the center, relative to the internal radius.
* @type {number}
*/
const FACTOR_TITLE_OFFSET = 0.35;
/**
* The formatted value font size (height) relative to the internal radius.
* @type {number}
*/
const FACTOR_VALUE_FONT_SIZE = 0.18;
/**
* The title font size (height) for tick labels relative to the internal radius.
* @type {number}
*/
const FACTOR_TICK_LABEL_FONT_SIZE = 0.14;
/**
* The offset of the formatted value down from the center, relative to the
* internal radius.
* @type {number}
*/
const FACTOR_VALUE_OFFSET = 0.75;
/**
* The font name for title text.
* @type {string}
*/
const TITLE_FONT_NAME = 'arial';
/**
* Time in miliseconds for animating a move of the value pointer.
* @type {number}
*/
const NEEDLE_MOVE_TIME = 400;
/**
* Tolerance factor for how much values can exceed the range (being too
* low or too high). The value is presented as a position (percentage).
* @type {number}
*/
const MAX_EXCEED_POSITION_POSITION = 0.02;
/**
* Information on how to decorate a range in the gauge.
*/
class GaugeColoredRange {
/**
* @param {number} fromValue The range start (minimal) value.
* @param {number} toValue The range end (maximal) value.
* @param {string} backgroundColor Color to fill the range background with.
*/
constructor(fromValue, toValue, backgroundColor) {
/**
* The range start (minimal) value.
* @type {number}
*/
this.fromValue = fromValue;
/**
* The range end (maximal) value.
* @type {number}
*/
this.toValue = toValue;
/**
* Color to fill the range background with.
* @type {string}
*/
this.backgroundColor = backgroundColor;
}
}
/**
* A UI component that displays a gauge.
* A gauge displayes a current value within a round axis that represents a
* given range.
* The gauge is built from an external border, and internal border inside it,
* ticks and labels inside the internal border, and a needle that points to
* the current value.
* @final
*/
class Gauge extends Component {
/**
* @param {number} width The width in pixels.
* @param {number} height The height in pixels.
* @param {!DomHelper=} opt_domHelper The DOM helper object for the
* document we want to render in.
*/
constructor(width, height, opt_domHelper) {
super(opt_domHelper);
/**
* The width in pixels of this component.
* @type {number}
* @private
*/
this.width_ = width;
/**
* The height in pixels of this component.
* @type {number}
* @private
*/
this.height_ = height;
/**
* The underlying graphics.
* @type {!AbstractGraphics}
* @private
*/
this.graphics_ =
googGraphics.createGraphics(width, height, null, null, opt_domHelper);
/**
* Colors to paint the background of certain ranges (optional).
* @type {!Array<!GaugeColoredRange>}
* @private
*/
this.rangeColors_ = [];
/**
* The minimal value that can be displayed.
* @private
* @type {number}
*/
this.minValue_ = 0;
/**
* The maximal value that can be displayed.
* @private
* @type {number}
*/
this.maxValue_ = 100;
/**
* The number of major tick sections.
* @private
* @type {number}
*/
this.majorTicks_ = 5;
/**
* The number of minor tick sections in each major tick section.
* @private
* @type {number}
*/
this.minorTicks_ = 2;
/**
* The current value that needs to be displayed in the gauge.
* @private
* @type {number}
*/
this.value_ = 0;
/**
* The current value formatted into a String.
* @private
* @type {?string}
*/
this.formattedValue_ = null;
/**
* The current colors theme.
* @private
* @type {?GaugeTheme}
*/
this.theme_ = null;
/**
* Title to display above the gauge center.
* @private
* @type {?string}
*/
this.titleTop_ = null;
/**
* Title to display below the gauge center.
* @private
* @type {?string}
*/
this.titleBottom_ = null;
/**
* Font to use for drawing titles.
* If null (default), computed dynamically with a size relative to the
* gauge radius.
* @private
* @type {?Font}
*/
this.titleFont_ = null;
/**
* Font to use for drawing the formatted value.
* If null (default), computed dynamically with a size relative to the
* gauge radius.
* @private
* @type {?Font}
*/
this.valueFont_ = null;
/**
* Font to use for drawing tick labels.
* If null (default), computed dynamically with a size relative to the
* gauge radius.
* @private
* @type {?Font}
*/
this.tickLabelFont_ = null;
/**
* The size in angles of the gauge axis area.
* @private
* @type {number}
*/
this.angleSpan_ = 270;
/**
* The radius for drawing the needle.
* Computed on full redraw, and used on every animation step of moving
* the needle.
* @type {number}
* @private
*/
this.needleRadius_ = 0;
/**
* The group elemnt of the needle. Contains all elements that change when
* the gauge value changes.
* @type {?GroupElement}
* @private
*/
this.needleGroup_ = null;
/**
* The current position (0-1) of the visible needle.
* Initially set to null to prevent animation on first opening of the gauge.
* @type {?number}
* @private
*/
this.needleValuePosition_ = null;
/**
* Text labels to display by major tick marks.
* @type {?Array<string>}
* @private
*/
this.majorTickLabels_ = null;
/**
* Animation object while needle is being moved (animated).
* @type {?Animation}
* @private
*/
this.animation_ = null;
}
/**
* @return {number} The minimum value of the range.
*/
getMinimum() {
return this.minValue_;
}
/**
* Sets the minimum value of the range
* @param {number} min The minimum value of the range.
*/
setMinimum(min) {
this.minValue_ = min;
const element = this.getElement();
if (element) {
aria.setState(element, 'valuemin', min);
}
}
/**
* @return {number} The maximum value of the range.
*/
getMaximum() {
return this.maxValue_;
}
/**
* Sets the maximum number of the range
* @param {number} max The maximum value of the range.
*/
setMaximum(max) {
this.maxValue_ = max;
const element = this.getElement();
if (element) {
aria.setState(element, 'valuemax', max);
}
}
/**
* Sets the current value range displayed by the gauge.
* @param {number} value The current value for the gauge. This value
* determines the position of the needle of the gauge.
* @param {string=} opt_formattedValue The string value to show in the gauge.
* If not specified, no string value will be displayed.
*/
setValue(value, opt_formattedValue) {
this.value_ = value;
this.formattedValue_ = opt_formattedValue || null;
this.stopAnimation_(); // Stop the active animation if exists
// Compute desired value position (normalize value to range 0-1)
const valuePosition = this.valueToRangePosition_(value);
if (this.needleValuePosition_ == null) {
// No animation on initial display
this.needleValuePosition_ = valuePosition;
this.drawValue_();
} else {
// Animate move
this.animation_ = new Animation(
[this.needleValuePosition_], [valuePosition], NEEDLE_MOVE_TIME,
easing.inAndOut);
const events = [
Transition.EventType.BEGIN, Animation.EventType.ANIMATE,
Transition.EventType.END
];
googEvents.listen(this.animation_, events, this.onAnimate_, false, this);
googEvents.listen(
this.animation_, Transition.EventType.END, this.onAnimateEnd_, false,
this);
// Start animation
this.animation_.play(false);
}
const element = this.getElement();
if (element) {
aria.setState(element, 'valuenow', this.value_);
}
}
/**
* Sets the number of major tick sections and minor tick sections.
* @param {number} majorUnits The number of major tick sections.
* @param {number} minorUnits The number of minor tick sections for each major
* tick section.
*/
setTicks(majorUnits, minorUnits) {
this.majorTicks_ = Math.max(1, majorUnits);
this.minorTicks_ = Math.max(1, minorUnits);
this.draw_();
}
/**
* Sets the labels of the major ticks.
* @param {?Array<string>} tickLabels A text label for each major tick value.
*/
setMajorTickLabels(tickLabels) {
this.majorTickLabels_ = tickLabels;
this.draw_();
}
/**
* Sets the top title of the gauge.
* The top title is displayed above the center.
* @param {string} text The top title text.
*/
setTitleTop(text) {
this.titleTop_ = text;
this.draw_();
}
/**
* Sets the bottom title of the gauge.
* The top title is displayed below the center.
* @param {string} text The bottom title text.
*/
setTitleBottom(text) {
this.titleBottom_ = text;
this.draw_();
}
/**
* Sets the font for displaying top and bottom titles.
* @param {?Font} font The font for titles.
*/
setTitleFont(font) {
this.titleFont_ = font;
this.draw_();
}
/**
* Sets the font for displaying the formatted value.
* @param {?Font} font The font for displaying the value.
*/
setValueFont(font) {
this.valueFont_ = font;
this.drawValue_();
}
/**
* Sets the color theme for drawing the gauge.
* @param {?GaugeTheme} theme The color theme to use.
*/
setTheme(theme) {
this.theme_ = theme;
this.draw_();
}
/**
* Set the background color for a range of values on the gauge.
* @param {number} fromValue The lower (start) value of the colored range.
* @param {number} toValue The higher (end) value of the colored range.
* @param {string} color The color name to paint the range with. For example
* 'red' or '#ffcc00'.
*/
addBackgroundColor(fromValue, toValue, color) {
this.rangeColors_.push(new GaugeColoredRange(fromValue, toValue, color));
this.draw_();
}
/**
* Creates the DOM representation of the graphics area.
* @override
*/
createDom() {
this.setElementInternal(this.getDomHelper().createDom(
TagName.DIV, goog.getCssName('goog-gauge'),
this.graphics_.getElement()));
}
/**
* Clears the entire graphics area.
* @private
*/
clear_() {
this.graphics_.clear();
this.needleGroup_ = null;
}
/**
* Redraw the entire gauge.
* @private
* @suppress {strictPrimitiveOperators} Part of the
* go/strict_warnings_migration
*/
draw_() {
if (!this.isInDocument()) {
return;
}
this.clear_();
let x;
let y;
const size = Math.min(this.width_, this.height_);
let r = Math.round(FACTOR_RADIUS_FROM_SIZE * size);
const cx = this.width_ / 2;
const cy = this.height_ / 2;
let theme = this.theme_;
if (!theme) {
// Lazy allocation of default theme, common to all instances
theme = Gauge.prototype.theme_ = new GaugeTheme();
}
// Draw main circle frame around gauge
const graphics = this.graphics_;
let stroke = this.theme_.getExternalBorderStroke();
let fill = theme.getExternalBorderFill(cx, cy, r);
graphics.drawCircle(cx, cy, r, stroke, fill);
r -= stroke.getWidth();
r = Math.round(r * FACTOR_MAIN_AREA);
stroke = theme.getInternalBorderStroke();
fill = theme.getInternalBorderFill(cx, cy, r);
graphics.drawCircle(cx, cy, r, stroke, fill);
r -= stroke.getWidth() * 2;
// Draw Background with external and internal borders
const rBackgroundInternal = r * FACTOR_COLOR_RADIUS;
for (let i = 0; i < this.rangeColors_.length; i++) {
const rangeColor = this.rangeColors_[i];
const fromValue = rangeColor.fromValue;
const toValue = rangeColor.toValue;
const path = new Path();
const fromAngle = this.valueToAngle_(fromValue);
const toAngle = this.valueToAngle_(toValue);
// Move to outer point at "from" angle
path.moveTo(
cx + googMath.angleDx(fromAngle, r),
cy + googMath.angleDy(fromAngle, r));
// Arc to outer point at "to" angle
path.arcTo(r, r, fromAngle, toAngle - fromAngle);
// Line to inner point at "to" angle
path.lineTo(
cx + googMath.angleDx(toAngle, rBackgroundInternal),
cy + googMath.angleDy(toAngle, rBackgroundInternal));
// Arc to inner point at "from" angle
path.arcTo(
rBackgroundInternal, rBackgroundInternal, toAngle,
fromAngle - toAngle);
path.close();
fill = new SolidFill(rangeColor.backgroundColor);
graphics.drawPath(path, null, fill);
}
// Draw titles
if (this.titleTop_ || this.titleBottom_) {
let font = this.titleFont_;
if (!font) {
// Lazy creation of font
const fontSize = Math.round(r * FACTOR_TITLE_FONT_SIZE);
font = new Font(fontSize, TITLE_FONT_NAME);
this.titleFont_ = font;
}
fill = new SolidFill(theme.getTitleColor());
if (this.titleTop_) {
y = cy - Math.round(r * FACTOR_TITLE_OFFSET);
graphics.drawTextOnLine(
this.titleTop_, 0, y, this.width_, y, 'center', font, null, fill);
}
if (this.titleBottom_) {
y = cy + Math.round(r * FACTOR_TITLE_OFFSET);
graphics.drawTextOnLine(
this.titleBottom_, 0, y, this.width_, y, 'center', font, null,
fill);
}
}
// Draw tick marks
const majorTicks = this.majorTicks_;
const minorTicks = this.minorTicks_;
const rMajorTickInternal = r * FACTOR_MAJOR_TICKS;
const rMinorTickInternal = r * FACTOR_MINOR_TICKS;
const ticks = majorTicks * minorTicks;
const valueRange = this.maxValue_ - this.minValue_;
const tickValueSpan = valueRange / ticks;
const majorTicksPath = new Path();
const minorTicksPath = new Path();
const tickLabelFill = new SolidFill(theme.getTickLabelColor());
let tickLabelFont = this.tickLabelFont_;
if (!tickLabelFont) {
tickLabelFont = new Font(
Math.round(r * FACTOR_TICK_LABEL_FONT_SIZE), TITLE_FONT_NAME);
}
const tickLabelFontSize = tickLabelFont.size;
for (let i = 0; i <= ticks; i++) {
const angle = this.valueToAngle_(i * tickValueSpan + this.minValue_);
const isMajorTick = i % minorTicks == 0;
const rInternal = isMajorTick ? rMajorTickInternal : rMinorTickInternal;
const path = isMajorTick ? majorTicksPath : minorTicksPath;
x = cx + googMath.angleDx(angle, rInternal);
y = cy + googMath.angleDy(angle, rInternal);
path.moveTo(x, y);
x = cx + googMath.angleDx(angle, r);
y = cy + googMath.angleDy(angle, r);
path.lineTo(x, y);
// Draw the tick's label for major ticks
if (isMajorTick && this.majorTickLabels_) {
const tickIndex = Math.floor(i / minorTicks);
const label = this.majorTickLabels_[tickIndex];
if (label) {
x = cx + googMath.angleDx(angle, rInternal - tickLabelFontSize / 2);
y = cy + googMath.angleDy(angle, rInternal - tickLabelFontSize / 2);
let x1;
let x2;
let align = 'center';
if (angle > 280 || angle < 90) {
align = 'right';
x1 = 0;
x2 = x;
} else if (angle >= 90 && angle < 260) {
align = 'left';
x1 = x;
x2 = this.width_;
} else {
// Values around top (angle 260-280) are centered around point
const dw = Math.min(x, this.width_ - x); // Nearest side border
x1 = x - dw;
x2 = x + dw;
y += Math.round(tickLabelFontSize / 4); // Movea bit down
}
graphics.drawTextOnLine(
label, x1, y, x2, y, align, tickLabelFont, null, tickLabelFill);
}
}
}
stroke = theme.getMinorTickStroke();
graphics.drawPath(minorTicksPath, stroke, null);
stroke = theme.getMajorTickStroke();
graphics.drawPath(majorTicksPath, stroke, null);
// Draw the needle and the value label. Stop animation when doing
// full redraw and jump to the final value position.
this.stopAnimation_();
this.needleRadius_ = r;
this.drawValue_();
}
/**
* Handle animation events while the hand is moving.
* @param {!AnimationEvent} e The event.
* @private
*/
onAnimate_(e) {
this.needleValuePosition_ = e.x;
this.drawValue_();
}
/**
* Handle animation events when hand move is complete.
* @private
*/
onAnimateEnd_() {
this.stopAnimation_();
}
/**
* Stop the current animation, if it is active.
* @private
*/
stopAnimation_() {
if (this.animation_) {
googEvents.removeAll(this.animation_);
this.animation_.stop(false);
this.animation_ = null;
}
}
/**
* Convert a value to the position in the range. The returned position
* is a value between 0 and 1, where 0 indicates the lowest range value,
* 1 is the highest range, and any value in between is proportional
* to mapping the range to (0-1).
* If the value is not within the range, the returned value may be a bit
* lower than 0, or a bit higher than 1. This is done so that values out
* of range will be displayed just a bit outside of the gauge axis.
* @param {number} value The value to convert.
* @private
* @return {number} The range position.
*/
valueToRangePosition_(value) {
const valueRange = this.maxValue_ - this.minValue_;
let valuePct = (value - this.minValue_) / valueRange; // 0 to 1
// If value is out of range, trim it not to be too much out of range
valuePct = Math.max(valuePct, -MAX_EXCEED_POSITION_POSITION);
valuePct = Math.min(valuePct, 1 + MAX_EXCEED_POSITION_POSITION);
return valuePct;
}
/**
* Convert a value to an angle based on the value range and angle span
* @param {number} value The value.
* @return {number} The angle where this value is located on the round
* axis, based on the range and angle span.
* @private
*/
valueToAngle_(value) {
const valuePct = this.valueToRangePosition_(value);
return this.valuePositionToAngle_(valuePct);
}
/**
* Convert a value-position (percent in the range) to an angle based on
* the angle span. A value-position is a value that has been proportinally
* adjusted to a value betwwen 0-1, proportionaly to the range.
* @param {number} valuePct The value.
* @return {number} The angle where this value is located on the round
* axis, based on the range and angle span.
* @private
*/
valuePositionToAngle_(valuePct) {
const startAngle = googMath.standardAngle((360 - this.angleSpan_) / 2 + 90);
return this.angleSpan_ * valuePct + startAngle;
}
/**
* Draw the elements that depend on the current value (the needle and
* the formatted value). This function is called whenever a value is changed
* or when the entire gauge is redrawn.
* @private
*/
drawValue_() {
if (!this.isInDocument()) {
return;
}
const r = this.needleRadius_;
const graphics = this.graphics_;
const theme = this.theme_;
const cx = this.width_ / 2;
const cy = this.height_ / 2;
const angle = this.valuePositionToAngle_(
/** @type {number} */ (this.needleValuePosition_));
// Compute the needle path
const frontRadius = Math.round(r * FACTOR_NEEDLE_FRONT);
const backRadius = Math.round(r * FACTOR_NEEDLE_BACK);
const frontDx = googMath.angleDx(angle, frontRadius);
const frontDy = googMath.angleDy(angle, frontRadius);
const backDx = googMath.angleDx(angle, backRadius);
const backDy = googMath.angleDy(angle, backRadius);
const angleRight = googMath.standardAngle(angle + 90);
const distanceControlPointBase = r * FACTOR_NEEDLE_WIDTH;
const controlPointMidDx =
googMath.angleDx(angleRight, distanceControlPointBase);
const controlPointMidDy =
googMath.angleDy(angleRight, distanceControlPointBase);
const path = new Path();
path.moveTo(cx + frontDx, cy + frontDy);
path.curveTo(
cx + controlPointMidDx, cy + controlPointMidDy,
cx - backDx + (controlPointMidDx / 2),
cy - backDy + (controlPointMidDy / 2), cx - backDx, cy - backDy);
path.curveTo(
cx - backDx - (controlPointMidDx / 2),
cy - backDy - (controlPointMidDy / 2), cx - controlPointMidDx,
cy - controlPointMidDy, cx + frontDx, cy + frontDy);
// Draw the needle hinge
const rh = Math.round(r * FACTOR_NEEDLE_HINGE);
// Clean previous needle
let needleGroup = this.needleGroup_;
if (needleGroup) {
needleGroup.clear();
} else {
needleGroup = this.needleGroup_ = graphics.createGroup();
}
// Draw current formatted value if provided.
if (this.formattedValue_) {
let font = this.valueFont_;
if (!font) {
const fontSize = Math.round(r * FACTOR_VALUE_FONT_SIZE);
font = new Font(fontSize, TITLE_FONT_NAME);
font.bold = true;
this.valueFont_ = font;
}
let fill = new SolidFill(theme.getValueColor());
const y = cy + Math.round(r * FACTOR_VALUE_OFFSET);
graphics.drawTextOnLine(
this.formattedValue_, 0, y, this.width_, y, 'center', font, null,
fill, needleGroup);
}
// Draw the needle
let stroke = theme.getNeedleStroke();
let fill = theme.getNeedleFill(cx, cy, rh);
graphics.drawPath(path, stroke, fill, needleGroup);
stroke = theme.getHingeStroke();
fill = theme.getHingeFill(cx, cy, rh);
graphics.drawCircle(cx, cy, rh, stroke, fill, needleGroup);
}
/**
* Redraws the entire gauge.
* Should be called after theme colors have been changed.
*/
redraw() {
this.draw_();
}
/** @override */
enterDocument() {
super.enterDocument();
// set roles and states
const el = this.getElement();
asserts.assert(el, 'The DOM element for the gauge cannot be null.');
aria.setRole(el, 'progressbar');
aria.setState(el, 'live', 'polite');
aria.setState(el, 'valuemin', this.minValue_);
aria.setState(el, 'valuemax', this.maxValue_);
aria.setState(el, 'valuenow', this.value_);
this.draw_();
}
/** @override */
exitDocument() {
super.exitDocument();
this.stopAnimation_();
}
/** @override */
disposeInternal() {
this.stopAnimation_();
this.graphics_.dispose();
delete this.graphics_;
delete this.needleGroup_;
delete this.theme_;
delete this.rangeColors_;
super.disposeInternal();
}
}
exports = Gauge;
Codebase Browser
chromium