Scales

As discussed in the Overview topic, the scales are the most important component of a gauge. The scales display ticks and labels, they arrange pointers and also maintain ranges and other auxiliary elements. There are two types of scales – oval and linear. The oval scale distributes its elements in a circle, the linear scale distributes its element on a vertical or horizontal axis depending on its orientation. The oval and linear scales are represented by the OvalScale and LinearScale classes respectively. These classes share a common base class – BaseScale and apart from the difference in their layout logic they are very similar.

Customization

Geometry

The scales display a geometry according to its type. The elements displayed in the scale are aligned and arranged relative to the scale geometry. The geometry is either circular, for oval scale, or trapezoidal, for linear scales. The following figures show the geometries of oval and horizontal and vertical linear scales.

Oval	Horizontal Linear	Vertical Linear

The scale geometry can be customized through various properties. The fill and stroke of the geometry are defined by the Fill and Stroke properties. The start and end width are specified through the StartWidth and EndWidth properties. These properties are of type Length and can express relative values. See the Metrics section at the end of this topic for additional information regarding this. The start and end angles of the oval geometry can be specified through the StartAngle and EndAngle properties of the OvalScale class respectively. Both properties are expressed in degrees.

Data

The MinValue and MaxValue properties can be used to define the range of values displayed on the scale. The distribution of the values along the scale geometry is determined by the FunctionType property and can be Linear, Logarithmic or Custom. The base of the logarithmic distribution is specified through the LogarithmBase property. The custom value distribution function is supplied through the CustomFunction and ReversedCustomFunction properties.

Custom Painting

The appearance of the scale can be further customized by handling one of the PrepaintScale and PaintScale events. The former is raised before the default scale rendering, the latter is raised afterwards. The following code demonstrates a sample PaintScale event handler which draws a star on top of the scale:

Java

public void paintScale(CustomPaintEvent e)
{
    PathFigure path = new PathFigure("M0.5,0.02 L0.62,0.36 L0.98,0.36 L0.7,0.58 L0.8,0.92 L0.5,0.72 L0.2,0.92 L0.3,0.58 L0.02,0.36 L0.38,0.36 L0.5,0.02");
    path.setStroke(new Pen(Colors.Black));
    path.setFill(Brushes.Lime);    double height = e.getElement().getActualHeight();
    double width = e.getElement().getActualWidth();
    
    double shapeSize = 3.2;
    path.setMargin(new Margins(width / 2 - shapeSize / 2,
      height/4, width / 2 - shapeSize / 2, height / 4 - shapeSize));
    
    e.paintVisualElement(path, new XDimension2D.Double(width, height));
}

The above method will render a scale similar to the one below:

Scale Elements

Various elements can be added to a scale, including ticks, labels and pointers.

Ticks and Labels

The ticks and labels represent cornerstones along the scale, usually round values. The ticks and labels are created and added to the scales implicitly according to the specified settings. There are three categories of ticks and labels – major, middle and minor. Each category has corresponding settings, exposed respectively by the MajorTickSettings, MiddleTickSettings and MinorTickSettings properties of the BaseScale class. These settings provide properties for specifying the number of ticks along the scale, their alignment and appearance, the format of their associated label, and more. For additional information about ticks and labels refer to the Ticks and Labels topic.

Pointers

The pointers represent needles or similar types of indicators within the scale. They are used to visualize a current measurement within the scale. For example, in a car speedometer the pointers are used to indicate the current speed. Pointers can be added to the scale through the Pointers property. Pointers expose numerous properties that can be used to customize their appearance. For additional information check the Pointers topic.

Ranges

The ranges emphasize portions of the scale which represent particular interest. An example of a range is the red zone of a car cyclometer. Ranges are added to the scale through the Ranges property. For extensive information on how to use and setup ranges, refer to the Ranges topic.

Interaction

Users can interactively adjust the value of the pointers in the scale by clicking anywhere within the scale bounds. Interactivity only applies to pointers with IsInteractive property set to true. When the value of a pointer is changed interactively, the ValueChanged of the pointer is raised.

Metrics

The sizes of various scale elements can be specified either relatively to the size of the scale or as absolute values. This applies to all properties of type Length. The following example defines a pointer with relative width and height:

Java

Pointer pointer = new Pointer();
pointer.setPointerWidth(new Length(100, LengthType.Relative));
pointer.setPointerHeight(new Length(50, LengthType.Relative));

Relative sizes are calculated differently depending on the type of scale. In oval scales relative sizes are calculated based on the radius of the scale. Therefore the above pointer will extend from the center to the outer edge of the scale. In linear scales sizes are based on the width or height of the scale depending on the scale orientation.