# Imágenes

> Cargar y mostrar imágenes con ImageView, los modos de escala (ImageSize) e imágenes de fondo.

Source: https://crossfly.dev/es/docs/ui/images-and-graphics/images — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# 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)
```java
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`
```java
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
```java
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`:
```java
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](/docs/ui/images-and-graphics/custom-drawing) · [Whiteboard](/docs/ui/images-and-graphics/whiteboard)
- Catálogo: [ImageView](/docs/ui/widgets/imageview) · Referencia: Capítulo 18 — Imágenes