# How to set a background image on a Component

> Add a background image to any Component with addBackgroundImage and ImageSize.

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

# How to set a background image on a Component

**Purpose.** Draw an image behind the content of **any** `Component` (a screen, a panel,
a card), controlling how it fills the area and where it is centered. Unlike an `ImageView`, the
background image is painted by the component itself, behind the children.

## APIs used
- `void Component.addBackgroundImage(Image image, ImageSize imageSize, float centerX, float centerY)` — adds a background image. `centerX`/`centerY` are fractions from 0 to 1 that position the image within the leftover space (`0.5, 0.5` = centered).
- `void Component.addBackgroundImage(Image image, Relative width, Relative height, float centerX, float centerY)` — variant with explicit relative width/height (via `Relative`), instead of an `ImageSize`.
- `ImageSize` (enum, verified in `UIConstants`): `ORIGINAL, RATIO, STRETCH, FIT, FIT_WIDTH, FIT_HEIGHT, FIT_HALF_WIDTH, FIT_HALF_HEIGHT`.

### Useful modes for a background (behavior in `BackgroundImage.onPaint`)
- `FIT` — covers the **entire** area preserving the aspect ratio (may overflow/crop). It is the typical mode for wallpaper.
- `RATIO` — fits entirely within the area preserving the aspect ratio (letter-box).
- `STRETCH` — stretches to fill exactly, ignoring the aspect ratio.
- `ORIGINAL` — natural size, no scaling.

## Complete example (copy, paste and run)

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

/** Runnable main screen. Point the launcher (classname) and run: 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");

         // Covers the whole component (here, the window itself), centered,
         // preserving the aspect ratio:
         addBackgroundImage(bg, ImageSize.FIT, 0.5f, 0.5f);
      } catch (ImageException | IOException e) {
         // file not found or corrupted
      }
   }
}
```

> The snippet below shows **only the core**. To run it, place it inside the `MainWindow` skeleton above.

## Minimal snippet

```java
// verified in source: 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");

// Covers the whole component, centered, preserving the aspect ratio:
meuComponent.addBackgroundImage(bg, ImageSize.FIT, 0.5f, 0.5f);
```

> Implementation notes (source):
> - For all modes except `ORIGINAL`, if the image is larger than the target area the `BackgroundImage`
>   **pre-scales** the image once (`resize(..., ResizeMode.STRETCH, ResizeQuality.FAST)`) and caches the
>   result, reducing GPU texture bandwidth. If the `resize` fails, it falls back to the original image.
> - `centerX`/`centerY` offset the image within the leftover space: the position is
>   `(component.width - w) * centerX` (same for Y). With `0,0` the image sticks to the top-left corner.
> - It is possible to add **several** background images to the same component; they are painted in insertion order.

## Dive deeper
- Sibling recipe: [carregar-arquivo-rede.md](/docs/cookbook/images/carregar-arquivo-rede) — load the image before using it as a background.
- [Images](/docs/ui/images-and-graphics/images) — `ImageSize` modes in detail.