References for IBM® Gauge widgets


_Gauge super class

This object is the super class for the analog gauge and bar graph widgets. This object provides all of the common functionality between those two widgets, which includes drawing the base surface, handling most mouse events, and so on. The following common variables and functions are available:

Object variables
Number gaugeWidth The width of the surface to create on the page. Expressed in pixels.
Number gaugeHeight The height of the surface to create on the page. Expressed in pixels.
String|Object gaugeBackground The color to apply to the background of the gauge. Typically, a CSS style color such as #e0e0e0. Use this color for the fill object. See the example.
Number gaugeMin The minimum value to be displayed on the gauge.
Number gaugeMax The maximum value to be displayed on the gauge.
String image A URL to use as the background for the gauge.
Number imageX The x position to place the image. The default value is 0, which specifies the lower-left corner position.
Number imageY The y position to place the image. The default value is 0, which specifies the lower-left corner position.
Number imageWidth The width of the previously indicated image. If an image is used, then you must specify this value for the image to be displayed.
Number imageHeight The height of the previously indicated image. If an image is used, then you must specify this value for the image to be displayed.
Boolean imageOverlay Whether the previously mentioned image is an overlay, rather than a background.
Number useRangeStyles Whether to use CSS styles to indicate the range colors.
Boolean hideValues Whether to hide the text boxes beneath the gauge and show the value of the indicators.

gaugeBackground

Declaratively, in markup, this variable can only be set as a string, which is typically a CSS style color string, such as gray or #e0e0e0. However, in JavaScriptTM, the gaugeBackground variable can be set to a fill object, fulfilling the dojox.gfx fill object definition. The linear fill object expects the following conditions:

{
type: "linear", 
x1: 0, // x-position to start the first color
y1: 0, // y-position to start the first color
x2: 100, // x-position to end the second color
y2: 100, // x-position to end the second color
colors: [{offset: 0, color: "black"}, // the first color
	 {offset: 1, color: "white"}] // the second color
}
To set a gray-to-white gradient, going from the end of a gauge to the beginning, you might enter the following code:
var gauge = dijit.byId("testGauge");
var fill = new Object();
fill.type = "linear";
fill.x1 = 0;
fill.x2 = 0;
fill.y2 = 0;
fill.y1 = gauge.gaugeHeight;
fill.colors = [{offset: 0, color: "#ECECEC"}, {offset: 1, color: "white"}];
gauge.gaugeBackground = fill;


useRangeStyles

This variable default value is 0, indicating that built-in range colors are used. However, if set to a number greater than 0, then that number of CSS classes, ibmGaugeRange1, ibmGaugeRange2, and so on, are used to style the ranges. This feature does not work in Internet Explorer. The CSS class has properties such as the following example:

.ibmGaugeRange1 {
	fill: #808080 ;
	stroke: #808080 ;
}
As shown, these are Scalable Vector Graphics (SVG) styles, not HTML styles. Attributes such as background-color have no effect.


hideValues

By default, the hideValues variable is set to false, meaning that for each indicator added to the gauge, a text box beneath the gauge surface is displayed that shows the value of that indicator as a text value. This feature is for accessibility purposes, and setting this variable to true makes this gauge *inaccessible*. This is an important consideration to make, as some readers might not be able to access the value of the gauges, if these text boxes are disabled.


Object functions
void addRange(Object range)
Adds a range to this gauge widget.
void addRanges(Array ranges)
Adds a collection of range objects to this gauge.
void moveIndicatorToFront(Object indicator)
Moves the given indicator to the beginning of the gauge.
void drawText(String txt, Number x, Number y, String align, String vAlign)
Draws text onto the gauge.
void removeText(String t)
Removes the given text from the gauge.
void updateTooltip(String text)
Updates the hover help for the gauge with the given text.
void handleMouseOver(Object event)
Mouse support.
void handleMouseOut(Object event)
Mouse support.
void handleMouseDown(Object event)
Mouse support.
void handleMouseUp(Object event)
Mouse support.
void handleMouseMove(Object event)
Mouse support.

Function details
addRange

addRanges

moveIndicatorToFront

drawText

removeText

updateTooltip

handleMouseOver

handleMouseOut

handleMouseDown

handleMouseUp

handleMouseMove

The following widgets (Range, Gradient, GradientColor, and Indicator) are used primarily to create a gauge declaratively, in markup, or instead of using an anonymous object for the other gauge functions.

Range Widget
Object variables
Number low The low or minimum value of this range.
Number high The high or maximum value of this range.
String hover The text to put in the hover help when this range is moused over.
String|Object color The color of this range. Might also be a ibm_gauge.widget.Gradient object.
Number size For a circular gauge, such as AnalogGauge, this value indicates the size of the arc.

Gradient Widget
Object variables
String type The type of gradient. See dojox.gfx.* to see available types.
Number x1 The x coordinate of where the first color is used most.
Number x2 The x coordinate of where the second color is used most.
Number y1 The y coordinate of where the first color is used most.
Number y2 The y coordinate of where the second color is used most.
Array colors The two colors to use for this gradient. These colors are typically either a ibm_gauge.widget.GradientColor object or an anonymous object with comparable properties.

Object functions
Object getFillObject()
Gets this widget as an anonymous fill object.

Function details
getFillObject

Gradient color widget
Object variables
Number offset The offset of this color, which is either 0 or 1.
String color The color to use. Typically a CSS style color, such as white or #000000.

Object functions
Object getColorObject()
Gets this widget as an anonymous color object.

Function details
getcolorObject

Indicator widget
Object variables
Number value The value on the gauge that this indicator represents.
String type The type of indicator. Possible examples include line, arrow, and bar. Possible values depend on the type of gauge.
String color The color of this indicator. Generally a CSS style color.
String label The label for this indicator.
Number length The length of the indicator.
Number width The width or thickness of the indicator.
Number offset The offset of the indicator.
String hover The text to enter in the hover help when this indicator moused over.
String|Function onDragMove The function to call when the indicator is moved with a drag action. This value can be either a function name or the function, itself.

Analog gauge widget

The analog gauge widget provides a graphical, circular gauge for indicating numerical values, much like a speedometer or a pressure gauge. This gauge can have any starting and ending angle values, providing gauges in any number of circle-based shapes, including full circles, semicircles, and arcs. The analog gauge extends the _Gauge superclass, inheriting all of its variables, properties, and functions.

Object variables
Number gaugeWidth Overrides the _Gauge property of the same name. This variable indicates the width of the gauge and sets the default to 300 pixels.
Number gaugeHeight Overrides the _Gauge property of the same name. This variable indicates the height of the gauge and sets the default to 200 pixels.
Number cx The x coordinate of the center of the gauge, within the prescribed surface area. Default is gaugeWidth/2.
Number cy The y coordinate of the center of the gauge, within the prescribed surface area. Default is gaugeHeight/2.
Number radius The radius of the gauge. Default is the lower value between the cx-25 and cy-25 values.
Number startAngle Indicates the angle, in degrees, where the gauge starts. Default is -90.
Number endAngle Indicates the angle, in degrees, where the gauge ends. Default is -90.

Object functions
void addIndicator(Object indicator)
Adds the given indicator to this gauge.
Number getAngle(Number value)
Given a numerical value indicated on the gauge, gets the angle that corresponds with that value.
Number getValueForAngle(Number angle)
Given an angle, gets the value to which the angle corresponds.
Number getRadians(Number angle)
Converts from degrees to radians.
Number getDegrees(Number radians)
Converts from radians to degrees.
void draw()
Draws or redraw the gauge.
void drawRange(Object range)
Draws the given range on this gauge.
void drawIndicator(Object indicator)
Draws the given indicator on this gauge.
void moveIndicator(Object indicator)
Moves the given indicator on this gauge.
Object getRangeUnderMouse(Object event)
Determines the range currently where the mouse cursor hovers.

Function details
addIndicator

getAngle

getValueForAngle

getRadians

getDegrees

draw

drawRange

drawIndicator

moveIndicator

getRangeUnderMouse

Bar graph widget

The bar graph widget provides a graphical view to numerical data in the form of a single column horizontal bar graph. The bar graph can have any number of horizontal bars on the same column, target indicators, and tick marks. The bar graph widget extends the _Gauge superclass, inheriting all of its variables, properties and functions.

Object variables
Number gaugeWidth Overrides the _Gauge property of the same name. This variable indicates the width of the gauge and sets the default to 250 pixels.
Number gaugeHeight Overrides the _Gauge's property of the same name. This variable indicates the height of the gauge and sets the default to 35 pixels.
Number dataX The x coordinate, in pixels, where the data area starts. The default is 5.
Number dataY The y coordinate of where the data area should start, in pixels. The default is 5.
Number dataWidth Width, in pixels, of the data area. Default is gaugeWidth-10.
Number dataHeight Height, in pixels, of the data area. Default is gaugeHeight-10.

Object functions
void addIndicator(Object indicator)
Adds the given indicator to this bar graph.
Number getPosition(Number value)
Gets the coordinate position that represents a given value.
Number getValueForPosition(Number position)
Gets the value for the given coordinate position.
void draw()
Draws or redraws the bar graph.
void drawRange(Object range)
Draws the given range on this bar graph.
void drawIndicator(Object indicator)
Draws the given indicator on this bar graph.
void moveIndicator(Object indicator)
Moves the given indicator on this bar graph.
void resizeIndicator(Object indicator)
Resizes the given indicator on this bar graph.
Object getRangeUnderMouse(Object event)
Determines the range where the mouse cursor hovers.

Function details
addIndicator

getPosition

getValueForPosition

draw

drawRange

drawIndicator

moveIndicator

resizeIndicator

getRangeUnderMouse