# Default theme cursors

This directory holds the pointer cursors for the ltk **default** theme.
They are GNOME's **Adwaita** cursors (what GNOME Shell uses), bundled
verbatim so the theme is self-contained and does not depend on
`adwaita-icon-theme` being installed on the target system.

Licence and attribution are documented separately in
[`LICENSE.md`](./LICENSE.md).

## Layout

Standard XCursor theme layout:

```
themes/default/
├── cursor.theme            # XCursor theme manifest (Name=Default)
└── cursors/
    ├── default             # one binary XCursor file per CSS cursor name
    ├── text
    ├── pointer
    ├── ew-resize
    ├── …
    ├── arrow -> default    # customary X11 alias symlinks
    └── hand2 -> pointer
```

- Each regular file is a binary XCursor image set (magic `Xcur`),
  carrying one or more nominal sizes and, for the busy cursors, several
  animation frames.
- The file **name is the CSS / freedesktop cursor name** (`default`,
  `text`, `pointer`, `not-allowed`, `ns-resize`, …), which is exactly
  the name a `wp_cursor_shape_v1` shape resolves to. The alias symlinks
  (`arrow`, `hand2`, `bottom_left_corner`, …) are the legacy X11 names;
  they are not required by the cursor-shape protocol but are kept so the
  tree also works as a plain XCursor theme (e.g. for XWayland).

## Cursor set

The theme provides a file for every shape ltk can request — the 34
variants of [`ltk::CursorShape`](../../../src/types.rs), which mirror
`cursor_icon::CursorIcon` 1:1:

`default`, `context-menu`, `help`, `pointer`, `progress`, `wait`,
`cell`, `crosshair`, `text`, `vertical-text`, `alias`, `copy`, `move`,
`no-drop`, `not-allowed`, `grab`, `grabbing`, `e-resize`, `n-resize`,
`ne-resize`, `nw-resize`, `s-resize`, `se-resize`, `sw-resize`,
`w-resize`, `ew-resize`, `ns-resize`, `nesw-resize`, `nwse-resize`,
`col-resize`, `row-resize`, `all-scroll`, `zoom-in`, `zoom-out`.

`wait` and `progress` are animated (multiple frames with per-frame
delays). The `tests/cursor_assets.rs` integration test enforces that
every name above resolves to a valid XCursor file.

## How they are used

ltk does **not** rasterise cursors itself; as a Wayland client it
declares a shape per widget through `wp_cursor_shape_v1` and the
compositor draws it. The Liberux compositor (forge) resolves the
requested shape against the active theme's `cursors/` directory by CSS
name, picks the image whose nominal size is closest to `24px × output
scale`, and uploads it at the cursor's hotspot — so these files are what
the user actually sees under forge. A compositor that does not advertise
`wp_cursor_shape_v1`, or that uses a different cursor theme, will ignore
this directory.

## Forking / overriding

To ship different cursors in a derived theme, drop replacement XCursor
files (same CSS names) into the fork's `cursors/` directory. Keep
`cursor.theme` so the tree stays a valid XCursor theme, and update the
`Files: themes/default/cursors/*` paragraph in `debian/copyright` plus
this directory's `LICENSE.md` to match the new source and licence.