# Cómo definir una imagen de fondo en un Component

> Agregar una imagen de fondo a cualquier Component con addBackgroundImage e ImageSize.

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

# Cómo definir una imagen de fondo en un Component

**Propósito.** Dibujar una imagen detrás del contenido de **cualquier** `Component` (una pantalla, un panel,
una tarjeta), controlando cómo llena el área y dónde queda centrada. A diferencia de un `ImageView`, la
imagen de fondo es pintada por el propio componente, detrás de los hijos.

## APIs usadas
- `void Component.addBackgroundImage(Image image, ImageSize imageSize, float centerX, float centerY)` — agrega una imagen de fondo. `centerX`/`centerY` son fracciones de 0 a 1 que posicionan la imagen dentro del espacio sobrante (`0.5, 0.5` = centrada).
- `void Component.addBackgroundImage(Image image, Relative width, Relative height, float centerX, float centerY)` — variante con ancho/alto relativos explícitos (vía `Relative`), en vez de un `ImageSize`.
- `ImageSize` (enum, verificado en `UIConstants`): `ORIGINAL, RATIO, STRETCH, FIT, FIT_WIDTH, FIT_HEIGHT, FIT_HALF_WIDTH, FIT_HALF_HEIGHT`.

### Modos útiles para fondo (comportamiento en `BackgroundImage.onPaint`)
- `FIT` — cubre **toda** el área preservando la proporción (puede sobrepasar/recortar). Es el modo típico para papel tapiz.
- `RATIO` — cabe entera dentro del área preservando la proporción (letter-box).
- `STRETCH` — estira para llenar exactamente, ignorando la proporción.
- `ORIGINAL` — tamaño natural, sin escala.

## Ejemplo completo (copiar, pegar y ejecutar)

```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;

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

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

         // Cubre todo el componente (aquí, la propia ventana), centrado,
         // preservando la proporción:
         addBackgroundImage(bg, ImageSize.FIT, 0.5f, 0.5f);
      } catch (ImageException | IOException e) {
         // archivo no encontrado o corrupto
      }
   }
}
```

> El fragmento de abajo muestra **solo el núcleo**. Para ejecutarlo, colócalo en el esqueleto `MainWindow` de arriba.

## Fragmento mínimo

```java
// verificado en la fuente: 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");

// Cubre todo el componente, centrado, preservando la proporción:
meuComponent.addBackgroundImage(bg, ImageSize.FIT, 0.5f, 0.5f);
```

> Notas de implementación (fuente):
> - Para todos los modos excepto `ORIGINAL`, si la imagen es mayor que el área objetivo el `BackgroundImage`
>   **preescala** la imagen una vez (`resize(..., ResizeMode.STRETCH, ResizeQuality.FAST)`) y cachea el
>   resultado, reduciendo el ancho de banda de textura de la GPU. Si el `resize` falla, recurre a la imagen original.
> - `centerX`/`centerY` desplazan la imagen dentro del sobrante: la posición es
>   `(component.width - w) * centerX` (ídem para Y). Con `0,0` la imagen se pega a la esquina superior izquierda.
> - Es posible agregar **varias** imágenes de fondo al mismo componente; se pintan en el orden de inserción.

## Profundiza
- Receta hermana: [carregar-arquivo-rede.md](/docs/cookbook/images/carregar-arquivo-rede) — carga la imagen antes de usarla como fondo.
- [Imágenes](/docs/ui/images-and-graphics/images) — modos de `ImageSize` en detalle.