HanSolo Medusa Usage Guide

HanSolo Medusa adds gauge and clock controls to Aussom under fx.hansolo.medusa. It is useful for dashboards, monitoring screens, control panels, and any UI that needs rich meter-style displays instead of plain text or progress bars.

The Medusa wrappers are builder-first. That matches how the Java library is designed and keeps the common configuration path small and readable.

What It Is Good For

dashboards with gauges and dials
clocks with multiple visual skins
monitoring views with thresholds, sections, and markers
framed gauge displays for industrial or control-panel UIs

Main Building Blocks

Class	Use For
`HsGaugeBuilder`	Main builder for Medusa gauges.
`HsGauge`	Runtime gauge control after build.
`HsClockBuilder`	Main builder for Medusa clocks.
`HsClock`	Runtime clock control after build.
`HsFGaugeBuilder`	Builder for framed gauges.
`HsFGauge`	Framed gauge region.
`HsSection`	Numeric bands on gauges.
`HsMarker`	Numeric threshold markers on gauges.
`HsAlarm`	Clock alarms.
`HsTimeSection`	Time ranges on clocks.

Getting Started

Include the Medusa module and the FX classes you need:

include fx;
include fx.Color;
include fx.hansolo.medusa.medusa;

Example 1: Gauge With Builder, Section, and Marker

include fx;
include fx.Color;
include fx.hansolo.medusa.medusa;

app = fx.fxApp("Medusa Gauge", 500, 420);

green = new Color("#37A169");
red = new Color("#E53E3E");

normal = new HsSection(0.0, 60.0, "Normal", green);
warning = new HsMarker(75.0, "Warn", red);

gauge = medusa.newGaugeBuilder()
    .skinType("DASHBOARD")
    .title("CPU")
    .unit("%")
    .minValue(0.0)
    .maxValue(100.0)
    .value(42.0)
    .sections([normal])
    .markers([warning])
    .animated(false)
    .valueVisible(true)
    .prefSize(320.0, 320.0)
    .build();

app.setLayout(gauge);
app.show(true);
fx.shutdown();

Example 2: Clock With Time Sections and Alarm

include fx;
include fx.Color;
include fx.hansolo.medusa.medusa;

app = fx.fxApp("Medusa Clock", 500, 420);

blue = new Color("#3182CE");

workHours = new HsTimeSection(
    medusa.localTime(9, 0),
    medusa.localTime(17, 0),
    "Work",
    blue
);

alarm = new HsAlarm("2026-04-19T12:00:00Z", "ONCE", "Lunch");

clock = medusa.newClockBuilder()
    .skinType("INDUSTRIAL")
    .title("UTC")
    .text("World")
    .timeIso("2026-04-19T12:00:00Z")
    .sections([workHours])
    .alarms([alarm])
    .running(false)
    .prefSize(320.0, 320.0)
    .build();

app.setLayout(clock);
app.show(true);
fx.shutdown();

Example 3: Framed Gauge

include fx;
include fx.hansolo.medusa.medusa;

app = fx.fxApp("Framed Gauge", 500, 420);

baseGauge = medusa.newGaugeBuilder()
    .skinType("SIMPLE")
    .title("Load")
    .value(18.0)
    .animated(false)
    .build();

fGauge = medusa.newFGaugeBuilder()
    .gauge(baseGauge)
    .gaugeDesign("METAL")
    .gaugeBackground("DARK_GRAY")
    .foregroundVisible(true)
    .build();

fGauge.setPrefSize(320.0, 320.0);

app.setLayout(fGauge);
app.show(true);
fx.shutdown();

Runtime Updates

The builder is for initial setup. After build(), use the runtime wrapper to change the control:

gauge.setValue(55.0);
clock.setText("Updated");
clock.setRunning(false);

Tips and Gotchas

Start with the builders. Medusa has a large property surface, and the builder path is the cleanest way to configure a new control.
Use the medusa.*Types() helper functions when you want to discover valid enum names such as skin types, LCD designs, or tick label locations.
HsAlarm takes ISO-8601 date/time strings for the common path. Example: "2026-04-19T12:00:00Z".
HsTimeSection expects Java LocalTime values. Use medusa.localTime(...) to create them.
If you update a shown Medusa control during tests or other async work, do it on the FX thread with fx.runLater(...).
The wrappers expose the common configuration path, but you can still use .obj with AJI for deeper library features.