free html hit counter

Introduction

JFXGauge is a small library of JavaFX gauge controls. Two skins are currently available for the gauges: a text and a thermometer skin.

textDemo thumbnail
Text skin

 

thermoDemo thumbnail
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.

Maven
<dependency>
    <groupId>org.beryx.jfxgauge</groupId>
    <artifactId>jfxgauge</artifactId>
    <version>2.0.0</version>
</dependency>
Gradle
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.

Gauge properties
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

Configuration via CSS
.gauge {
    -fx-skin: "org.beryx.jfxgauge.TextSkin";
}

The text skin consists only of a Text component, as can be seen in the figure below.

textSkin
CSS styling
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

Configuration via CSS
.gauge {
    -fx-skin: "org.beryx.jfxgauge.ThermometerSkin";
}

The figure below shows the main graphical components handled by the thermometer skin.

thermoSkinComponents

The figure below shows the graphical components associated with text and markings.

thermoSkinMarkings
CSS styling
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; }
Custom CSS properties
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