<dvt:gauge>

dvt:gauge gauge gauge

UIComponent class: oracle.adf.view.faces.bi.component.gauge.UIGauge
Component type: oracle.dss.adf.gauge.Gauge

Overview

Use the gauge tag to create an ADF gauge. The attributes on this tag are sufficient to produce a gauge but you can also specify custom settings for many components by including any of the gauge child tags.

The Gauge is a measuring instrument for indicating a quantity such as temperature, pressure, speed etc. It shows a metric value and threshold ranges using graphical representation. Inside a Gauge, there is an Indicator. The Indicator represents the metric value of the Gauge. A single Gauge shows a single metric value. If a grid of values is applied to the Gauge, the Gauge becomes a Gauge set that contains multiple Gauges and each of them represents a value in the grid.

There are four types of Gauges: Dial Gauge, Status Meter, Vertical Status Meter and LED Gauge. All Gauges consist of five major parts: Top Label, Bottom Label, Metric Label, Plot Area and Legend Area with an exception that LED Gauge does not have a Plot Area. Some other parts of the Gauge like Indicator, Tick Labels, Tick Mark and Gauge Frame may be inside the Plot Area as well.

Data Model

Single Value - The simplest data model for a Gauge is a single metric value, which can be specified by the value attribute. In addition, the threshold, minimum and maximum values can also be specified by Threshold tag, and the minValue and maxValue attributes respectively. The following JSPX xml generates a single Gauge.

        <dvt:gauge value = "10" minValue = "0" maxValue = "100">
           <dvt:thresholdSet>
              <dvt:threshold thresholdMaxValue = "30"/>
              <dvt:threshold thresholdMaxValue = "60"/>
              <dvt:threshold/>
           </dvt:thresholdSet>
        </dvt:gauge>
        

Data Grid - Alternatively, the data binding dialogs can be used to bind the Gauge to a data control, which is typically based on a rowset. Another common way to provide data for the Gauge is to use the tabularData attribute to create a grid of data. This requires use of a backing or managed bean.

If a grid of values is specified, the Gauge becomes a Gauge set. Each Gauge in the Gauge set represents a value in the grid. The number of Gauges depends on the number of rows and columns in the grid by default. Users may customize the number of column in the Gauge set by using gaugeSetColumnCount attribute.

Data Specification - A Data Specification can be used to specify columns or rows of data to be used as the metric value, and threshold, minimum and maximum values. The following example shows how to use a Data Specification for a set of tabular data. This tabular data contains 5 columns and 2 rows. If Data Specification is not used, the following table will generate 10 Gauges that there will be a gauge for each value. Each column has its desired data specification as shown. Sales is assigned to be metric value, Quota is assigned to be the first threshold, etc. This will generate 2 Gauges, one for Boston and one for Chicago, both with metric, minimum, maximum and threshold values specified.

    CommonGauge gauge = new CommonGauge();
    Object[] specs = { DataSpecification.METRIC, DataSpecification.MINIMUM, DataSpecification.MAXIMUM, DataSpecification.THRESHOLD, DataSpecification.THRESHOLD }; 
    String[] colLabels = new String[] { "Sales", "Min", "Max", "Quota", "Target" };
    String[] rowLabels = new String[] { "Boston", "Chicago" };
    double[][] values = new double[][] { {40, 60}, {0,0}, {100,80}, {30,35}, {50,70} };
    List gaugeData = new ArrayList();
    for (int c = 0; c < colLabels.length; c++) {
       for (int r = 0; r < rowLabels.length; r++) {
          gaugeData.add(new Object[] { colLabels[c], rowLabels[r], new Double(values[c][r]) });
       }
    }
    gauge.setTabularData(specs, gaugeData);

       

Plot Area and Gauge Frame

The Plot Area contains a graphical representation of the metric value for the Gauge. Different gauge types have different plot areas. Indicator, Thresholds and Tick Marks are generally inside the Plot Area.

The Gauge Frame is a decorative frame that encloses the whole plot area on Dial Gauges. Users may choose the fill color and the border color of the Gauge Frame.

The Plot Area appears differently in different types of gauge.

The Dial Gauge Plot Area consists of a dial and a needle. It looks like a speedometer. The dial has tick marks showing the values at specific angles. Users may change the angular extent of the dial using the angleExtent attribute.

The Vertical Status Meter and Status Meter are meters with a rectangular indicator placed in a bounding box. It looks like a mercury barometer. The bounding box has tick marks showing the values at certain locations within the box.

The LED Gauge does not have a Plot Area. See the Indicator section below for details on LED Gauge.

Indicator

The Indicator shows the metric value of the Gauge. There are three types of indicators for Dial Gauges: Line, Needle and Fill. Line and Needle are rotating pointers to show the metric value by pointing to certain angle on the dial. The Needle indicator is thicker than the Line indicator. Fill is a slice or section of the dial that fills from the minimum value up to the metric value. Users may specify the indicator fill color and border color.

In a Status Meter, the indicator is rectangular. Its length is proportional to the metric value. Use the <dvt:indicatorBar> tag to specify the fill color and border color of the indicator.

The LED Gauge indicates its value mainly by its color. It changes its color to match the threshold range into which the metric value falls. Therefore, one or more thresholds must be present for LED Gauges. Users may change the style of the LED by attribute ledStyle. The shape of the LED gauge can be changed to circular (LS_DOT), an arrow shape (LS_ARROW), triangular (LS_TRIANGLE), or customizable shape (LS_CUSTOM).

In order to make the customizable shape is functional, both ledStyleCallback attribute and its callback class have to be implemented. The callback class extends the LedStyleCallback class, which users need to implement the getLEDImage method to return the desired image for every threshold range. See the JavaDoc for the LedStyleCallback class for more information.

Thresholds

A Threshold represents a significant value range like quota, target or limit value etc. When the indicator falls into one of the threshold ranges, it means certain criteria have been met or not. Different threshold ranges in gauges may have different colors, which you may customize.

Specify the threshold ranges by using <dvt:thresholdSet> tag and <dvt:threshold> tag. The thresholdMaxValue attribute is used to indicate the breakpoint of the ranges. For examples, if thresholdMaxValue of two threshold tags are specified, there will be three threshold ranges, starting from minimum value to first thresholdMaxValue, first thresholdMaxValue to second thresholdMaxValue and second thresholdMaxValue to maximum value. The threshold ranges can also be specified through the data bindings.

A Gauge Legend can be added to show the colors, ranges and descriptions of the Thresholds.

The style of threshold representation can be changed for Dial Gauges. Threshold colors can fill the entire plot area, form a solid or segmented ring around the Plot Area.

Tick Marks and Tick Labels

Dial Gauges and Status Meters have Tick Marks and Tick Labels to show the incremental, minimum and maximum values for a specific rotational angle or a location on the Plot Area. Users may specify where the tick marks occur within a Gauge, such as increments, minimum, maximum, metric, threshold values etc. If increment is specified, user may decide the number of ticks to be displayed in a gauge. Tick Labels may show actual value or percentage value. The Tick Labels can be positioned inside or outside of the Plot Area.

Labels

There are three labels in a gauge: Top Label, Bottom Label and Metric Label.

The Top Label shows the title of the Gauge. It can be positioned above the Gauge or inside the Gauge. The data grid column label is the default Top Label in Gauge Sets.

The Bottom Label further describes the value. It can be positioned below the Gauge or inside the Gauge. The data grid row label is the default Bottom Label in Gauge Sets.

The Metric Label shows the numerical value of the metric. It can be positioned below or with the bottom label, or inside the Gauge. The Metric Label may show the percentage value instead of numerical value.

If top, bottom, and metric labels are placed inside a Gauge, they are positioned at the center horizontally. When two or more labels are placed inside the Gauge, they are ordered vertically (from top, bottom and then metric label) within the Gauge Plot Area.

The Upper Label Frame is a decorative frame that encloses the Top Label, and the Lower Label Frame is the one that encloses the Bottom and Metric Labels. The fill color and border color of those frames can be modified.

Legend

The Legend of the Gauge shows a description of the thresholds. It shows the color and the name or range of each threshold. It can be positioned above, below, or to the left or right of the Gauge Plot Area using the position attribute of the <dvt:gaugeLegendArea> tag.

Note: Only one legend exists in either a single Gauge or a Gauge Set. For a Gauge Set, the threshold ranges or values showing in the legend is according to the first Gauge in the Gauge Set. Therefore, the usage of different threshold ranges for Gauges in a Gauge Set is not recommended.

The Legend Title and texts can be customized by the <dvt:gaugeLegendTitle> tag and <dvt:gaugeLegendText> tag respectively.

Gauge Size

The default Gauge size is 200 pixels tall by 200 pixels wide. The "inlineStyle" attribute can be used to change the size. Set inlineStyle = "width: 500px; height: 350px;", for instance, to change the Gauge size to 350 pixels tall by 500 pixels wide. The width and the height can also be specified in percent. Use percent for height only when the Gauge is added to an explicitly sized container or one that manages layout, otherwise gauge will behave differently for different browsers. Use the "dynamicResize" attribute to resize the Gauge based on its container size. Note that the specified size applies to the collection of all of the Gauges in a Gauge set, rather than to each individual Gauge.

Animation

Gauges support animation. Animate the gauge during initial rendering using the attribute "animationOnDisplay". The Gauge can also be animated when the data changes using the attribute "animationOnDataChange". Use the attribute "animationDuration" to specify the animation duration. Animation is not supported in Gauge Sets.

Tooltips

Tooltips are useful to display identification and or detail information of the metric value. While the indicator shows the ballpark value of the metric value, tooltip can be very useful to show the exact value.

Font

The <dvt:gaugeFont> tag is used for font formatting. Text color, style, size, and font name can be specified using this tag. This tag is used as a child tag for any of the Gauge's text component tags. Text components for the gauge are topLabel, bottomLabel, metricLabel, gaugeLegendText, gaugeLegendTitle and tickLabel.

Interactivity

Use the shapeAttributes tag to specify interactivity on an individual Gauge set component. A backing or managed bean may be required to use certain functionality of this feature. Please look at <dvt:shapeAttributes> tag for more information.

Here is an example of the interactivity on indicator and metric label. Here is a Dial Gauge. The tooltip of the indicator and the metric label become "Indicator" and "MetricLabel" respectively. When the indicator is clicked, the window title becomes "Indicator is clicked".

        <dvt:gauge gaugeType="DIAL">
            <dvt:shapeAttributesSet>
                <dvt:shapeAttributes component="GAUGE_INDICATOR"
                                         alt="Indicator"
                                         onClick="document.title="Indicator is clicked";"/>
                <dvt:shapeAttributes component="GAUGE_METRICLABEL"
                             alt="MetricLabel"/>
            </dvt:shapeAttributesSet>
        </dvt:gauge>
        

Relationship with other tags

The gauge can have the following child tags:

• <dvt:bottomLabel>
• <dvt:gaugeBackground>
• <dvt:gaugeFrame>
• <dvt:gaugeLegendArea>
• <dvt:gaugeLegendText>
• <dvt:gaugeLegendTitle>
• <dvt:gaugePlotArea>
• <dvt:gaugeSetBackground>
• <dvt:indicator>
• <dvt:indicatorBar>
• <dvt:indicatorBase>
• <dvt:lowerLabelFrame>
• <dvt:metricLabel>
• <dvt:shapeAttributesSet>
• <dvt:thresholdSet>
• <dvt:tickLabel>
• <dvt:tickMark>
• <dvt:topLabel>
• <dvt:upperLabelFrame>

Example

The following example shows XML for a gauge tag.
<dvt:gauge id="foo2" value ="#{sampleGauge.gaugeDataModel}"
gaugeType="STATUSMETER" imageFormat="FLASH"
imageHeight="350" imageWidth="250"
gaugeSetAlignment="GSA_RIGHT" gaugeSetColumnCount="2"
gaugeSetDirection="GSD_ACROSS"
partialTriggers="gaugeTypes2" partialSubmit="true">
</dvt:gauge>


Events

Attributes