Element: <oj-c-meter-circle>

CORE PACK

Oracle® JavaScript Extension Toolkit (JET)
17.0.0

F92240-01

Since:
  • 14.0.0
Module:
  • meter-circle

Note: This component supersedes the following component: <oj-status-meter-gauge>. Migration info available at preceding link.

QuickNav

Attributes


JET meter circle

A meter circle displays information graphically in a circular bar, highlighting a specific metric value's progress in relation to its min, max and thresholds.
<oj-c-meter-circle value='4'></oj-c-meter-circle>

Accessibility

The application is strongly encouraged, even though it is not required, to populate the aria-label attribute on the element with meaningful descriptors as the oj-c-meter-circle element does not provide a default descriptor.

If an application is using center content with visible text, thresholds, or reference lines, they need to include the information for screender readers using the following methods:

  • aria-describedby
  • aria-labelledby
  • aria-label

If you are using indicatorColor, applications are responsible for making sure that the color meets the minimum contrast ratio.

Keyboard

Key Action
Enter Submit the current value of the meter circle.
Tab Move focus to next element and submit the current value of the meter circle.
Shift + Tab Move focus to previous element.
End Increase the meter circle's transient value to max value. Value is set after using Enter or Tab to submit.
Home Decrease the meter circle's transient value to zero. Value is set after using Enter or Tab to submit.
UpArrow Increase the meter circle's transient value. Value is set after using Enter or Tab to submit.
DownArrow Decrease the meter circle's transient value. Value is set after using Enter or Tab to submit.
LeftArrow Decrease the meter circle's transient value in left-to-right locales. Increase the meter circle's transient value in right-to-left locales. Value is set after using Enter or Tab to submit.
RightArrow Increase the meter circle's transient value in left-to-right locales. Decrease the meter circle's transient value in right-to-left locales. Value is set after using Enter or Tab to submit.

Touch End User Information

Gesture Action
Drag Value change when readonly is false.


Usage

Signature:

interface CMeterCircleElement

Typescript Import Format
//To typecheck the element APIs, import as below.
import { CMeterCircleElement } from "oj-c/meter-circle";

//For the transpiled javascript to load the element's module, import as below
import "oj-c/meter-circle";

For additional information visit:

Note: Application logic should not interact with the component's properties or invoke its methods until the BusyContext indicates that the component is ready for interaction.


Slots

JET components that allow child content support slots. Please see the slots section of the JET component overview doc for more information on allowed slot content and slot types.

centerTemplate

The centerTemplate slot is used to specify center content. When the template is executed, the component's binding context is extended with the following properties:
Properties of $current:
Name Type Description
innerBounds oj-c.MeterCircle.Bounds Object containing (x, y, width, height) of the rectangle inscribed in the center area. The inner bounds are useful for inserting content that is guaranteed to fit within the center area. If the angleExtent isn't 360 then we will provide the clipped square.
outerBounds oj-c.MeterCircle.Bounds Object containing (x, y, width, height) of the rectangle circumscribing the center area. The outer bounds are useful for creating background for the entire center area when used with a CSS border-radius. If the angleExtent isn't 360 then we will provide the clipped square.
value (number|null) The current value of the meter circle.

Attributes

angle-extent :number

Specifies the angle extent of a meter circle. Value should be provided in degrees.
Default Value:
  • 360
Names
Item Name
Property angleExtent
Property change event angleExtentChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-angle-extent-changed

color :string

Specifies the color of the meter circle indicator. Only applies when thresholdDisplay is not set to indicator.
Names
Item Name
Property color
Property change event colorChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-color-changed

datatip :(context: oj-c.MeterBar.DatatipContext) => string | null

The function that returns a custom datatip string for given value of meter circle. The function is called with DatatipContext as context. If datatip is undefined, meter circle will use the default datatip. If the returned value of the function is null, no datatip is shown.
Names
Item Name
Property datatip
Property change event datatipChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-datatip-changed

described-by :(string|null)

Used to establish a relationship between this component and another element. A common use is to tie a label, which can be a text in a div or some other HTML element, and the oj-c-meter-circle together for accessibility. The oj-label element has a label-id, which is used by the described-by attribute to tie the two components together to facilitate correct screen reader behavior.
Names
Item Name
Property describedBy
Property change event describedByChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-described-by-changed

indicator-size :number

Specifies the ratio of relative thickness of the indicator to the plot area.
Default Value:
  • 1
Names
Item Name
Property indicatorSize
Property change event indicatorSizeChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-indicator-size-changed

inner-radius :number

Specifies the inner radius, defined by the ratio of the distance from the center of the gauge to the innermost edge of the indicator to plot area. Valid values are ratios from 0 to 1. Depends on the size of the gauge and theme.
Names
Item Name
Property innerRadius
Property change event innerRadiusChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-inner-radius-changed

labelled-by :(string|null)

Used to establish a relationship between this component and another element. A common use is to tie a label, which can be a text in a div or some other HTML element, and the oj-c-meter-circle together for accessibility. The oj-label element has a label-id, which is used by the labelled-by attribute to tie the two components together to facilitate correct screen reader behavior.
Names
Item Name
Property labelledBy
Property change event labelledByChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-labelled-by-changed

max :number

Integer value specifying the maximum value of the meter circle.
Default Value:
  • 100
Names
Item Name
Property max
Property change event maxChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-max-changed

min :number

Integer value specifying the minimum value of the meter circle.
Default Value:
  • 0
Names
Item Name
Property min
Property change event minChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-min-changed

plot-area* :oj-c.MeterCircle.PlotArea

Specifies the plot area of the meter circle.
Names
Item Name
Property plotArea
Property change event plotAreaChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-plot-area*-changed

readonly :boolean

Defines whether the value of the meter circle can be changed by the end user.
Default Value:
  • false
Names
Item Name
Property readonly
Property change event readonlyChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-readonly-changed

reference-lines :Array.<oj-c.MeterCircle.ReferenceLine>

Specifies the array of objects defining the reference lines for the meter circle.
Names
Item Name
Property referenceLines
Property change event referenceLinesChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-reference-lines-changed

size :"sm"|"md"|"lg"|"fit"

Specifies the size of the meter var.
Supported Values:
Value Description
fit Meter Circle that fills available width and height.
lg large Meter circle
md medium Meter circle (default, if unspecified)
sm small Meter circle
Default Value:
  • "md"
Names
Item Name
Property size
Property change event sizeChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-size-changed

start-angle :number

Specifies the start angle of the plot area relative to the positive x axis. Value should be provided in degrees.
Default Value:
  • 90
Names
Item Name
Property startAngle
Property change event startAngleChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-start-angle-changed

step :number

Specifies the increment by which values can be changed by the end user when readonly is false. The step must be a positive value that is smaller than the difference between the min and max.
Default Value:
  • 1
Names
Item Name
Property step
Property change event stepChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-step-changed

threshold-display :"all"|"plotArea"|"indicator"

Controls whether the current threshold is displayed on the indicator, in the plot area, or if all the thresholds are displayed in the plot area.
Default Value:
  • "indicator"
Names
Item Name
Property thresholdDisplay
Property change event thresholdDisplayChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-threshold-display-changed

thresholds :Array.<oj-c.MeterCircle.Threshold>

An array of objects defining the thresholds for the meter circle.
Names
Item Name
Property thresholds
Property change event thresholdsChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-thresholds-changed

(readonly) transient-value :number

A read-only property for retrieving the transient value from the meter circle. It is triggered when dragging over the meter circle.
Supports writeback:
  • true
Names
Item Name
Property transientValue
Property change event transientValueChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-transient-value-changed

value :(number|null)

The value of the meter circle.
Default Value:
  • 0
Supports writeback:
  • true
Names
Item Name
Property value
Property change event valueChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-value-changed

Methods

getProperty(property) : {any}

Retrieves the value of a property or a subproperty.
Parameters:
Name Type Description
property The property name to get. Supports dot notation for subproperty access.
Returns:
Type
any

setProperties(properties) : {void}

Performs a batch set of properties.
Parameters:
Name Type Description
properties An object containing the property and value pairs to set.
Returns:
Type
void

setProperty(property, value) : {void}

Sets a property or a single subproperty for complex properties and notifies the component of the change, triggering a corresponding event.
Parameters:
Name Type Description
property The property name to set. Supports dot notation for subproperty access.
value The new value to set the property to.
Returns:
Type
void

Type Definitions

Bounds

Properties:
Name Type Description
height number The height of the bounding rectangle.
width number The width of the bounding rectangle.
x number The x position of the bounding rectangle.
y number The y position of the bounding rectangle.

DatatipContext

Context for datatip function.
Properties:
Name Type Description
value number The current value of the meter circle.

PlotArea

Properties:
Name Type Argument Description
color string <optional>
The color of the plot area.
rendered "off" | "on" <optional>
Defines if the plot area is to be rendered. The default value is on.

ReferenceLine

Properties:
Name Type Argument Description
color string <optional>

The color of the reference line.

In addition to standard CSS color values, special enumerated values 'danger', 'warning', and 'success' are also supported. These special values are mapped to corresponding CSS color values based upon the current theme.

value number The value of the reference line.

Threshold

Properties:
Name Type Argument Description
accessibleLabel string <optional>
A label for the threshold used for accessibility purposes.
color string <optional>

The color of the threshold.

In addition to standard CSS color values, special enumerated values 'danger', 'warning', and 'success' are also supported. These special values are mapped to corresponding CSS color values based upon the current theme.

max number The maximum value of the threshold.