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)

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

// 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 — load the image before using it as a background.
• Images — ImageSize modes in detail.