<dvt:gauge>

dvt:gauge gauge gauge

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

Overview

The gauge tag is deprecated. Use the dialGauge, ledGauge, ratingGauge, or statusMeterGauge tag instead.

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);

Number Formatting

DVT gauge supports number formatting on its metricLabel and tickLabel. Users can customize the number formatting by adding <af:convertNumber> to the <dvt:metricLabel> and <dvt:tickLabel> tags. The following is an example of how to configure these tags:

<dvt:gauge value="#{binding.dataModel}"> <dvt:metricLabel> <af:convertNumber pattern="#{appPrefs.metricLabelPattern}" /> </dvt:metricLabel> </dvt:tickLabel> <af:convertNumber pattern="#{appPrefs.tickLabelPattern}" /> </dvt:tickLabel> </dvt:gauge>

Automatic Scaling and Precision

Gauge automatically determines the scale ( e.g. 4K ) and precision ( e.g. show 2 decimal points - 0.25 ) based on the values that are being displayed. This automatic formatting still occurs when <af:convertNumber> is specified. The gauge tags that support <af:convertNumber> child tags ( <dvt:metricLabel> and <dvt:tickLabel>) also have scaling and autoPrecision attributes that can be used to control graph's automatic number formatting. By default, scaling="auto" means gauge will auto-calculate the scale. For example, 40,000 will be formatted as "40K". By default, autoPrecision="on" means that graph will auto-calculate the precision of the number. For example, 0.230546 will be displayed as "0.23". If the autoPrecision is 'on' then all of the <af:convertNumber> fraction digit settings ( e.g. min/maxFractionDigits or pattern) are ignored.

Formatting Percent values

When number type is set to percent (valid value are NT_NUMBER and NT_PERCENT), the formatting engine will use the label format and will automatically force the convertNumber type to percent. When <af:convertNumber> is forced to percent, gauge clears <af:convertNumber> pattern, since the pattern will prevent type=percent if specified. This means that patterns are ignored when gauge forces percent formatting.

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.

Context Menus

Context menus can be defined by using any of the context menu facets that are defined on the gauge. Context Menus are currently only supported in Flash.

Due to technical limitations when using the Flash rendering format, the context menu contents are currently displayed using the Flash Player's context menu. This imposes several limitations defined by the Flash Player:

• Flash does not allow for submenus in its context menu.
• Flash only allows a maximum of 15 custom menu items. The component's built in menu items, such as the ones for interactiveSliceBehavior, also count towards this limit.
• Flash only allows for text-only menu items. Icons or other controls possible in ADF Faces menus are not possible in Flash.
• Each caption must contain at least one visible character.
• Control characters, newlines, and other white space characters are ignored.
• No caption can be more than 100 characters long.
• Captions that are identical to another custom item are ignored, whether the matching item is visible or not. Menu captions are compared to built-in captions or existing custom captions without regard to case, punctuation, or white space.
• The following captions are not allowed, but the words may be used in conjunction with other words to form a custom caption: "Save","Zoom In", "Zoom Out", "100%", "Show All", "Quality", "Play", "Loop", "Rewind", "Forward", "Back", "Movie not loaded", "About", "Print", "Show Redraw Regions", "Debugger", "Undo", "Cut", "Copy", "Paste", "Delete", "Select All", "Open", "Open in new window", "Copy link"
• None of the following words can appear in a custom caption on their own or in conjunction with other words: "Adobe", "Macromedia", "Flash Player", "Settings"

Additionally, since Flash's request for context menu items is a synchronous call, so a server request to evaluate EL is not possible when the context menu is invoked. To provide context menus that vary by selected object, the menus will be pre-fetched if the context menu popup uses contentDelivery="lazyUncached". For context menus that may vary by state, this means that any EL expressions within the menu definition will be called repeatedly at render time, with different selection and currency states. When using these context menus that are pre-fetched, the application must be aware of the following:

• Long running or slow code should not be executed in any EL that may be used to determine how the context menu is displayed. This does not apply to af:commandMenuItem attributes that are called after a menu item is selected, such as "actionListener".
• In the future, if the Flash limitations are solved, the ADF context menu may be displayed in place of the Flash context menu. To ensure upgrade compatibility, applications developers should code such that their EL will function both in cases where the menu is pre-fetched, and also if the EL is evaluated when the menu is invoked. It is highly recommended that the only component state that applications rely on are selection and currency.

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:attributeFormat>
• <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"
inlineStyle = "width:350px; height:250px;"
gaugeSetAlignment="GSA_RIGHT" gaugeSetColumnCount="2"
gaugeSetDirection="GSD_ACROSS"
partialTriggers="gaugeTypes2" partialSubmit="true">
</dvt:gauge>


Geometry Management

• This component can be stretched by a parent layout component that stretches its children, e.g. panelStretchLayout, panelSplitter, if dynamicResize="DYNAMIC_SIZE" is set.
• This component does stretch to fill up the browser's viewport when it is the "sole visual root component" in the component tree, if dynamicResize="DYNAMIC_SIZE" is set.
• When NOT stretched, this component will be displayed in its default dimensions which are provided by the skin. This can be modified by applying a dimension using the inlineStyle or styleClass attributes.
• This component does not stretch its children.

Attachment Mode

In attachment mode, the gauge will be displayed in HTML5 or PNG, depending on the browser being used. Limited client interactivity, such as tooltips, is available. The clickListener feature is not supported in attachment mode.

Screen Shot(s)

Events

Supported Facets

Attributes