Images (`ImageView`)

ImageView displays an Image inside a component, with control over scaling (ImageSize) and alignment.

Complete example (copy, paste and run)

package com.exemplo;

import java.io.*;                     // IOException

import dev.crossfly.ui.*;
import dev.crossfly.ui.layout.*;
import dev.crossfly.ui.image.*;       // Image, ImageException
import dev.crossfly.util.*;           // Debug

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

      // Load with fallback: new Image(path) throws ImageException/IOException (checked).
      Image logo;
      try
      {
         logo = new Image("images/logo.png");   // app resource path
      }
      catch (ImageException | IOException e)
      {
         Debug.log("falha ao carregar: " + e);
         return;   // aborts the build if the image is missing
      }

      // Display with ImageView, keeping proportion (RATIO) and centered.
      ImageView foto = new ImageView(logo, ImageSize.RATIO)
         .alignX(Position.CENTER)
         .alignY(Position.CENTER);
      add(0.4f, foto);   // 40% of the height (VerticalLayout)

      // Background image of the window itself (a Component method, not an ImageView).
      addBackgroundImage(logo, ImageSize.FIT, 0.5f, 0.5f);   // centered, covering
   }
}

The snippets below show only the core (what goes inside onShow()). To run them, place them in the MainWindow skeleton above.

Load an `Image`

Image logo;
try {
   logo = new Image("images/logo.png");   // app resource path
} catch (ImageException | IOException e) {
   Debug.log("falha ao carregar: " + e);
   return;
}

Useful constructors: new Image(String path), new Image(byte[] bytes), new Image(InputStream), new Image(int w, int h) (empty bitmap to draw on). All can throw ImageException (and the path/stream one also IOException).

Display

ImageView foto = new ImageView(logo, ImageSize.RATIO)
   .alignX(Position.CENTER)
   .alignY(Position.CENTER);
painel.add(0.4f, foto);   // 40% of the height (VerticalLayout)

Constructors: ImageView(), ImageView(Image), ImageView(Image, ImageSize). Fluent: .image(Image), .imageSize(ImageSize), .alignX(Position), .alignY(Position).

Scale modes (`ImageSize`)

Mode	Behavior
`ORIGINAL`	natural size in pixels
`RATIO`	fits inside the component keeping proportion (may leave empty space)
`FIT`	covers the component keeping proportion (may crop)
`STRETCH`	stretches to fill, ignoring proportion
`FIT_WIDTH` / `FIT_HEIGHT`	fits by width / height, keeping proportion
`FIT_HALF_WIDTH` / `FIT_HALF_HEIGHT`	half the width / height

Rule of thumb: RATIO = “show it whole” (letterbox); FIT = “fill without distorting” (crops the overflow); STRETCH = fill by distorting (avoid on photos).

Background image (of a component/screen)

It is not an ImageView — it is a method of the Component itself:

janela.addBackgroundImage(fundo, ImageSize.FIT, 0.5f, 0.5f);   // centered, covering
// or sized via Relative:
janela.addBackgroundImage(marca, Relative.ofScreen(0.3f), null, 0.5f, 0.9f);

centerX/centerY are 0–1 (relative position of the image’s center).

Best practices

Always handle ImageException/IOException when loading — they are checked.
Photos: RATIO (show everything) or FIT (fill by cropping). Avoid STRETCH (distorts).
Load large images off the paint thread and come back with Component.onUI(...).

Common mistakes

Not catching the exceptions from new Image(...) → does not compile.
Using STRETCH on a photo of a person (distortion); use FIT.
Confusing RATIO (fits inside) with FIT (covers and crops).

Images (ImageView)