WebContainer

WebContainer é um widget que embute uma webview nativa (conteúdo HTML/JavaScript) dentro da sua UI CrossFly. Ele é um wrapper fino: não desenha nada próprio — delega tudo à IWebView que a plataforma fornece via PlatformUtils.instance.createWebView(). Serve para exibir uma página, um formulário HTML ou um painel web como se fosse um componente comum da tela.

⚠️ Honestidade sobre disponibilidade: WebContainer só funciona onde existe uma IWebView nativa (Android, iOS, Desktop). Não há implementação concreta de IWebView nesta base de código nem no alvo Web/TeaVM — createWebView() retorna null em plataformas sem suporte, e o construtor de WebContainer então lança UnsupportedOperationException. Num build Web/WebGL, prefira abrir uma página externa (view(url)) em vez de embutir uma webview.

🔴 · Pacote: dev.crossfly.ui · Estende: Component (implementa Runnable) · Delega para: IWebView

Quando usar

Exibir conteúdo web (HTML/JS) dentro do app, numa plataforma com webview nativa (Android/iOS/Desktop).
Integrar um formulário HTML e capturar o envio via setFormSubmitListener.

Quando NÃO usar

Para conteúdo estático simples (texto/imagem) → use os widgets nativos (chartview, labels, imagens) em vez de carregar uma página.

Aparência

WebContainer não pinta pixels próprios: a webview nativa do sistema é sobreposta à área do componente. A visibilidade é coordenada automaticamente em onPaint — a webview aparece apenas quando a janela pai está no topo (isTopMost()) e some caso contrário.

Exemplo completo (copiar, colar e rodar)

WebContainer só funciona onde há uma IWebView nativa. O exemplo detecta o suporte com PlatformUtils.instance.createWebView() != null antes de criar o container (evitando o UnsupportedOperationException do construtor) e, sem suporte (ex.: alvo Web/TeaVM), degrada abrindo a página externamente com view(url).

package com.exemplo;

import dev.crossfly.PlatformUtils;

import dev.crossfly.ui.*;
import dev.crossfly.ui.layout.*;

/** Tela principal executável. Aponte o launcher (classname) e rode: gradlew :lwjgl3:run */
public class MainWindow extends Window
{
   @Override
   public void onShow() throws Exception
   {
      super.onShow();
      setLayout(new VerticalLayout());

      String url = "https://example.com";

      // Só cria o WebContainer se a plataforma fornecer uma IWebView nativa.
      if (PlatformUtils.instance.createWebView() != null)
      {
         WebContainer browser = new WebContainer();
         browser.show(url);
         add(LAY_FILL, browser);
      }
      else
      {
         // Alvo Web/TeaVM (sem webview embutida): abre a página externamente.
         add(LAY_AUTO, new Label("Sem webview nativa — abrindo externamente…"));
         PlatformUtils.instance.view(url);
      }
   }
}

Os trechos abaixo mostram só o miolo (o que vai dentro de onShow()). Para rodar, coloque-os no esqueleto MainWindow acima.

Uso básico

WebContainer browser = new WebContainer();   // pode lançar UnsupportedOperationException
browser.show("https://example.com");
container.add(LAY_FILL, browser);

Construtores

Construtor	Descrição
`WebContainer()`	Obtém a webview nativa via `PlatformUtils.instance.createWebView()` e inicia invisível. Lança `UnsupportedOperationException` se a plataforma não fornecer uma `IWebView`.

Propriedades e personalização

Método	Tipo	O que faz
`show(String url)`	`void`	Carrega e exibe a URL na webview.
`hide()`	`void`	Esconde a webview mantendo o estado da página.
`setVisible(boolean)`	`void`	`true` = `show(null)` (mantém URL/estado atual); `false` = `hide()`.
`isVisible()`	`boolean`	Se a webview está visível.
`evaluateJavaScript(String script)`	`void`	Executa JavaScript na página.
`setFormSubmitListener(IWebView.FormSubmitListener)`	`void`	Registra callback para captura de envios de formulário HTML.

A IWebView exige que as operações ocorram na render thread (paint thread). Volte a ela com Component.onUI(...) se estiver chamando show/evaluateJavaScript de outra thread.

Callbacks e eventos

Callback	Quando dispara
`IWebView.FormSubmitListener` (via `setFormSubmitListener`)	Ao enviar um formulário HTML dentro da página embutida.

WebContainer não usa onAction/onClick — a interação acontece dentro da página web. O único gancho de app é o listener de submit de formulário.

Estados

visível / oculto: gerenciado por show/hide/setVisible e, automaticamente, pela posição da janela (a webview some quando a janela pai não está no topo).
removido: no onRemove, view.removeView() é chamado e a IWebView não pode ser reutilizada — para reexibir, crie um novo WebContainer.

Formulário HTML com captura de envio (plataforma com webview)

WebContainer form = new WebContainer();
form.setFormSubmitListener(dados -> processarEnvio(dados));  // IWebView.FormSubmitListener
form.show("https://meuservico/formulario.html");
container.add(LAY_FILL, form);

Degradação segura no alvo Web

// No build Web/TeaVM, createWebView() retorna null e o construtor lança.
try {
   WebContainer c = new WebContainer();
   c.show("https://example.com");
   container.add(LAY_FILL, c);
} catch (UnsupportedOperationException e) {
   // Sem webview embutida: abra a página externamente.
   PlatformUtils.instance.view("https://example.com");
}

Boas práticas

Encapsule a criação num try/catch de UnsupportedOperationException para degradar bem no alvo Web.

Erros comuns

Criar WebContainer em plataforma sem suporte: lança UnsupportedOperationException. Trate ou detecte antes.
Reutilizar após onRemove: a IWebView foi descartada (removeView()); crie uma nova instância.
Esperar embutir web no alvo Web/TeaVM: não há implementação; embutir webview ≠ ser um app web. Use view(url).

Veja também

Guia da área: ui/ · Receitas: cookbook/
Conceito (plataformas, threading de UI): concepts/
Componentes relacionados: locationview