25 Using ADF Gauge Components

25.1.1 Types of Gauges

The following types of gauges are supported by the gauge component:

• Dial: Indicates its metric along a 220 degree arc. This is the default gauge type. Figure 25-2 shows a dial gauge indicating a Plasma HD TV stock level within an acceptable range.

  Figure 25-2 Dial Gauge with Thresholds

  
  

• Status Meter: Indicates the progress of a task or the level of some measurement along a rectangular bar. An inner rectangle shows the current level of a measurement against the ranges marked on an outer rectangle. Figure 25-3 shows the Plasma HD TV stock level using a status meter gauge.

  Figure 25-3 Status Meter Gauge with Thresholds

  
  

• Status Meter (vertical): Indicates the progress of a task or the level of some measurement along a vertical rectangular bar. Figure 25-4 shows the Plasma HD TV stock level using a vertical status meter gauge.

  Figure 25-4 Vertical Status Meter Gauge with Thresholds

  
  

• LED (light-emitting diode): Depicts graphically a measurement, such as key performance indicator (KPI). Several styles of graphics are available for LED gauges such as arrows that indicate good (up arrow), fair (left- or right-pointing arrow), or poor (down arrow). Figure 25-5 shows the Plasma HD TV stock level using a LED bulb indicator and Figure 25-6 shows the same stock level using a LED arrow.

  Figure 25-5 LED Bulb Gauge

  
  

  Figure 25-6 LED Arrow Gauge

  
  

25.1.2 Gauge Terminology

Gauge terms identify the many aspects of a gauge and gauge set that you can customize. The gauge component includes approximately 20 child tags that provide options for this customization.

The following list groups the various parts of a gauge that can be configured:

• Overall gauge customization: Each item in this group is represented by a gauge child tag:

  • Gauge Background: Controls border color and fill color for the background of a gauge.

  • Gauge Set Background: Controls border color and fill color for the background of a gauge set.

  • Gauge Frame: Refers to the frame behind the dial gauge.

  • Plot Area: Represents the area inside the gauge itself.

  • Indicator: Points to the value that is plotted in a dial gauge. It is typically in the form of a line or an arrow.

  • Indicator Bar: The inner rectangle in a status meter gauge.

  • Indicator Base: The circular base of a line or needle style indicator in a dial gauge.

  • Threshold Set: Specifies the threshold sections for the metrics of a gauge. You can create an infinite number of thresholds for a gauge.

• Data values: These include the metric (which is the actual value that the gauge is plotting), minimum value, maximum value, and threshold values. Section 25.2, "Understanding Data Requirements for Gauges" describes these values.

• Labels: The gauge supports the following elements with a separate child tag for each item:

  • Bottom Label: Refers to an optional label that appears below the gauge and is surrounded by the lower label frame.

  • Lower Label Frame: Controls the colors for the background and border of the frame that contains the bottom label. The metric label can also appear inside the lower label frame, to the right of the bottom label.

  • Metric Label: Shows the value of the metric that the gauge is plotting in text.

  • Tick Labels: Displays text that is displayed to identify tick marks on a gauge.

  • Tick Marks: Refers to the markings along the value axis of the gauge. These can identify regular intervals, from minimum value to maximum value, and can also indicate threshold values.

  • Top Label: Refers to the label that appears at the top of a gauge. By default a title separator is used with a label above the gauge.

  • Upper Label Frame: Refers to the background and border of the frame that encloses the top label. You can specify border color and fill color for this frame. Turn off the default title separator when using this frame.

• Legend: The gauge supports the gauge legend area, text, and title elements with a separate child tag for each item.

• Shape Attributes Set: The gauge supports interactivity properties for its child elements. For example, the alt text of a gauge plot area can be displayed as a tooltip when the mouse hovers over that element.

25.3.1 Creating a Gauge Using Tabular Data

The process of creating a gauge from tabular data includes the following steps:

• Storing the data in a method in the gauge's managed bean.

• Creating a gauge that uses the data stored in the managed bean.

25.3.1.2 Structure of the List of Tabular Data

The list that contains the tabular data consists of a three-member Object array for each data value to be passed to the gauge. The members of each array must be organized as follows:

• The first member (index 0) is the column label, in the grid, of the data value. This is generally a String.

• The second member (index 1) is the row label, in the grid, of the data value. This is generally a String.

• The third member (index 2) is the data value, which is usually Double.

Figure 25-8 has five columns: Quota, Sales, Margin, Costs, and Units. The example has three rows: London, Paris, and New York. This data produces a gauge set with five gauges in each row and lets you compare values such as sales across the three cities.

Figure 25-8 Comparison of Annual Results

Example 25-2 shows code that creates the list of tabular data required for the gauge that compares annual results for three cities.

Example 25-2 Code to Create a List of Tabular Data for a Gauge

public List getGaugeData() 
{
    ArrayList list = new ArrayList();
    String[] rowLabels  = new String[] {"London", "Paris", "New York"};
    String[] colLabels  = new String[] {"Quota", "Sales", "Margin", "Costs", "Units"};
    double [] [] values = new double[][]{
        {60, 90, 135},
        {50, -100, -150},
        {130, 140, 150},
        {70, 80, -130},
        {110, 120, 130}
        };
    for (int c = 0; c < colLabels.length; c++)
    {
     for (int r = 0; r < rowLabels.length; r++)
       {
        list.add (new Object [] {colLabels[c], rowLabels[r], 
            new Double (values [c][r])});
       }
    }
    return list;
}

25.3.2 How to Create a Gauge Using Tabular Data

Use the tabularData attribute of the gauge tag to reference the tabular data that is stored in a managed bean.

To create a gauge that uses tabular data from a managed bean:

1. From the Component Palette, drag the dvt:gauge tag to a page.

2. In the Component Gallery, select the category, type, and quick-start layout style for the gauge that you are creating.

3. In the Gauge Data category of the Property Inspector, click the tabularData attribute dropdown icon and select Expression Builder.

4. In the Expression Builder dialog, use the search box to locate the managed bean.

5. Expand the managed bean node and select the method that creates the list of tabular data.

6. Click OK. The Expression is created.

   If the name of the managed bean is sampleGauge and the name of the method that creates the list of tabular data is getGaugeData, the Expression Builder generates the code #{sampleGauge.gaugeData} as the value for the tabularData attribute of the dvt:gauge tag.

25.3.3 What Happens When You Create a Gauge Using Tabular Data

When you create a gauge tag that is powered by data obtained from a list referenced in the tabularData attribute, the following results occur:

• A gauge is generated with a setting in its tabularData attribute. The settings for all other attributes for this gauge are provided by default.

• You have the option of changing the setting of the gaugeType attribute in the Property Inspector to DIAL, LED, STATUSMETER, or VERTICALSTATUSMETER.

25.4.1 Changing the Type of the Gauge

You can change the type of a gauge using the gaugeType attribute of the dvt:gauge tag. The acceptable values are DIAL, LED, STATUSMETER, or VERTICALSTATUSMETER. The gauge type is reflected in the visual editor default gauge.

25.4.2 Determining the Layout of Gauges in a Gauge Set

A single gauge can display one row of data bound to a gauge component. A gauge set displays a gauge for each row in multiple rows of data in a data collection.

You can specify the location of gauges within a gauge set by specifying values for attributes in the dvt:gauge tag.

To specify the layout of gauges in a gauge set:

1. In the Structure window, right-click the dvt:gauge node and select Go to Properties.

2. In the Property Inspector, select the Common attributes category.

3. To determine the number of columns of gauges that will appear in a gauge set, specify a value for the gaugeSetColumnCount attribute.

   A setting of zero causes all gauges to appear in a single row. Any positive integer determines the exact number of columns in which the gauges are displayed. A setting of -1 causes the number of columns to be determined automatically from the data source.

4. To determine the placement of gauges in columns, specify a value for the gaugeSetDirection attribute.

   If you select GSD_ACROSS, then the default layout of the gauges is used and the gauges appear from left to right, then top to bottom. If you select GSD_DOWN, the layout of the gauges is from top to bottom, then left to right

5. To control the alignment of gauges within a gauge set, specify a value for the gaugeSetAlignment attribute.

   This attribute defaults to the setting GSA_NONE, which divides the available space equally among the gauges in the gauge set. Other options use the available space and optimal gauge size to allow for alignment towards the left or right and the top or bottom within the gauge set. You can also select GSA_CENTER to center the gauges within the gauge set.

25.4.3 Changing Gauge Size and Style

You can customize the width and height of a gauge and you can allow for dynamic resizing of a gauge based on changes to the size of its container. You can also control the style sheet used by a gauge. These two aspects of a gauge are interrelated in that they share the use of the gauge inlineStyle attribute.

25.4.4 Adding Thresholds to Gauges

Thresholds are data values in a gauge that highlight a particular range of values. Thresholds must be values between the minimum and the maximum value for a gauge. The range identified by a threshold is filled with a color that is different from the color of other ranges.

The data collection for a gauge can provide dynamic values for thresholds when the gauge is databound. After the gauge is created, you can also insert a dvt:thresholdSet tag and individual dvt:threshold tags to create static thresholds. If threshold values are supplied in both the data collection and in threshold tags, then the gauge honors the values in the threshold tags.

25.4.5 Formatting Numbers in Gauges

For gauges, the dvt:metricLabel, dvt:tickLabel, and dvt:legendText tags may require numeric formatting.

<dvt:gauge> 
  <dvt:metricLabel position="LP_BELOW_GAUGE" numberType="NT_PERCENT">
    <dvt:numberFormat posNumFmt="POS_NUMFMT_NUM_POS"/>
  </dvt:metricLabel>
</dvt:gauge> 

25.4.6 Formatting Text in Gauges

You can format text in any of the following tags that represent subcomponents of a gauge:

• dvt:bottomLabel

• dvt:gaugeMetricLabel

• dvt:gaugeLegendText

• dvt:gaugeLegendTitle

• dvt:tickLabel

• dvt:topLabel

<dvt:gauge> 
  <dvt:metricLabel>
     <dvt:gaugeFont name="Tahoma" size="11" color="#3C3C3C" bold="true"/>
  </dvt:metricLabel>
</dvt:gauge> 

25.4.7 Specifying an N-Degree Dial

You can specify a gauge that sweeps through angles other than the standard 220-degree arc in a dial gauge. Set the angleExtent attribute to specify the range of degrees in the gauge.

For example, to create a 270 degree dial gauge, set the angleExtent attribute as follows: <dvt:gauge angleExtent="270"/>.

25.4.8 Customizing Gauge Labels

You can control the positioning of gauge labels. You can also control the colors and borders of the gauge label frames.

25.4.9 Customizing Indicators and Tick Marks

There are a variety of options available for customizing the indicators of gauges and the location and labeling of tick marks.

25.5.1 Using Gradient Special Effects in a Gauge

A gradient is a special effect in which an object changes color gradually. Each color in a gradient is represented by a stop. The first stop is stop 0, the second is stop 1, and so on. You must specify the number of stops in the special effects for a subcomponent of a gauge that supports special effects.

You can define gradient special effects for the following subcomponents of a gauge:

• Gauge background: Uses the dvt:gaugeBackground tag.

• Gauge set background: Uses the dvt:gaugeSetBackground tag.

• Gauge plot area: Uses the dvt:gaugePlotArea tag.

• Gauge frame: Uses the dvt:gaugeFrame tag.

• Gauge legend area: Uses the dvt:gaugeLegendArea tag.

• Lower label frame: Uses the dvt:lowerLabelFrame tag.

• Upper label frame: Uses the dvt:upperLabelFrame tag.

• Indicator: Uses the dvt:indicator tag.

• Indicator bar: Uses the dvt:indicatorBar tag.

• Indicator base: Uses the dvt:indicatorBase tag.

• Threshold: Uses the dvt:threshold tag.

The approach that you use to define gradient special effects is identical for each part of the gauge that supports these effects.

<dvt:gauge >
  <dvt:gaugeBackground borderColor="#848284">
    <dvt:specialEffects fillType="FT_GRADIENT" gradientDirection="GD_RADIAL">
      <dvt:gradientStopStyle stopIndex="0" gradientStopPosition="60"
           gradientStopColor="FFFFCC"/>
      <dvt:gradientStopStyle stopIndex="1" gradientStopPosition="90"
           gradientStopColor="FFFF99"/>
    </dvt:specialEffects> 
  </dvt:gaugeBackground>
</dvt:gauge>

25.5.2 Animating Gauges

You can animate gauges (not gauge sets) to show changes in data, for example, a dial gauge indicator can change color when a data value increases or decreases. Figure 25-9 shows a dial gauge with the dial indicator animated to display the data change at each threshold level.

Figure 25-9 Animated Dial Gauge

The attributes for setting animation effects on gauges include:

• animationOnDisplay: Use to specify the type of initial rendering effect to apply. Valid values are:

  • NONE (default): Do not show any initial rendering effect.

  • AUTO: Apply an initial rendering effect automatically chosen based on graph or gauge type.

• animationOnDataChange: Use to specify the type of data change animation to apply. Valid values are:

  • NONE: Apply no data change animation effects.

  • AUTO (default): Apply Active Data Service (ADS) data change animation events. For more information about ADS see Section 25.5.3.

  • ON: Apply partial page refresh (PPR) data change animation events.

• animationUpColor: Use to specify the RGB hexadecimal color used to indicate that a data value has increased.

• animationDownColor: Use to specify the RGB hexadecimal color used to indicate that a data value has decreased.

25.5.3 Animating Gauges with Active Data

Animation effects using Active Data Service (ADS) can be added to dial and status meter gauge types. ADS allows you to bind ADF Faces components to an active data source using the ADF model layer. To allow this, you must configure the components and the bindings so that the components can display the data as it is updated in the data source.

In order to use the Active Data Service, you must have a data source that publishes events when data is changed, and you must create business services that react to those events and the associated data controls to represent those services. For more information about ADS and configuring your application, see the "Using the Active Data Service" chapter in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

25.6.1 Creating a Custom Shapes Graphic File

Due to the requirements for rotating and resizing a gauge's components, such as the plot area or tick marks, a vector graphics file is required when creating a custom shapes graphic file. Scalable Vector Graphics (SVG) is the supported file format for creating custom shapes for gauges.

After designing the gauge and exporting to an SVG file, additional information is added to identify, scale, and position the gauge shapes and components, and to specify other metadata used in processing.

In the SVG file, gauge components are identified using an ID. For example, an SVG file with <polygon id="indicator"/> would be interpreted as using a polygon shape for the indicator component. To specify multiple shapes to create the desired visual for a component, the ID can be modified as in id="indicator_0", id="indicator_1", and id="indicator_2".

Table 25-1 shows the gauge components IDs and their descriptions.

Table 25-2 shows the metadata IDs and descriptions used for internal calculations, not rendered in the gauge.

Example 25-6 shows a sample SVG file used to specify custom shapes for the components of a gauge.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg xmlns:svg="http://www.w3.org/2000/svg"
   xmlns="http://www.w3.org/2000/svg"
   version="1.0">
 
    <rect width="264.72726" height="179.18887" rx="8.2879562" 
       ry="10.368411" x="152.76225" y="202.13995" 
       style="fill:#c83737;fill-opacity:1;stroke:none"
       id="gaugeFrame"/>
    <rect width="263.09058" height="42.581127" rx="3.0565372"
       ry="3.414634" x="155.11697" y="392.35468"
       fill="#c83737"
       id="lowerLabelFrame" />
    <rect width="241.79999" height="120.13961"
       x="164.2415" y="215.94714"
       style="fill:#ffeeaa"
       id="plotAreaBounds"/>
    <rect width="74.516975" height="44.101883"
       rx="2.6630435" ry="3.5365853"
       x="247.883" y="325.4415"
       style="fill:#ffd5d5;fill-opacity:1;stroke:none"
       id="indicatorBase"/>
    <rect width="6.0830183" height="98.849045" rx="2.6630435"
       ry="2.2987804" x="282.86035" y="237.23772"
       style="fill:#00aa00;fill-opacity:1;stroke:none"
       id="indicator"/>
</svg>

25.6.2 How to Use a Custom Shapes File

After creating the SVG file to be used to specify the custom shapes for your gauge, set the customShapesPath attribute to point to the file.

To specify a custom shapes file:

1. In the Structure window, right-click the dvt:gauge node and select Go to Properties.

2. In the Appearance attributes category of the Property Inspector, for the CustomShapesPath attribute, enter the path to the custom shapes file. For example, customShapesPath="/path/customShapesFile.svg".

25.6.3 What You May Need to Know About Supported SVG Features

The custom shapes available to you support the following SVG features:

• Transformations

• Paths

• Basic shapes

• Fill and stroke painting

• Linear and radial gradients

SVG features that are not supported by custom shapes in JDeveloper include:

• Unit Identifiers: All coordinates and lengths should be specified without the unit identifiers, and are assumed to be in pixels. The parser does not support unit identifiers, because the size of certain units can vary based on the display used. For example, an inch may correspond to different numbers of pixels on different displays. The only exceptions to this are gradient coordinates, which can be specified as percentages.

• Text: All text on the gauge is considered data, and should be specified through the tags or data binding.

• Specifying Paint: The supported options are none, 6-digit hexadecimal, and a <uri> reference to a gradient.

• Fill Properties: The fill-rule attribute is not supported.

• Stroke Properties: The stroke-linecap, stroke-linejoin, stroke-miterlimit, stroke-disarray, and stroke-opacity attributes are not supported.

• Linear Gradients and Radial Gradients: The gradientUnits, gradientTransform, spreadMethod, and xlink:href are not supported. Additionally, the r, fx, and fy attributes on the radial gradient are not supported.

• Elliptical Arc Out-of-Range Parameters: If rx, ry, and x-axis-rot are too small such that there is no solution, the ellipse should be scaled uniformly until there is exactly one solution. The SVG parser will not support this.

• General Error Conditions: The SVG input is expected to be well formed and without errors. The SVG parser will not perform any error checking or error recovery for incorrectly formed files, and it will stop parsing when it encounters an error in the file.

25.6.4 How to Set Custom Shapes Styles

In addition to the ability to specify custom shapes for gauges, there are a set of prebuilt custom shapes styles for use with the gauge components. The available styles are:

• Beveled circle

• Full circle

• Rounded rectangle

Figure 25-10 shows a dial gauge displayed with each of the custom shapes styles applied.

Figure 25-10 Dial Gauges with Custom Shapes Styles

To apply a custom shapes style to a gauge:

1. In the Structure window, right-click the dvt:gauge node and select Go to Properties.

2. In the Appearance attributes category of the Property Inspector, select the custom shapes style from the CustomShapesPath attribute dropdown list.