Images, and the two questions that come up before the picture does.
\n\nHow does it fill its box? ImageSize is the whole answer, and picking\nwrong is the most visible mistake in an app: a portrait photo stretched into a landscape tile is\nnoticed by everybody and reported by nobody, because it looks like a bad photo rather than a bug.\nCropping to fill is almost always right for a photo; fitting inside is almost always right for a\nlogo.
Where does the image come from? An app's own assets, or bytes it was handed — a camera\ncapture, a database blob, a download. Both end up as an Image, and neither belongs in\nonPaint: decoding is expensive, and doing it per frame is the classic reason a list\nstutters exactly where the pictures are.
Drawn here rather than loaded from a file, so the recipe carries no asset of its own — but a\ngenerated image and a decoded one behave identically from this point on.
", "api": [ { "name": "Card", "doc": null }, { "name": "ColorUtils", "doc": null }, { "name": "Component", "doc": null }, { "name": "Gap", "doc": null }, { "name": "Image", "doc": null }, { "name": "ImageView", "doc": "/docs/ui/widgets/imageview" }, { "name": "Relative", "doc": null }, { "name": "Styles", "doc": null }, { "name": "Widgets", "doc": null } ], "files": [ { "path": "dev/cf/recipe/R26Images.java", "name": "R26Images.java", "code": "package dev.cf.recipe;\n\nimport dev.crossfly.ui.*;\nimport dev.crossfly.ui.color.ColorUtils;\nimport dev.crossfly.ui.graphics.*;\nimport dev.crossfly.ui.image.Image;\nimport dev.crossfly.ui.layout.*;\nimport dev.crossfly.ui.style.*;\n\nimport static dev.crossfly.ui.Widgets.*;\n\n/**\n * Images, and the two questions that come up before the picture does.\n *\n *How does it fill its box? {@link ImageView.ImageSize} is the whole answer, and picking\n * wrong is the most visible mistake in an app: a portrait photo stretched into a landscape tile is\n * noticed by everybody and reported by nobody, because it looks like a bad photo rather than a bug.\n * Cropping to fill is almost always right for a photo; fitting inside is almost always right for a\n * logo.
\n *\n *Where does the image come from? An app's own assets, or bytes it was handed — a camera\n * capture, a database blob, a download. Both end up as an {@link Image}, and neither belongs in\n * {@code onPaint}: decoding is expensive, and doing it per frame is the classic reason a list\n * stutters exactly where the pictures are.
\n *\n *Drawn here rather than loaded from a file, so the recipe carries no asset of its own — but a\n * generated image and a decoded one behave identically from this point on.
\n */\npublic class R26Images extends Recipe\n{\n public String title()\n {\n return \"Images\";\n }\n\n public String note()\n {\n return \"Decode once, keep the Image, reuse it. Loading inside onPaint or inside a list's bind\"\n + \" step is what makes scrolling stutter where the pictures are.\";\n }\n\n public void build(Component body) throws Exception\n {\n // Made once, held, reused by all three views below — the point of the recipe.\n Image swatch = gradient(240, 160);\n\n // The names repay one careful reading, because two of them are the opposite of what they\n // sound like. RATIO fits the whole picture INSIDE the box; FIT scales until it COVERS the\n // box and crops what hangs over. Guessing between those two is how a portrait photo ends up\n // letterboxed in a tile that had room to crop it properly.\n show(body, \"RATIO — the whole picture, inside the box\", swatch, ImageSize.RATIO);\n show(body, \"FIT — covers the box, crops the overflow\", swatch, ImageSize.FIT);\n show(body, \"STRETCH — fills by distorting. Almost never right\", swatch, ImageSize.STRETCH);\n }\n\n private void show(Component body, String caption, Image img, ImageSize size)\n throws Exception\n {\n Card c = new Card();\n c.add(LAY_AUTO, label(caption, 1f, true, Styles.textColor, Position.START));\n ImageView v = new ImageView(img, size);\n v.getStyle()\n .autoHeight(Relative.ofFont(6f));\n c.add(LAY_AUTO, outgap(v, 0, .4f, 0, 0));\n c.getStyle()\n .outgap(Gap.ofFont(0, 0, 0, .6f));\n body.add(LAY_AUTO, c);\n }\n\n /**\n * Builds an image in memory from the theme's own colours.\n *\n *An {@code Image} is pixels; where they came from stops mattering the moment you have one.\n * The same object could have arrived from {@code PhotoPicker}, from a SQLite blob or from a\n * download, and every line after this one would be unchanged.
\n */\n private static Image gradient(int w, int h) throws Exception\n {\n Image img = Image.createSurface(w, h);\n int[] px = new int[w * h];\n int from = Styles.primaryColor.color(), to = tertiary().color();\n for (int y = 0; y < h; y++)\n {\n int rowColor = ColorUtils.lerpColor(from, to, y / (float) h);\n for (int x = 0; x < w; x++)\n // Diagonal bands, so cropping and stretching are both obvious at a glance.\n px[y * w + x] = ((x + y) / 18) % 2 == 0 ? rowColor\n : ColorUtils.lerpColor(rowColor, Styles.backColor.color(), .35f);\n }\n img.setPixels(px);\n // Pixels written, texture stale: applyChanges is what pushes them to the GPU. Forgetting it\n // gives you an image that is correct in memory and blank on screen.\n img.applyChanges();\n return img;\n }\n}\n" } ], "lines": 97, "sharedFiles": [ { "path": "dev/cf/recipe/Recipe.java", "name": "Recipe.java", "code": "package dev.cf.recipe;\n\nimport dev.cf.*;\nimport dev.crossfly.ui.*;\nimport dev.crossfly.ui.graphics.*;\nimport dev.crossfly.ui.layout.*;\nimport dev.crossfly.ui.skin.*;\nimport dev.crossfly.ui.style.*;\n\nimport static dev.crossfly.ui.Widgets.*;\n\n/**\n * Base of a recipe: one screen that shows one thing, and nothing else.\n *\n *A recipe is not a sample. A sample shows a component with all its knobs; a recipe answers a\n * question somebody actually has — \"how do I put a filter sheet over a list?\", \"how do I make this\n * follow the theme?\" — in as few lines as it takes, so the answer can be read in one screen and\n * copied without editing.
\n *\n *That is the whole design constraint: the boilerplate lives here, the substance lives in the\n * subclass. A recipe that spends twenty lines building a title bar teaches the title bar.
\n *\n *Write one as:
\n *\n *\n * public class MyRecipe extends Recipe\n * {\n * public String title() { return \"What this shows\"; }\n * public String note() { return \"The one sentence worth knowing.\"; }\n *\n * public void build(Component body) throws Exception\n * {\n * body.add(LAY_AUTO, new Button(\"Tap\"));\n * }\n * }\n * \n */\npublic abstract class Recipe extends SampleWindow implements Described\n{\n @Override\n public abstract String title();\n\n /**\n * The one thing a reader should take away — printed above the recipe, in caption tone.\n *\n * @return the note, or null for none\n */\n @Override\n public String note()\n {\n return null;\n }\n\n /**\n * Builds the recipe.\n *\n * @param body a vertical, scrollable container with sensible padding — add to it and stop\n * @throws Exception when building fails\n */\n public abstract void build(Component body) throws Exception;\n\n @Override\n public void onAdd(boolean firstTime) throws Exception\n {\n addTopBar(title());\n\n // The page, not the surface. addTopBar just set fullscreenColor to the surface,\n // and on a white page a white card has no edges — see Tones.page(). Re-derived on restyle so\n // a dark-mode flip does not leave the light page behind.\n fullscreenColor = Tones.page();\n onRestyle(() -> fullscreenColor = Tones.page());\n\n contents.setLayout(new VerticalLayout(Position.START, Position.START));\n contents.getStyle()\n .ingap(Gap.ofFont(1f, 1f, 1f, 1f));\n\n String n = note();\n if (n != null)\n contents.add(LAY_AUTO, outgap(nota(n), 0, 0, 0, 1f));\n\n Component body = new Component();\n body.setLayout(new VerticalLayout(Position.START, Position.START));\n body.setScrollable(ScrollDirection.VERTICAL);\n body.testTag(\"recipe.body\");\n contents.add(LAY_FILL, body);\n build(body);\n if (pinned != null)\n {\n // Measured again once its labels have sizes: the band's AUTO height is taken in the first\n // layout, before them, and on the iPhone it showed only its first line - the odometer's\n // \"No text recognizer on this device.\" was set and never seen (17/10/2026).\n final Component band = pinned;\n onUI(band::invalidateMeasure);\n }\n if (pinned != null)\n body.add(LAY_AUTO, new Component()\n {\n @Override\n public int getAutoHeight()\n {\n // Room for the last row to scroll clear of the floating band.\n return pinned.getAutoHeight();\n }\n });\n }\n\n /**\n * The note, as a tinted band rather than three lines of grey.\n *\n * It is the one sentence the reader is meant to leave with, and it used to be the least\n * legible thing on the screen: caption-coloured, caption-sized, indistinguishable from the\n * captions further down that are only labels. A tone and a glyph cost nothing here — nobody has\n * to read the band to know what it is.
\n *\n * @param n the note text\n * @return the band\n * @throws Exception when building fails\n */\n /**\n * Pins {@code c} to the bottom of the screen, in a band that FLOATS over the scrolling body: it\n * stays on screen however far the body is scrolled, and the body scrolls underneath it. That is the\n * place a recipe says what just happened. An answer at the top of the body went out of view as soon\n * as the person scrolled down to the button that produced it (14/10/2026).\n *\n * The band is 80% OPAQUE (the surface at alpha 0xCC), as the user asked; it floats rather than\n * sitting below the body because a transparency with nothing behind it cannot be seen -- the first\n * version had the band under the body, and the person saw a plain bar. The body gets a spacer as\n * tall as the band at its end, so its last row can still scroll clear of it.\n *\n * @param c the component to pin, usually the answer label\n * @return {@code c}, to chain\n * @throws Exception if the layout refuses\n */\n protected \n * Provides common infrastructure:\n * \n *
\n *\n * Usage
\n * \n * public class MySample extends SampleWindow {\n * public void onAdd(boolean firstTime) throws Exception {\n * if (!firstTime) return;\n * initWindow();\n * addTopBar(\"My Sample\");\n * // ... add content\n * }\n * }\n * \n */\npublic abstract class SampleWindow extends Window\n{\n /** The main content area of the window, added by {@link #addTopBar(String, Button...)}, for subclasses to add their content into. */\n protected Component contents;\n\n // ─── Top bar ─────────────────────────────────────────────────────────────\n\n /**\n * Builds and adds a standard top bar with a back (←) button on the left,\n * a centered title, and any optional extra buttons on the right.\n *\n * @param title the text shown in the bar\n * @param rightButtons zero or more icon buttons placed aligned to the right\n * @throws Exception if component construction fails\n */\n protected void addTopBar(String title, Button... rightButtons) throws Exception\n {\n fullscreenColor = Styles.backColor.color();\n setLayout(new VerticalLayout());\n add(0f, buildTopBar(title, rightButtons));\n add(LAY_FILL, contents = new Component());\n contents.getStyle()\n .ingap(Gap.ofFont(0, .5f, 0, .5f));\n }\n\n /**\n * Same as {@link #addTopBar(String, Button...)}, but returns the bar component\n * instead of adding it, for callers that need to position it manually.\n *\n * @param title the bar title\n * @param rightButtons optional right-side icon buttons\n * @return the assembled top-bar {@link Component}\n * @throws Exception if component construction fails\n */\n protected Component buildTopBar(String title, Button... rightButtons) throws Exception\n {\n Button btBack = barButton(\"\\ue5c4\", this::hide); // arrow_back\n btBack.testTag(\"sample.back\");\n // Padded on every side, like the bar's right buttons: with none above and below, the target\n // was the arrow itself, too small to hit on a small phone (iPhone 5s, 17/10/2026).\n btBack.getStyle()\n .ingap(Gap.ofFont(.75f))\n .outgap(Gap.ofFont(0, 0, .25f, 0));\n\n Component bar = new Component().style(barStyle);\n bar.setLayout(new GridLayout(Position.START, Position.CENTER));\n\n int n = 2 + rightButtons.length;\n Object[] params = new Object[n * 2];\n params[0] = 0f;\n params[1] = 1f;\n for (int i = 0; i < rightButtons.length; i++)\n params[2 + i] = 0f;\n params[n] = btBack;\n params[n + 1] = new Label(title).style(barTitleStyle);\n for (int i = 0; i < rightButtons.length; i++)\n {\n params[n + 2 + i] = rightButtons[i];\n rightButtons[i].getStyle()\n .ingap(Gap.ofFont(.75f));\n }\n\n bar.add(params);\n return bar;\n }\n\n /**\n * Creates a standard bar icon button (transparent, white icon, pressed feedback).\n *\n * @param materialIcon the Material Icon unicode codepoint string\n * @param action the action to run when the button is tapped\n * @return the configured {@link Button}\n */\n protected Button barButton(String materialIcon, Runnable action)\n {\n return new Button(new MaterialIcon(materialIcon)).style(barButtonNormal)\n .pressedStyle(barButtonPressed)\n .onAction(e -> action.run());\n }\n}\n"
}
],
"page": "https://crossfly.dev/examples/images",
"run": "https://crossfly.dev/playground/index.html?ex=images",
"runLocally": "gradlew lwjgl3:run --args=\"classname dev.cf.recipe.R26Images\"",
"license": "See crossfly.dev for licensing. The code is published to be copied into your own project."
}