# Images

> Load and display images with ImageView, the scale modes (ImageSize) and background images.

Source: https://crossfly.dev/docs/ui/images-and-graphics/images — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# Images (`ImageView`)

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

## Complete example (copy, paste and run)
```java
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`
```java
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
```java
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:
```java
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).

## See also
- [Custom drawing](/docs/ui/images-and-graphics/custom-drawing) · [Whiteboard](/docs/ui/images-and-graphics/whiteboard)
- Catalog: [ImageView](/docs/ui/widgets/imageview) · Reference: Chapter 18 — Images