{ "id": "map", "kind": "recipe", "tags": [ "device" ], "title": "A map with pins", "note": "OSM needs no API key, so a map works the moment you write it. Opens in a window of its own — a native view inside a scrolling page floats over everything around it.", "className": "R25Map", "package": "dev.cf.recipe", "doc": "

A real map with pins on it, and the two things that make a map different from every other widget.

\n\n

It is a native view on top of the GL canvas, not a component inside it. It does not\nscroll with a parent, does not clip to one, and does not take part in a screen transition — a\nfade over a map shows a black rectangle for the whole animation. So a map gets a rectangle of its\nown and every control you want over it goes outside that rectangle, in ordinary\ncomponents.

\n\n

The engine is a constructor argument. Changing provider means building a new\nMapContainer — there is no setter, and there should not be one. OSM needs no key\nand is the right default for anything that is not shipping; GOOGLE needs\nMapContainer.googleMapsKey set before the container is built.

\n\n

Opened on a button rather than built into this screen, on purpose: a native view inside a\nscrolling recipe list would float over the recipes above and below it.

", "api": [ { "name": "Button", "doc": "/docs/ui/widgets/button" }, { "name": "Component", "doc": null }, { "name": "Debug", "doc": null }, { "name": "Gap", "doc": null }, { "name": "GridLayout", "doc": null }, { "name": "LatLon", "doc": null }, { "name": "Map", "doc": null }, { "name": "MapContainer", "doc": null }, { "name": "MapPin", "doc": null }, { "name": "MaterialIcon", "doc": null }, { "name": "Styles", "doc": null }, { "name": "VerticalLayout", "doc": null }, { "name": "Widgets", "doc": null }, { "name": "Window", "doc": null } ], "files": [ { "path": "dev/cf/recipe/R25Map.java", "name": "R25Map.java", "code": "package dev.cf.recipe;\n\nimport dev.cf.Tones;\n\nimport dev.crossfly.map.*;\nimport dev.crossfly.ui.*;\nimport dev.crossfly.ui.color.*;\nimport dev.crossfly.ui.graphics.*;\nimport dev.crossfly.ui.layout.*;\nimport dev.crossfly.ui.style.*;\nimport java.util.ArrayList;\nimport java.util.List;\n\nimport static dev.crossfly.ui.Widgets.*;\n\n/**\n * A real map with pins on it, and the two things that make a map different from every other widget.\n *\n *

It is a native view on top of the GL canvas, not a component inside it. It does not\n * scroll with a parent, does not clip to one, and does not take part in a screen transition — a\n * fade over a map shows a black rectangle for the whole animation. So a map gets a rectangle of its\n * own and every control you want over it goes outside that rectangle, in ordinary\n * components.

\n *\n *

The engine is a constructor argument. Changing provider means building a new\n * {@link MapContainer} — there is no setter, and there should not be one. {@code OSM} needs no key\n * and is the right default for anything that is not shipping; {@code GOOGLE} needs\n * {@code MapContainer.googleMapsKey} set before the container is built.

\n *\n *

Opened on a button rather than built into this screen, on purpose: a native view inside a\n * scrolling recipe list would float over the recipes above and below it.

\n */\npublic class R25Map extends Recipe\n{\n /** A few coordinates to plot. Real ones come from your store — with the nulls filtered out. */\n private static final double[][] WHERE = { { 53.7996, -1.5491 }, { 51.2194, 4.4025 },\n { 41.1579, -8.6291 }, { 45.0703, 7.6869 }, { 55.6050, 13.0038 }, { 51.4545, -2.5879 } };\n private static final String[] WHO = { \"Northgate\", \"Bellamy\", \"Kestrel\", \"Halden & Roe\",\n \"Ironvale\", \"Meridian\" };\n\n public String title()\n {\n return \"A map with pins\";\n }\n\n public String note()\n {\n return \"OSM needs no API key, so a map works the moment you write it. Opens in a window of\"\n + \" its own — a native view inside a scrolling page floats over everything around it.\";\n }\n\n public void build(Component body) throws Exception\n {\n body.add(LAY_AUTO, outgap(label(\"Six suppliers, plotted from coordinates. The pins are data;\"\n + \" the map only draws them.\", 1f, false, Styles.captionColor, Position.START), 0, 0, 0,\n 1f));\n\n Button open = Tones.action(\"Open the map\");\n open.testTag(\"map.open\");\n open.onAction(c -> new MapScreen().show());\n body.add(LAY_AUTO, open);\n }\n\n /** The map, in a window of its own, with the app's chrome kept outside its rectangle. */\n private static class MapScreen extends Window\n {\n private MapContainer container;\n\n @Override\n public void onAdd(boolean firstTime) throws Exception\n {\n if (!firstTime)\n return;\n fullscreenColor = Styles.backColor.color();\n setLayout(new VerticalLayout(Position.START, Position.START));\n\n Component bar = new Component();\n bar.setLayout(new GridLayout(Position.START, Position.CENTER));\n bar.getStyle()\n .ingap(Gap.ofFont(.6f, .5f, .6f, .5f));\n Button back = new Button(MaterialIcon.of(0xE5C4, 1.4f));\n back.onAction(c -> hide());\n bar.add(0f, 1f, back, outgap(label(\"Suppliers\", 1.5f, true, Styles.textColor,\n Position.START), .6f, 0, 0, 0));\n add(0f, bar);\n\n // OSM: no key, no account, works offline against its own tiles cache. The callback fires\n // when the native view is ready — plotting before that plots into nothing.\n container = new MapContainer(Map.MapEngine.OSM, 0, this::plot);\n add(LAY_FILL, container);\n }\n\n private void plot()\n {\n try\n {\n final List pins = new ArrayList<>();\n double lat = 0, lon = 0;\n for (int i = 0; i < WHERE.length; i++)\n {\n pins.add(new MapPin().position(WHERE[i][0], WHERE[i][1])\n .title(WHO[i])\n .snippet(\"Supplier\"));\n lat += WHERE[i][0];\n lon += WHERE[i][1];\n }\n\n // batch(): every add is a call across to the native view, and six of them is six\n // round-trips and six redraws. Inside a batch it is one. At six pins nobody notices;\n // at six hundred it is the difference between a map and a freeze.\n container.map.batch(() -> container.map.add(pins.toArray(new MapPin[0])));\n\n // Open on the middle of what was plotted, not on a fixed point: a map that opens\n // somewhere the data is not makes the user pan before it tells them anything.\n container.map.centerOnLocation(new LatLon(lat / WHERE.length, lon / WHERE.length), 4);\n }\n catch (Exception e)\n {\n dev.crossfly.util.Debug.handle(e);\n }\n }\n }\n}\n" } ], "lines": 124, "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 T pin(T c) throws Exception\n {\n Component band = new Component();\n band.setLayout(new VerticalLayout(Position.START, Position.START));\n band.style(Skin.get()\n .card()\n .backColor(Styles.backColor.withAlpha(0xCC))\n .borderColor(Styles.borderColor.withAlpha(0x33))\n .borderRadius(0)\n .shadow(0, 0, 0, 0)\n .ingap(Gap.ofFont(1f, 1f, 1f, 1.2f))\n .outgap(Gap.ofFont(0)));\n band.add(LAY_AUTO, c);\n // Floated: positioned at the bottom, full width, over whatever the body has there.\n band.setRelativeBounds(Relative.START, Relative.END, Relative.FULL, Relative.AUTO);\n contents.add(LAY_AUTO, band);\n pinned = band;\n return c;\n }\n\n /** The floating band {@link #pin} made, or null; the body ends in a spacer as tall as it. */\n private Component pinned;\n\n private Component nota(String n) throws Exception\n {\n Component band = new Component();\n band.setLayout(new GridLayout(Position.START, Position.START));\n band.style(Skin.get()\n .card()\n .backColor(Tones.accent().withAlpha(0x16))\n .borderColor(Tones.accent().withAlpha(0x4A))\n .shadow(0, 0, 0, 0)\n .outgap(Gap.ofFont(0)));\n // 0xE88E is the outlined \"info\". The glyph column hugs; the text takes the rest and wraps.\n // The weights are GridLayout's own — 0f hugs, 1f takes what is left. LAY_FILL belongs to the\n // vertical and horizontal layouts and means nothing here: it collapsed the text to nothing.\n band.add(LAY_AUTO, 1f, matglyph(0xE88E, Tones.accent(), 1.05f),\n outgap(label(n, 1f, false, secondary(), Position.START), .5f, 0, 0, 0));\n return band;\n }\n}\n" }, { "path": "dev/cf/SampleWindow.java", "name": "SampleWindow.java", "code": "package dev.cf;\n\nimport dev.crossfly.ui.*;\nimport dev.crossfly.ui.graphics.*;\nimport dev.crossfly.ui.layout.*;\nimport dev.crossfly.ui.style.*;\n\nimport static dev.cf.sample.CrossFlySamplesColors.*;\n\n/**\n * Base class for all CrossFly sample windows.\n *

\n * Provides common infrastructure:\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/map", "run": "https://crossfly.dev/playground/index.html?ex=map", "runLocally": "gradlew lwjgl3:run --args=\"classname dev.cf.recipe.R25Map\"", "license": "See crossfly.dev for licensing. The code is published to be copied into your own project." }