# Como definir uma imagem de fundo em um Component

> Adicionar uma imagem de fundo a qualquer Component com addBackgroundImage e ImageSize.

Source: https://crossfly.dev/pt/docs/cookbook/images/imagem-de-fundo — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# Como definir uma imagem de fundo em um Component

**Propósito.** Desenhar uma imagem atrás do conteúdo de **qualquer** `Component` (uma tela, um painel,
um card), controlando como ela preenche a área e onde fica centrada. Diferente de um `ImageView`, a
imagem de fundo é pintada pelo próprio componente, atrás dos filhos.

## APIs usadas
- `void Component.addBackgroundImage(Image image, ImageSize imageSize, float centerX, float centerY)` — adiciona uma imagem de fundo. `centerX`/`centerY` são frações de 0 a 1 que posicionam a imagem dentro da sobra de espaço (`0.5, 0.5` = centralizada).
- `void Component.addBackgroundImage(Image image, Relative width, Relative height, float centerX, float centerY)` — variante com largura/altura relativas explícitas (via `Relative`), em vez de um `ImageSize`.
- `ImageSize` (enum, verificado em `UIConstants`): `ORIGINAL, RATIO, STRETCH, FIT, FIT_WIDTH, FIT_HEIGHT, FIT_HALF_WIDTH, FIT_HALF_HEIGHT`.

### Modos úteis para fundo (comportamento em `BackgroundImage.onPaint`)
- `FIT` — cobre **toda** a área preservando a proporção (pode extrapolar/cortar). É o modo típico para papel de parede.
- `RATIO` — cabe inteira dentro da área preservando a proporção (letter-box).
- `STRETCH` — estica para preencher exatamente, ignorando a proporção.
- `ORIGINAL` — tamanho natural, sem escala.

## Exemplo completo (copiar, colar e rodar)

```java
package com.exemplo;

import java.io.IOException;

import dev.crossfly.ui.*;                     // Window, Component
import dev.crossfly.ui.layout.*;             // VerticalLayout
import dev.crossfly.ui.image.*;              // Image, ImageException
import dev.crossfly.ui.UIConstants.ImageSize;

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

      try {
         Image bg = new Image("/sdcard/wallpaper.jpg");

         // Cobre todo o componente (aqui, a própria janela), centralizado,
         // preservando a proporção:
         addBackgroundImage(bg, ImageSize.FIT, 0.5f, 0.5f);
      } catch (ImageException | IOException e) {
         // arquivo não encontrado ou corrompido
      }
   }
}
```

> O trecho abaixo mostra **só o miolo**. Para rodar, coloque-o no esqueleto `MainWindow` acima.

## Trecho mínimo

```java
// verificado na fonte: Component.addBackgroundImage (158, 181); BackgroundImage.java onPaint (105)
import dev.crossfly.ui.image.Image;
import dev.crossfly.ui.UIConstants.ImageSize;

Image bg = new Image("/sdcard/wallpaper.jpg");

// Cobre todo o componente, centralizado, preservando a proporção:
meuComponent.addBackgroundImage(bg, ImageSize.FIT, 0.5f, 0.5f);
```

> Notas de implementação (fonte):
> - Para todos os modos exceto `ORIGINAL`, se a imagem for maior que a área alvo o `BackgroundImage`
>   **pré-escala** a imagem uma vez (`resize(..., ResizeMode.STRETCH, ResizeQuality.FAST)`) e cacheia o
>   resultado, reduzindo a banda de textura da GPU. Se o `resize` falhar, cai para a imagem original.
> - `centerX`/`centerY` deslocam a imagem dentro da sobra: a posição é
>   `(component.width - w) * centerX` (idem para Y). Com `0,0` a imagem cola no canto superior esquerdo.
> - É possível adicionar **várias** imagens de fundo ao mesmo componente; são pintadas na ordem de inserção.

## Aprofunde-se
- Receita irmã: [carregar-arquivo-rede.md](/docs/cookbook/images/carregar-arquivo-rede) — carregue a imagem antes de usá-la como fundo.
- [Imagens](/docs/ui/images-and-graphics/images) — modos de `ImageSize` em detalhe.