ImageView

ImageView renders an Image within the component’s bounds, with the scale mode controlled by the ImageSize enum and horizontal/vertical alignment via Position. It is the declarative way to show a fixed image (photo, cover, logo) in a layout.

Internally it keeps a cached scaled copy (ResizeMode.STRETCH, ResizeQuality.FAST) so it does not resize every frame; the cache is invalidated when the image, the scale mode or the size changes.

🟢 · Package: dev.crossfly.ui · Extends: Component · Style: ComponentStyle (uses ingap for internal margin)

When to use

• Display a fixed image in a layout: photo, cover, logo, avatar.
• Adjust how the image fills the space (aspect ratio, cover, stretch).

When NOT to use

• Per-frame animation, continuously varying scale or composite drawing → make your own Component with onPaint calling paint.image(...) directly (see images-and-graphics/).
• Background image of another component → use the Component’s own BackgroundImage (Ch. 18).

Appearance

The image is centered by default within the internal area (after ingap) and scaled according to ImageSize:

``

Complete example (copy, paste and run)

package com.exemplo;

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

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

      // Loading an Image can throw ImageException/IOException — handle it so the screen doesn't break.
      ImageView iv = new ImageView();          // empty (placeholder: nothing is drawn)
      try {
         Image capa = new Image("cf/samples/api/ui/books/book1.png");
         iv.image(capa).imageSize(ImageSize.RATIO);
      } catch (ImageException e) {
         System.out.println("Imagem não encontrada, usando placeholder vazio: " + e.getMessage());
      }

      add(LAY_FILL, iv);
   }
}

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

Basic usage

Image capa = new Image("cf/samples/api/ui/books/book1.png");
ImageView iv = new ImageView(capa, ImageSize.RATIO);
container.add(LAY_FILL, iv);

Constructors

Properties and customization

Callbacks and events

None. ImageView is non-interactive.

States

No interaction states. If image == null, nothing is drawn.

Cover (crop) with top alignment

Image foto = new Image(caminhoFoto);
ImageView avatar = new ImageView(foto, ImageSize.FIT)
   .alignY(Position.START);      // keeps the top visible when cropping
container.add(0.4f, avatar);

Swap the image at runtime (fluent)

ImageView iv = new ImageView();          // empty
container.add(LAY_FILL, iv);
// later, on load:
iv.image(new Image(novoCaminho))
  .imageSize(ImageSize.STRETCH);

Best practices

• Give the ImageView a defined layout space (LAY_FILL or a fraction) — the scale mode only makes sense with known bounds.
• Release the Image with dispose() when it is no longer used (native resource — see Ch. 18).
• On the Web, prefer ResizeQuality.FAST; the ImageView’s internal scaling already uses that path.

Common mistakes

• Confusing FIT with RATIO: RATIO does letter-box (fits entirely); FIT covers and may crop. STRETCH distorts.
• Expecting automatic sizing from an ImageView without an image: getAutoWidth/Height() return 0 when image == null.

See also

• Area guide: ui/ · Recipes: cookbook/
• Concept (images, Paint.image): concepts/
• Related components: Label · Button