# Imagens

> Carregar e exibir imagens com ImageView, os modos de escala (ImageSize) e imagens de fundo.

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

# Imagens (`ImageView`)

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

## Exemplo completo (copiar, colar e rodar)
```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

/** 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`
```java
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
```java
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`)
| Modo | Comportamento |
|---|---|
| `ORIGINAL` | tamanho natural em pixels |
| `RATIO` | **cabe dentro** do componente mantendo proporção (pode sobrar espaço) |
| `FIT` | **cobre** o componente mantendo proporção (pode **cortar**) |
| `STRETCH` | estica para preencher, **ignorando** a proporção |
| `FIT_WIDTH` / `FIT_HEIGHT` | ajusta pela largura / altura, mantendo proporção |
| `FIT_HALF_WIDTH` / `FIT_HALF_HEIGHT` | metade da largura / altura |

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