* gradlew lwjgl3:run --args="classname dev.cf.app.wizard.WizardApp" ** *
One host Window that owns the trail, the footer and the current step; the steps themselves are * plain objects ({@link WizardStep}) that draw into a body the host provides. Not screens, not * windows — because the host has to be able to rebuild any of them at any time, in either * direction, and a stack of Windows cannot do that.
* *What is deliberately missing: saving a half-finished order and resuming it later. It is a real * requirement in real order entry, it is a persistence problem rather than a wizard problem, and * the seam for it is exactly the {@link Order} object — serialise that one thing and you have it.
*/ public class WizardApp extends Window implements Described { private final Order order = new Order(); private final ListBackwards is unconditional. Forwards runs the same gate {@link #next()} does, one step at a * time, so the trail cannot be used to skip a validation that the Next button enforces.
* * @param index the step to go to */ public void goToStep(int index) { if (index == current) return; if (index < current) { steps.get(current) .save(); showStep(index); return; } while (current < index) if (!next()) return; } /** * Advances one step if the current one is complete. * * @return whether it moved */ private boolean next() { WizardStep s = steps.get(current); s.save(); String p = s.problem(); if (p != null) { say(p); return false; } if (current == steps.size() - 1) { confirm(); return false; } showStep(current + 1); return true; } /** Goes back one step. Saves on the way out, and never validates. */ private void back() { if (current == 0) return; steps.get(current) .save(); showStep(current - 1); } private void showStep(int index) { try { current = index; say(null); body.removeAll(); // removeAll() takes the layout with it. body.setLayout(new VerticalLayout(Position.START, Position.START)); steps.get(index) .build(body); trail.current(index); trail.header((index + 1) + "/" + steps.size(), steps.get(index) .title() .toUpperCase(), "Total", Order.money(order.totalCents())); back.setEnabled(index > 0); next.setText(index == steps.size() - 1 ? "Place order" : "Next"); setValidLayout(false); Screen.repaint(); } catch (Exception e) { dev.crossfly.util.Debug.handle(e); } } private void say(String message) { problem.setText(message == null ? "" : message); problem.setVisible(message != null); problem.setValidLayout(false); if (message != null) Screen.repaint(); } /** * The end of the flow. * *It asks once, naming the total, and it is the only confirmation in the whole wizard. A * wizard that confirms each step teaches the user to dismiss confirmations, which is exactly the * habit you do not want them to have when they reach this one.
*/ private void confirm() { Alert a = new Alert("Place this order?", "Total " + Order.money(order.totalCents()) + " for " + order.customer + ".", "Cancel", "Place order"); a.buttonAction(1, c -> { Hint.show("Order placed", 2500); hide(); }); a.show(); } } ``` ### dev/cf/app/wizard/WizardStep.java ```java package dev.cf.app.wizard; import dev.crossfly.ui.Component; /** * One step of the wizard. * *The contract is four methods, and each of them exists because of a mistake that is easy to * make without it.
* *The single most important decision in a wizard shape. The steps write into this and * read from it; no step holds state of its own that survives its own screen. That is what makes * going backwards work — a step rebuilt on the way back reads what it wrote and shows it — and it * is what makes the review page possible at all, because the review has one place to read from * rather than four screens to interrogate.
* *The alternative, where each step keeps its own fields and hands them forward, works right up * until the user goes back two steps and changes something. Then the forward hand-off has already * happened, and half the wizard is holding stale copies.
*/ public class Order { /** One line of the order. */ public static class Line { /** What was ordered. */ public final String product; /** How many. */ public int quantity; /** Unit price in cents. */ public final long unitCents; /** * @param product the product name * @param quantity how many * @param unitCents the unit price in cents */ public Line(String product, int quantity, long unitCents) { this.product = product; this.quantity = quantity; this.unitCents = unitCents; } /** This line's total, in cents. */ public long totalCents() { return quantity * unitCents; } } // ── Step 1: who ── /** The customer's name. */ public String customer = ""; /** Contact e-mail. */ public String email = ""; /** Purchase-order reference the customer gave, if any. */ public String reference = ""; // ── Step 2: what ── /** The order lines. */ public final ListThe step with a list inside it, which is the one that makes a wizard interesting. Two things * follow from that and neither is obvious until it bites:
* *The step where one choice changes what the rest of the step asks: collection needs no address. * Hiding the address field rather than disabling it is the right call here — a disabled field * still reads as something you failed to fill in — and it is why {@link #problem()} checks the * address only when it is actually being asked for.
* *The options are {@link Option}s in a group rather than a dropdown, because there are three of * them, they carry a price, and the user should be able to compare them without opening anything. * A dropdown is right when the list is long or the choice is uninteresting; here it is neither.
*/ public class DeliveryStep extends WizardStep { private Option[] options; private TextField address; private Component addressBox; private Switch note; /** * @param order the shared order */ public DeliveryStep(Order order) { super(order); } public String title() { return "Delivery"; } public int icon() { return 0xE558; // local shipping } public String tag() { return "step.delivery"; } public void build(Component body) throws Exception { body.add(LAY_AUTO, outgap(label("How should it get there?", 1.5f, true, Styles.textColor, Position.START), 0, 0, 0, 1f)); Group group = new Group(); options = new Option[Order.SHIPPING.length]; for (int i = 0; i < options.length; i++) { final int idx = i; String cost = Order.SHIPPING_COST[i] == 0 ? "included" : Order.money(Order.SHIPPING_COST[i]); Option o = new Option(Order.SHIPPING[i] + " · " + cost); o.testTag("step.delivery.option." + i); o.setChecked(order.shipping == i); o.onAction(c -> { order.shipping = idx; showAddress(idx != 2); Screen.repaint(); }); group.add(o); options[i] = o; body.add(LAY_AUTO, outgap(o, 0, 0, 0, .4f)); } addressBox = new Component(); addressBox.setLayout(new VerticalLayout(Position.START, Position.START)); address = new TextField(order.address == null ? "" : order.address); address.caption("Delivery address"); address.testTag("step.delivery.address"); addressBox.add(LAY_AUTO, outgap(address, 0, .8f, 0, .8f)); body.add(LAY_AUTO, addressBox); note = new Switch("Include a delivery note"); note.checked(order.deliveryNote); note.testTag("step.delivery.note"); body.add(LAY_AUTO, note); showAddress(order.shipping != 2); } private void showAddress(boolean show) { addressBox.setVisible(show); addressBox.setValidLayout(false); } public void save() { order.address = address.getText() .trim(); order.deliveryNote = note.isChecked(); for (int i = 0; i < options.length; i++) if (options[i].isChecked()) order.shipping = i; } public String problem() { if (order.shipping < 0) return "Choose how it should be delivered."; if (order.shipping != 2 && order.address.isEmpty()) return "We need an address to deliver to."; return null; } public String[] summary() { return new String[] { "Shipping", order.shipping < 0 ? "—" : Order.SHIPPING[order.shipping], "Address", order.shipping == 2 ? "Collection" : order.address, "Delivery note", order.deliveryNote ? "Yes" : "No" }; } } ``` ### dev/cf/app/wizard/ReviewStep.java ```java package dev.cf.app.wizard; import java.util.List; import dev.crossfly.ui.*; import dev.crossfly.ui.graphics.*; import dev.crossfly.ui.layout.*; import dev.crossfly.ui.style.*; import static dev.crossfly.ui.Widgets.*; /** * Step 4 — the review, which is the step a wizard exists for. * *Every step before this one asked for something. This one is the only place the user sees the * whole thing at once, and it is where they either commit or notice the mistake. Three properties * make it work, and all three are about not duplicating the steps:
* *There is no top bar in CrossFly, and that is not an omission. A title bar is the single most * app-specific piece of chrome there is — height, colour, whether it collapses, whether the title * centres, what sits on the right — and a framework that decided those would be fought by every * app that used it. What the framework supplies is what a bar is made of: a container, a * layout, buttons, glyphs, and a style that follows the skin.
* *So this is an app-level class, shared by the four examples here because they are four * examples in one repository — in a real project it would live in your own {@code ui} package. It * is about forty lines, which is roughly what a top bar costs, and it is worth reading as the * answer to "how do I compose chrome out of primitives".
* *
* add(0f, new AppBar("Part", this::hide).action(0xE3C9, this::edit));
*
*/
public class AppBar extends Component
{
private final String title;
private final Runnable onBack;
private final int[] icons = new int[3];
private final Runnable[] actions = new Runnable[3];
private final String[] tags = new String[3];
private int count;
/**
* @param title the heading
* @param onBack what the back arrow does, or null for a bar with no back arrow
*/
public AppBar(String title, Runnable onBack)
{
this.title = title;
this.onBack = onBack;
}
/**
* Adds a right-hand action. Up to three; past that the answer is a menu, not a fourth glyph.
*
* @param codepoint the Material Icons codepoint
* @param tag the test tag for the button
* @param action what it does
* @return this bar, for chaining
*/
public AppBar action(int codepoint, String tag, Runnable action)
{
if (count < icons.length)
{
icons[count] = codepoint;
tags[count] = tag;
actions[count] = action;
count++;
}
return this;
}
@Override
public void onAdd(boolean firstTime) throws Exception
{
if (!firstTime)
return;
// A strip of surface with a hairline of elevation under it. Both colours are theme tokens, so
// the bar is right in dark mode and under every skin without a branch anywhere — and the
// shadow is expressed as a ratio of the font height, so it survives a high-DPI screen, where
// a shadow measured in pixels all but disappears.
getStyle().backColor(Styles.backColor)
.shadow(0, .06f, .25f, Styles.borderColor)
.ingap(Gap.ofFont(.5f, .4f, .5f, .4f));
setLayout(new GridLayout(Position.START, Position.CENTER));
// A bar with no back arrow gets no COLUMN for one. The obvious shortcut — always build the
// column and fill it with a bare `new Component()` — silently kills the entire row: an empty
// container has no layout, an auto-width column cannot measure it, and the bar comes out
// zero-high with the title inside it. It looks like the title was never added.
boolean hasBack = onBack != null;
int columns = (hasBack ? 1 : 0) + 1 + count;
Object[] cells = new Object[columns * 2];
int k = 0;
if (hasBack)
cells[k++] = 0f; // back: its own width
cells[k++] = 1f; // title: everything left over
for (int i = 0; i < count; i++)
cells[k++] = 0f; // actions: their own width
if (hasBack)
{
Button b = new Button(MaterialIcon.of(0xE5C4, 1.4f)); // arrow_back
b.testTag("bar.back");
b.onAction(c -> onBack.run());
b.getStyle()
.outgap(Gap.ofFont(0, 0, .5f, 0));
cells[k++] = b;
}
Label t = label(title, 1.5f, true, Styles.textColor, Position.START);
t.testTag("bar.title");
cells[k++] = t;
for (int i = 0; i < count; i++)
{
Button b = new Button(MaterialIcon.of(icons[i], 1.4f));
final Runnable a = actions[i];
b.testTag(tags[i]);
b.onAction(c -> a.run());
b.getStyle()
.outgap(Gap.ofFont(.4f, 0, 0, 0));
cells[k++] = b;
}
add(cells);
}
}
```
### dev/cf/app/AppTheme.java
```java
package dev.cf.app;
import dev.crossfly.ui.color.ColorScheme;
import dev.crossfly.ui.style.Styles;
/**
* The one line that gives an app its colour, and the reason the four examples here have one.
*
* An app declares its brand; it does not pick colours. One seed goes in, and CrossFly * derives the whole scheme from it — primary, surface, on-surface, containers, the tonal fills * behind an active tab, the ring of a gauge, both themes. Nothing downstream names a colour, which * is what makes dark mode and the skin picker work without a single branch.
* *Skip this and the app is not "unstyled", it is grey: the skin's neutral palette is what * you get when nobody declared anything, and it looks exactly like a bug. That is what happened to * these four — they were correct from the samples menu, which declares a brand of its own, and * monochrome when launched straight from {@code classname}, which is how anybody copying them would * run them.
* *The brand is global state. A real app declares it once in {@code Main} and never thinks about * it again — and if that is your case, {@code Styles.setBrand(BRAND)} at startup is the whole story * and this class is more machinery than you need.
* *These four are different: they are guests. They open from a menu that has its own brand, and * from a test suite whose later screenshots are compared against committed images. A guest that * changes global state and walks away leaves its host repainted in someone else's colour — the * samples menu comes back blue, the goldens fail three tests later, and neither failure points at * the app that caused it. So each app calls {@link #enter()} when it opens and {@link #leave()} * when it closes, and the palette that was in force is handed back.
*/ public final class AppTheme { /** * The seed every colour in the four example apps is derived from. * *Deep blue, chosen against orange for one reason: orange is the brand of the production app * these examples were extracted from, and an example that wears it invites the reader to think * the two are related. For orange instead, this is the only line to change — * {@code 0xFFE2622C} is a good one. Nothing else in the four apps names a colour.
*/ public static final int BRAND = 0xFF1565C0; /** * The page behind the cards: the surface, pulled a little way towards the brand. * *Why a page needs its own colour at all. Cards, buttons and fields are all drawn on * the skin's surface, which in a light theme is white or near it. Put them on a white page and * every edge disappears — the card stops reading as a card and a white button on white looks * like a mistake rather than a control. What separates them is not a border, it is the page * being a shade the foreground is not.
* *Why it is derived and not a hex. {@code 0xFFF2F5F9} would be a perfectly nice light * blue and would be wrong twice: it stops being light blue the moment somebody changes * {@link #BRAND} to orange, and it stays light in dark mode, where the page must go darker than * the cards rather than lighter. Mixing the primary into the surface at 8% follows both — the * tint always matches the brand, and in a dark theme the same call yields a deep, slightly * tinted ground.
* *Read it through {@code onRestyle} rather than once, so a theme flip re-derives it.
* * @return the ARGB page colour for the palette currently in force */ public static int pageColor() { return dev.cf.Tones.page(); } /** What was in force before the outermost {@link #enter()}. */ private static Integer previousBrand; private static ColorScheme previousScheme; /** How many example apps are open. Restores only when the last one closes. */ private static int depth; private AppTheme() { } /** * Declares {@link #BRAND}, remembering whatever was in force. * *Call it first thing in {@code onAdd}. It triggers a restyle, so every window already open * re-resolves its colours — including this one, which is why it can run before the screen is * built.
*/ public static void enter() { if (depth++ == 0) { previousBrand = Styles.hasBrand() ? Integer.valueOf(Styles.brand()) : null; ColorScheme live = Styles.colorScheme(); if (live != null) { // A SNAPSHOT, never the reference. Styles keeps ONE ColorScheme instance for the life // of the app and mutates its roles in place on every seed change — deliberately, so // that a PalColor captured into a style at build time keeps resolving and follows the // theme forever. The consequence for anybody saving and restoring: the object you kept // IS the object about to be overwritten, so handing it back restores nothing at all. // This cost four broken golden images in a suite that had been green all morning. previousScheme = ColorScheme.fromSeed(BRAND, live.isDark); previousScheme.copyFrom(live); } } Styles.setBrand(BRAND); } /** * Hands the palette back to the host. * *Call it from {@code onRemove}, which CrossFly runs on {@code hide()}. Two cases: the host * had declared a brand, so re-declaring it regenerates everything; or nothing was declared, so * the declaration is dropped and the scheme that was actually in force is restored — * clearing the brand alone would leave this app's blue behind, still painted, just no longer * owned by anybody.
*/ public static void leave() { if (depth > 0 && --depth == 0) { if (previousBrand != null) Styles.setBrand(previousBrand.intValue()); else { Styles.clearBrand(); if (previousScheme != null) Styles.setColorScheme(previousScheme); } previousBrand = null; previousScheme = null; } } } ```