Imagens (ImageView)

ImageView exibe um Image dentro de um componente, com controle de escala (ImageSize) e alinhamento.

Exemplo completo (copiar, colar e rodar)

package com.exemplo;

import java.io.*;                     // IOException

import dev.crossfly.ui.*;
import dev.crossfly.ui.layout.*;
import dev.crossfly.ui.image.*;       // Image, ImageException
import dev.crossfly.util.*;           // Debug

/** 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());

      // Carregar com fallback: new Image(path) lança ImageException/IOException (checadas).
      Image logo;
      try
      {
         logo = new Image("images/logo.png");   // caminho de recurso do app
      }
      catch (ImageException | IOException e)
      {
         Debug.log("falha ao carregar: " + e);
         return;   // aborta a montagem se a imagem faltar
      }

      // Exibir com ImageView, mantendo proporção (RATIO) e centralizado.
      ImageView foto = new ImageView(logo, ImageSize.RATIO)
         .alignX(Position.CENTER)
         .alignY(Position.CENTER);
      add(0.4f, foto);   // 40% da altura (VerticalLayout)

      // Imagem de fundo da própria janela (método do Component, não um ImageView).
      addBackgroundImage(logo, ImageSize.FIT, 0.5f, 0.5f);   // centralizada, cobrindo
   }
}

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

Carregar um Image

Image logo;
try {
   logo = new Image("images/logo.png");   // caminho de recurso do app
} catch (ImageException | IOException e) {
   Debug.log("falha ao carregar: " + e);
   return;
}

Construtores úteis: new Image(String path), new Image(byte[] bytes), new Image(InputStream), new Image(int w, int h) (bitmap vazio para desenhar). Todos podem lançar ImageException (e o de path/stream também IOException).

Exibir

ImageView foto = new ImageView(logo, ImageSize.RATIO)
   .alignX(Position.CENTER)
   .alignY(Position.CENTER);
painel.add(0.4f, foto);   // 40% da altura (VerticalLayout)

Construtores: ImageView(), ImageView(Image), ImageView(Image, ImageSize). Fluent: .image(Image), .imageSize(ImageSize), .alignX(Position), .alignY(Position).

Modos de escala (ImageSize)

Regra prática: RATIO = “aparecer inteira” (letterbox); FIT = “preencher sem distorcer” (recorta o excedente); STRETCH = preencher distorcendo (evite em fotos).

Imagem de fundo (de um componente/tela)

Não é um ImageView — é um método do próprio Component:

janela.addBackgroundImage(fundo, ImageSize.FIT, 0.5f, 0.5f);   // centralizada, cobrindo
// ou dimensionada por Relative:
janela.addBackgroundImage(marca, Relative.ofScreen(0.3f), null, 0.5f, 0.9f);

centerX/centerY são 0–1 (posição relativa do centro da imagem).

Boas práticas

• Sempre trate ImageException/IOException ao carregar — são checadas.
• Fotos: RATIO (mostrar tudo) ou FIT (preencher recortando). Evite STRETCH (distorce).
• Carregue imagens grandes fora da paint thread e volte com Component.onUI(...).

Erros comuns

• Não capturar as exceções de new Image(...) → não compila.
• Usar STRETCH em foto de pessoa (distorção); use FIT.
• Confundir RATIO (cabe dentro) com FIT (cobre e corta).

Veja também

• Desenho customizado · Whiteboard
• Catálogo: ImageView · Referência: Capítulo 18 — Imagens