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)

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

// 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 — carga la imagen antes de usarla como fondo.
• Imágenes — modos de ImageSize en detalle.