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