Imágenes (`ImageView`)

ImageView muestra un Image dentro de un componente, con control de escala (ImageSize) y alineación.

Ejemplo completo (copiar, pegar y ejecutar)

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

/** Pantalla principal ejecutable. Apunta el launcher (classname) y corre: gradlew :lwjgl3:run */
public class MainWindow extends Window
{
   @Override
   public void onShow() throws Exception
   {
      super.onShow();
      setLayout(new VerticalLayout());

      // Cargar con fallback: new Image(path) lanza ImageException/IOException (comprobadas).
      Image logo;
      try
      {
         logo = new Image("images/logo.png");   // ruta de recurso de la app
      }
      catch (ImageException | IOException e)
      {
         Debug.log("falha ao carregar: " + e);
         return;   // aborta el montaje si la imagen falta
      }

      // Mostrar con ImageView, manteniendo la proporción (RATIO) y centrado.
      ImageView foto = new ImageView(logo, ImageSize.RATIO)
         .alignX(Position.CENTER)
         .alignY(Position.CENTER);
      add(0.4f, foto);   // 40% de la altura (VerticalLayout)

      // Imagen de fondo de la propia ventana (método del Component, no un ImageView).
      addBackgroundImage(logo, ImageSize.FIT, 0.5f, 0.5f);   // centrada, cubriendo
   }
}

Los fragmentos siguientes muestran solo el núcleo (lo que va dentro de onShow()). Para ejecutar, colócalos en el esqueleto MainWindow de arriba.

Cargar un `Image`

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

Constructores útiles: new Image(String path), new Image(byte[] bytes), new Image(InputStream), new Image(int w, int h) (bitmap vacío para dibujar). Todos pueden lanzar ImageException (y el de path/stream también IOException).

Mostrar

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

Constructores: ImageView(), ImageView(Image), ImageView(Image, ImageSize). Fluido: .image(Image), .imageSize(ImageSize), .alignX(Position), .alignY(Position).

Modos de escala (`ImageSize`)

Modo	Comportamiento
`ORIGINAL`	tamaño natural en píxeles
`RATIO`	cabe dentro del componente manteniendo la proporción (puede sobrar espacio)
`FIT`	cubre el componente manteniendo la proporción (puede recortar)
`STRETCH`	estira para llenar, ignorando la proporción
`FIT_WIDTH` / `FIT_HEIGHT`	ajusta por el ancho / alto, manteniendo la proporción
`FIT_HALF_WIDTH` / `FIT_HALF_HEIGHT`	mitad del ancho / alto

Regla práctica: RATIO = “aparecer entera” (letterbox); FIT = “llenar sin distorsionar” (recorta el excedente); STRETCH = llenar distorsionando (evítalo en fotos).

Imagen de fondo (de un componente/pantalla)

No es un ImageView — es un método del propio Component:

janela.addBackgroundImage(fundo, ImageSize.FIT, 0.5f, 0.5f);   // centrada, cubriendo
// o dimensionada por Relative:
janela.addBackgroundImage(marca, Relative.ofScreen(0.3f), null, 0.5f, 0.9f);

centerX/centerY son 0–1 (posición relativa del centro de la imagen).

Buenas prácticas

Siempre maneja ImageException/IOException al cargar — son checadas.
Fotos: RATIO (mostrar todo) o FIT (llenar recortando). Evita STRETCH (distorsiona).
Carga imágenes grandes fuera del paint thread y vuelve con Component.onUI(...).

Errores comunes

No capturar las excepciones de new Image(...) → no compila.
Usar STRETCH en foto de persona (distorsión); usa FIT.
Confundir RATIO (cabe dentro) con FIT (cubre y recorta).

Véase también

Dibujo personalizado · Whiteboard
Catálogo: ImageView · Referencia: Capítulo 18 — Imágenes

Imágenes (ImageView)