Introduction
JFXGauge is a small library of JavaFX gauge controls. Two skins are currently available for the gauges: a text and a thermometer skin.
| The source code is available on GitHub. |
Getting Started
| You need Java 11 or newer in order to use JFXGauge. |
Installation
JFXGauge is available in Maven Central and JCenter.
<dependency>
<groupId>org.beryx.jfxgauge</groupId>
<artifactId>jfxgauge</artifactId>
<version>2.0.0</version>
</dependency>
compile 'org.beryx.jfxgauge:jfxgauge:2.0.0'
Demo
Download the binary distribution and unzip it into a directory of your choice.
Make sure your JAVA_HOME environment variable correctly points to a JDK 8u40 or later.
Start the demo by executing 'jfxgauge' or 'jfxgauge.bat' in the bin directory.
Usage
A quick and effective way to learn how to use the gauges is to look at the source code of the GaugeDemo application. For an in-depth look, read the next sections of this documentation.
Gauges
A gauge is a JavaFX control.
The library offers two types of gauges: for int and for double values.
They are implemented by the classes org.beryx.jfxgauge.IntGauge and org.beryx.jfxgauge.DoubleGauge.
Both classes extend the abstract base class org.beryx.jfxgauge.Gauge.
A gauge has a series of JavaFX properties, as shown in the table below.
| Property | Type | Description |
|---|---|---|
value |
int / double |
the value indicated by the gauge |
lowValue |
int / double |
the lowest value that can be displayed by the gauge |
highValue |
int / double |
the highest value that can be displayed by the gauge |
valueFormat |
String |
the format used to display the values
(default format: "%d" for IntGauge; "%.2f" for DoubleGauge) |
status |
String |
read-only: computed based on value and thresholds;
the computed status may be overridden by imposedStatus;
used by skins to style the gauge;
(see details below) |
imposedStatus |
String |
if not null, it overrides the computed status;
(example: imposing the status as not-available) |
lowestStatus |
String |
the status corresponding to values below the first threshold |
thresholds |
List<Threshold> |
the list of thresholds used to compute the status;
each threshold entry is a pair <status, value> |
valueVisible |
boolean |
a hint to the skin to display the gauge value |
rangeVisible |
boolean |
a hint to the skin to display the lowValue and highValue |
thresholdsVisible |
boolean |
a hint to the skin to display the threshold values |
The status of a gauge determines its visual appearance. A skin uses the status to style the gauge, by adding status-related style classes to its components.
For example, if the gauge status is warning, a skin might add the style class value-warning to the text component used to display the value.
By adjusting the CSS properties of the value-warning style class, you can customize the visual appearance of the gauge in warning state.
Consult the Skins section for details about the style classes used by each skin.
By default, the status of a gauge is determined by the highest threshold with a value below the current value. If no such threshold exists, because the current value is below the one corresponding to the lowest threshold, the status is set to lowestStatus.
A frequent use case involves three acceptability ranges for the gauge values, corresponding to the ok, warning and error states.
For this situation, the Gauge class offers the convenience method configureWarningAndErrorThresholds, which takes two numerical arguments: warningThreshold and errorThreshold.
Consider an application where the process that updates the gauge values is temporarily out of order. In this case, the status determined using the value property and the thresholds no longer reflects the reality and you may want to override it with a status that signals the unavailability of the gauge. This can be done by setting the imposedStatus property.
There are no restrictions on the number of statuses of a gauge. You are also free to choose whatever names you want for the gauge statuses, as long as they are valid CSS names.
As a convenience, all skins have CSS stylesheets that customize the following statuses: ok, warning, error and not-available.
Skins
JFXGauge currently offers a text and a thermometer skin. You can use the CSS property -fx-skin to specify which skin should be used. If you don’t set this property, the gauge will use the thermometer skin.
The text skin
.gauge {
-fx-skin: "org.beryx.jfxgauge.TextSkin";
}The text skin consists only of a Text component, as can be seen in the figure below.
| CSS style class | Component | Example |
|---|---|---|
gauge
gauge-<status> |
gauge |
.gauge {
-fx-effect: innershadow(two-pass-box , black, 40, 0.1, 0, 0);
}
.gauge-warning {
-fx-background-color: orange;
} |
<gauge-id>-<status> |
gauge |
.text2-ok {
-fx-background-image: url("ok.png");
-fx-background-size: 120;
} |
value
value-<status> |
text |
#text2 .value {
-fx-underline: true;
}
.gauge .value-error {
-fx-fill: #cc5533;
} |
The thermometer skin
.gauge {
-fx-skin: "org.beryx.jfxgauge.ThermometerSkin";
}
The figure below shows the main graphical components handled by the thermometer skin.
The figure below shows the graphical components associated with text and markings.
| CSS style class | Component | Example |
|---|---|---|
gauge
gauge-<status> |
gauge |
.gauge-warning {
-fx-background-color: orange;
} |
pane
pane-<status> |
pane |
.gauge .pane-not-available {
-fx-opacity: 0.3;
} |
value
value-<status> |
text |
.gauge .value-error {
-fx-fill: #cc5533;
} |
tube-top
tube-top-<status> |
tubeTop |
#thermo1 .tube-top {
visibility: hidden;
} |
tube-bottom
tube-bottom-<status> |
tubeBottom |
#thermo1 .tube-bottom {
-fx-effect: innershadow(two-pass-box , black, 40, 0.1, 0, 0);
-fx-opacity: 0.8;
} |
tube-body
tube-body-<status> |
tubeBody |
#thermo0 .tube-body {
-fx-fill: pink;
} |
fluid
fluid-<status> |
tubeFluid
tubeBottom |
#thermo1 .fluid-not-available {
-fx-fill: #cccccc;
} |
tube-outside
tube-outside-<status> |
tubeTop
tubeBottom
tubeLeftWall
tubeRightWall |
#thermo1 .tube-outside-not-available {
-fx-stroke: #cccccc;
} |
tube-inside
tube-inside-<status> |
tubeTop
tubeBody |
#thermo2 .tube-inside {
-fx-fill: #f0f0ff;
} |
range-text |
rangeMarkingText |
#thermo3 .range-text {
-fx-rotate: -135;
-fx-translate-x: -2;
-fx-translate-y: 10;
} |
range-marking |
rangeMarkingLine |
#thermo5 .range-marking {
-fx-stroke: #8080f0;
-fx-stroke-width: 4;
} |
threshold-text
threshold-text-<status> |
thresholdMarkingText |
#thermo5 .threshold-warning-text {
-fx-fill: orange;
} |
threshold-marking
threshold-marking-<status> |
thresholdMarkingLine |
#thermo5 .threshold-warning-marking {
-fx-stroke: #f0f080;
-fx-stroke-width: 4;
} |
| Property | Type | Description | Example |
|---|---|---|---|
aspectRatio |
number |
top radius / bottom radius |
#thermo3 {
-fx-aspect-ratio: 0.2;
-fx-range-position: right;
-fx-threshold-position: left;
} |
rangePosition |
left | right |
where to place the range markings |
|
thresholdPosition |
left | right |
where to place the threshold markings |