# Whiteboard

> Free-hand drawing capture — signature, scribble — with pen color and thickness.

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

# Whiteboard

`Whiteboard` is a **free-hand drawing area using finger/mouse** — the classic case is **signature
capture**. It already handles the touch events and accumulates the strokes internally.

## Complete example (copy, paste and run)
```java
package com.exemplo;

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

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

      // Signature area filling the remaining space (LAY_FILL).
      Whiteboard board = new Whiteboard();
      board.setPenColor(0xFF000000);   // black pen
      board.thick = true;              // thick stroke
      add(LAY_FILL, board);

      // Button to clear the drawing.
      Button limpar = new Button("Limpar");
      limpar.onAction(c -> board.clear());
      add(LAY_AUTO, limpar);

      // Button to capture the drawing as an image (e.g., to persist it).
      Button salvar = new Button("Salvar");
      salvar.onAction(c -> {
         Image img = board.getImage();   // the current drawing as an Image (may be null if empty)
         // … persist img (e.g., PNG) …
      });
      add(LAY_AUTO, salvar);
   }
}
```
> The snippets below show **only the core** (what goes inside `onShow()`). To run them, place them in the `MainWindow` skeleton above.

## Basic usage (signature)
```java
Whiteboard assinatura = new Whiteboard();
assinatura.setPenColor(0xFF000000);   // black pen
assinatura.thick = true;              // thick stroke
painel.add(0.5f, assinatura);         // 50% of the height

Button limpar = new Button("Limpar");
limpar.onAction(c -> assinatura.clear());

Button salvar = new Button("Salvar");
salvar.onAction(c -> {
   Image img = assinatura.getImage();   // the drawing as an image
   // … persist img (e.g., PNG) …
});
```

## API
| Member | Effect |
|---|---|
| `setPenColor(int)` / `getPenColor()` | pen color (ARGB) |
| `thick` (`boolean` field) | `true` = thick stroke |
| `clear()` | erases everything |
| `getImage()` | returns the current drawing as `Image` |
| `setImage(Image)` | loads a base image (throws `ImageException`) |

## Best practices
- Give it **generous height** (a fraction of the container or `autoHeight`) — a signature needs space.
- Always offer a **Clear** button.
- When saving, use `getImage()` and handle exceptions when converting/persisting.

## Common mistakes
- Area too small → illegible signature.
- Forgetting that `setImage(Image)` throws `ImageException` (checked).
- Confusing it with `ImageView` (only displays) — `Whiteboard` **captures** drawing.

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