CSSFX Usage Guide

CSSFX adds development-time stylesheet hot reload for JavaFX apps in Aussom through the cssfx module. It watches the CSS files attached to your app and reloads them when you save changes, which makes visual iteration much faster than restarting the app after every tweak.

The wrapper is intentionally AJI-first. Aussom provides the common start and scoping helpers, while raw AJI remains available for advanced CSSFX features.

What It Is Good For

live CSS editing while building JavaFX screens
quickly iterating on layout, color, spacing, and typography
narrowing CSSFX monitoring to one stage, scene, or node
custom URI-to-path conversion when stylesheet lookup is non-standard

Key Concepts

Concept	Meaning
`cssfx.startMonitor()`	Starts global monitoring and returns a stop handle.
`cssfx.forStage(...)`	Limits monitoring to one stage.
`cssfx.forScene(...)`	Limits monitoring to one scene.
`cssfx.forNode(...)`	Limits monitoring to one node subtree.
`CssFxConfig`	Scoped configuration object used before calling `startMonitor()`.
`CssFxMonitor`	Stop handle returned by CSSFX start methods.
`addConverterCallback(...)`	Adds a custom URI-to-path converter for unusual stylesheet paths.

Getting Started

Include the module alongside the JavaFX controls you are styling:

include fx;
include fx.Label;
include fx.VBox;
include cssfx;

Attach a real CSS file to your app first, then start CSSFX after the app is shown.

Example 1: Global Hot Reload

include fx;
include fx.Label;
include fx.VBox;
include cssfx;

app = fx.fxApp("CSSFX Demo", 420, 220);

label = new Label("Hot Reload");
label.setId("liveLabel");

root = new VBox();
root.add(label);

app.setLayout(root);
app.addStyleSheet("styles/app.css");
app.show(true);

monitor = cssfx.startMonitor();

fx.shutdown();
monitor.stop();

While the app is open, editing styles/app.css will trigger a stylesheet reload.

Example 2: Scene-Scoped Monitor With a Custom Converter

This pattern is useful when CSSFX cannot map a stylesheet URI back to the file you want to watch.

include fx;
include fx.Label;
include fx.VBox;
include cssfx;

public convertCssUri(Uri) {
    return cssfx.pathFromUri(Uri);
}

app = fx.fxApp("Scoped CSSFX", 420, 220);

label = new Label("Scoped");
label.setId("liveLabel");

root = new VBox();
root.add(label);

app.setLayout(root);
app.addStyleSheet("tests/cssfx-test.css");
app.show(true);

stage = app.getAjo();
scene = stage.invoke("getScene");

cfg = cssfx.forScene(scene);
cfg.noDefaultConverters();
cfg.addConverterCallback(::convertCssUri);

monitor = cfg.startMonitor();

fx.shutdown();
monitor.stop();

Example 3: Node-Scoped Monitor

If only one scene subtree is actively being developed, you can scope monitoring to that node:

include fx;
include fx.Label;
include fx.VBox;
include cssfx;

app = fx.fxApp("Node CSSFX", 420, 220);

label = new Label("Node Scoped");
root = new VBox();
root.add(label);

app.setLayout(root);
app.addStyleSheet("styles/app.css");
app.show(true);

monitor = cssfx.forNode(label.obj).startMonitor();

fx.shutdown();
monitor.stop();

Tips and Gotchas

CSSFX is for development-time workflow, not normal production startup.
Start CSSFX after the JavaFX app is shown so the stage and scene are real.
Stylesheets should point to actual files on disk. CSSFX cannot hot reload something that does not map back to a watchable path.
If default URI conversion does not work in your project layout, use noDefaultConverters() plus addConverterCallback(...).
Always keep the returned CssFxMonitor if you want an explicit stop hook.
The wrapper is intentionally thin. If you need a CSSFX API that is not wrapped yet, use raw AJI against the underlying Java classes.