{
  "id": "webview",
  "kind": "recipe",
  "tags": [
    "device",
    "media"
  ],
  "title": "Embedded web page",
  "note": "A native browser over the canvas, at this component's rect. On the web it is an <iframe>, and script only reaches a page from your own origin.",
  "className": "R33WebView",
  "package": "dev.cf.recipe",
  "doc": "<p>Embedding a web page — the third native surface, and the one with a limit worth knowing.</p>\n\n<p><code>WebContainer</code> puts the platform's own browser over the GL canvas at this component's\nrect: <code>WebView</code> on Android, <code>WKWebView</code> on iOS, the system engine on Windows, a\n<code>WKWebView</code> through JNA on macOS, and — since 17/09/2026 — an <code><iframe></code> on the web,\nwhich had been the only one of the five without one.</p>\n\n<p><b>The limit is on the web and it is not a defect.</b> The four native backends can inject\nscript into any page they load. A browser cannot: reaching into a frame from another origin\nraises <code>SecurityError</code>, by design, with no flag that changes it. So\n<code>evaluateJavaScript</code> works on a page from the app's own origin and is refused\n— out loud, in the log — on anything else. The page talks back the way a framed page always has,\nwith <code>postMessage</code>, and it arrives at the same listener the native bridge feeds.</p>\n\n<p>Two more things that bite whoever embeds one for the first time, on every platform: a native\nsurface does not clip to a scrolling parent and shows as a blank rectangle during a window\ntransition; and plenty of sites refuse to be framed at all (<code>X-Frame-Options</code>), which looks\nexactly like a page that did not load, because from outside the frame it is indistinguishable.</p>",
  "api": [
    {
      "name": "Button",
      "doc": "/docs/ui/widgets/button"
    },
    {
      "name": "Capability",
      "doc": null
    },
    {
      "name": "Card",
      "doc": null
    },
    {
      "name": "Component",
      "doc": null
    },
    {
      "name": "Debug",
      "doc": null
    },
    {
      "name": "Device",
      "doc": null
    },
    {
      "name": "GridLayout",
      "doc": null
    },
    {
      "name": "Label",
      "doc": "/docs/ui/widgets/label"
    },
    {
      "name": "PlatformUtils",
      "doc": null
    },
    {
      "name": "Screen",
      "doc": null
    },
    {
      "name": "Styles",
      "doc": null
    },
    {
      "name": "VerticalLayout",
      "doc": null
    },
    {
      "name": "WebContainer",
      "doc": "/docs/ui/widgets/webcontainer"
    },
    {
      "name": "Widgets",
      "doc": null
    }
  ],
  "files": [
    {
      "path": "dev/cf/recipe/R33WebView.java",
      "name": "R33WebView.java",
      "code": "package dev.cf.recipe;\n\nimport dev.cf.Tones;\n\nimport dev.crossfly.Capability;\nimport dev.crossfly.PlatformUtils;\nimport dev.crossfly.util.Debug;\nimport dev.crossfly.ui.*;\nimport dev.crossfly.ui.layout.*;\nimport dev.crossfly.ui.style.*;\n\nimport static dev.crossfly.ui.Widgets.*;\n\n/**\n * Embedding a web page — the third native surface, and the one with a limit worth knowing.\n *\n * <p>{@link WebContainer} puts the platform's own browser over the GL canvas at this component's\n * rect: {@code WebView} on Android, {@code WKWebView} on iOS, the system engine on Windows, a\n * {@code WKWebView} through JNA on macOS, and — since 17/09/2026 — an {@code <iframe>} on the web,\n * which had been the only one of the five without one.</p>\n *\n * <p><b>The limit is on the web and it is not a defect.</b> The four native backends can inject\n * script into any page they load. A browser cannot: reaching into a frame from another origin\n * raises {@code SecurityError}, by design, with no flag that changes it. So\n * {@link WebContainer#evaluateJavaScript} works on a page from the app's own origin and is refused\n * — out loud, in the log — on anything else. The page talks back the way a framed page always has,\n * with {@code postMessage}, and it arrives at the same listener the native bridge feeds.</p>\n *\n * <p>Two more things that bite whoever embeds one for the first time, on every platform: a native\n * surface does not clip to a scrolling parent and shows as a blank rectangle during a window\n * transition; and plenty of sites refuse to be framed at all ({@code X-Frame-Options}), which looks\n * exactly like a page that did not load, because from outside the frame it is indistinguishable.</p>\n */\npublic class R33WebView extends Recipe\n{\n   private Label answer;\n   private WebContainer web;\n\n   public String title()\n   {\n      return \"Embedded web page\";\n   }\n\n   public String note()\n   {\n      return \"A native browser over the canvas, at this component's rect. On the web it is an\"\n         + \" <iframe>, and script only reaches a page from your own origin.\";\n   }\n\n   public void build(Component body) throws Exception\n   {\n      boolean has = PlatformUtils.isSupported(Capability.WEB_VIEW);\n\n      answer = label(has ? \"Ready.\" : \"This platform has no embedded web view.\", 1f, false,\n         has ? Styles.captionColor : Tones.danger(), Position.START);\n      answer.testTag(\"webview.answer\");\n      // Pinned below the scrolling body, so the answer stays in view (see Recipe.pin).\n      pin(answer);\n\n      if (!has)\n      {\n         Card c = new Card();\n         c.setLayout(new VerticalLayout(Position.START, Position.START));\n         c.add(LAY_AUTO, label(\"No WEB_VIEW on \" + dev.crossfly.device.Device.platform, 1.2f, true,\n            Styles.textColor, Position.START));\n         c.add(LAY_AUTO, label(\"Ask the capability before building a WebContainer: its constructor\"\n            + \" refuses by name, which is what lets an app open the page in the system browser\"\n            + \" instead.\", 1f, false, Styles.captionColor, Position.START));\n         body.add(LAY_AUTO, c);\n         return;\n      }\n\n      web = new WebContainer();\n      // The page reaches the app through one listener on every platform: the native backends inject\n      // window.DesktopBridge, and the web build installs the same name into a same-origin page.\n      web.setFormSubmitListener(data -> said(\"the page said: \" + data));\n      body.add(.6f, web);\n\n      Component buttons = new Component();\n      buttons.setLayout(new GridLayout(Position.START, Position.CENTER));\n      buttons.add(.33f, .33f, .33f,\n         button(\"Load\", \"webview.load\", () ->\n         {\n            web.show(\"https://example.com\");\n            said(\"Loading example.com…\");\n         }),\n         button(\"Ask the page\", \"webview.ask\", () ->\n         {\n            // On the four native platforms this comes back through the bridge. On the web it is\n            // refused, because example.com is another origin -- and the refusal is logged rather\n            // than being the silence that would send you debugging the page.\n            web.evaluateJavaScript(\"window.DesktopBridge && window.DesktopBridge.onFormSubmit(\"\n               + \"'title=' + document.title)\");\n            said(\"Asked. On the web this is refused unless the page is from this origin.\");\n         }),\n         button(\"Hide\", \"webview.hide\", () ->\n         {\n            web.hide();\n            said(\"Hidden — the page stays loaded.\");\n         }));\n      body.add(LAY_AUTO, buttons);\n   }\n\n   private Button button(String text, String tag, Runnable go) throws Exception\n   {\n      Button b = new Button(text);\n      b.testTag(tag);\n      b.onAction(e -> go.run());\n      return b;\n   }\n\n   private void said(String what)\n   {\n      Debug.log(\"[webview] \" + what);\n      answer.setText(what);\n      answer.invalidateMeasure(); // the pinned band must grow with it (see Recipe.pin)\n      Screen.repaint();\n   }\n}\n"
    }
  ],
  "lines": 120,
  "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 <b>recipe</b>: one screen that shows one thing, and nothing else.\n *\n * <p>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.</p>\n *\n * <p>That is the whole design constraint: <b>the boilerplate lives here, the substance lives in the\n * subclass.</b> A recipe that spends twenty lines building a title bar teaches the title bar.</p>\n *\n * <p>Write one as:</p>\n *\n * <pre>\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 * </pre>\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    * <p>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.</p>\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    * <p>\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 extends Component> 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 * <p>\n * Provides common infrastructure:\n * <ul>\n *   <li>Shared color palette and styles from {@link dev.cf.sample.CrossFlySamplesColors}</li>\n *   <li>{@link #addTopBar(String, Button...)} — standard deep-indigo top bar with back button</li>\n *   <li>{@link #barButton(String, Runnable)} — helper to create icon buttons for the bar</li>\n * </ul>\n *\n * <h3>Usage</h3>\n * <pre>\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 * </pre>\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/webview",
  "run": "https://crossfly.dev/playground/index.html?ex=webview",
  "runLocally": "gradlew lwjgl3:run --args=\"classname dev.cf.recipe.R33WebView\"",
  "license": "See crossfly.dev for licensing. The code is published to be copied into your own project."
}