| CRM64Pro GDK v0.19.0 A free cross-platform game development kit built on top of SDL 3.0

Loading...
Searching...
No Matches
Cursor
Graphics modules

## Description

Cursor Manager and Cursor objects for mouse and cursor handling [v26.04.0].

### Overview

The Cursor module provides complete mouse and cursor management built over the SDL cursor system. It supports both SDL system cursors and custom image-based cursors. A valid screen must exist before creating or loading cursors.

### Key features

- System cursors: Access to all 20 SDL system cursors
- Custom cursors: Create cursors from custom images
- Mouse tracking: Automatic cursor status updates (buttons and position)
- Image access: Direct access to underlying Image object (with limitations)
- CDC storage: Load and save cursors using CDC v1.x specification
- Cloning support: Automatic child cursor creation for shared resources

### SDL system cursors

The following 20 system cursors are available (from SDL_SystemCursor):

Standard cursors

SDL_SYSTEM_CURSOR_DEFAULT | Arrow (typically the default cursor)
SDL_SYSTEM_CURSOR_TEXT | I-beam (text selection)
SDL_SYSTEM_CURSOR_WAIT | Wait
SDL_SYSTEM_CURSOR_CROSSHAIR | Crosshair
SDL_SYSTEM_CURSOR_PROGRESS | Small wait cursor (or Wait if not available)
SDL_SYSTEM_CURSOR_NOT_ALLOWED | Slashed circle or crossbones
SDL_SYSTEM_CURSOR_POINTER | Hand (pointer)

Resize cursors

SDL_SYSTEM_CURSOR_NWSE_RESIZE | Double arrow pointing northwest and southeast
SDL_SYSTEM_CURSOR_NESW_RESIZE | Double arrow pointing northeast and southwest
SDL_SYSTEM_CURSOR_EW_RESIZE | Double arrow pointing west and east
SDL_SYSTEM_CURSOR_NS_RESIZE | Double arrow pointing north and south
SDL_SYSTEM_CURSOR_MOVE | Four pointed arrow (north, south, east, west)

Window resize cursors

SDL_SYSTEM_CURSOR_NW_RESIZE | Window resize top-left (or NWSE_RESIZE)
SDL_SYSTEM_CURSOR_N_RESIZE | Window resize top (or NS_RESIZE)
SDL_SYSTEM_CURSOR_NE_RESIZE | Window resize top-right (or NESW_RESIZE)
SDL_SYSTEM_CURSOR_E_RESIZE | Window resize right (or EW_RESIZE)
SDL_SYSTEM_CURSOR_SE_RESIZE | Window resize bottom-right (or NWSE_RESIZE)
SDL_SYSTEM_CURSOR_S_RESIZE | Window resize bottom (or NS_RESIZE)
SDL_SYSTEM_CURSOR_SW_RESIZE | Window resize bottom-left (or NESW_RESIZE)
SDL_SYSTEM_CURSOR_W_RESIZE | Window resize left (or EW_RESIZE)

### Custom cursor images

Each custom cursor (non-SDL system cursors) owns an Image ID with specific limitations:

Supported | Show image info, save image, change image name, colorkey (via CursorMgr::setColorKey())
Not supported | Color modulation, alpha modulation, blend modes
Colorkey note | Colorkey requires cursor rebuild; use CursorMgr::setColorKey() instead of Image methods

### Storage layer

Format | CDC v1.x specification
CursorMgr::load() | Load cursor from CDC archive
Cursor::save() | Save cursor to CDC archive

### Update mechanism

The cursor status (button states and position) is automatically updated internally when Main::update() calls CursorMgr::update().

### Manager type

This is an advanced "cloning" manager: when loading a cursor from a CDC file that is already loaded or created (using the name as the key), it will create a new child cursor. Child cursors share base data with the parent while allowing independent state.

### Naming security

Resource names are restricted to prevent collisions with system assets. The characters '#' and '@' are reserved for internal engine use. Any attempt to create or rename a resource starting with these characters will be rejected (returning a negative error code).

### Best practices

- Ensure a valid screen exists before creating or loading any cursors
- Use SDL system cursors when standard cursor appearances are acceptable: they are more efficient
- Use CursorMgr::setColorKey() instead of Image::setColorKey() for custom cursors (triggers required rebuild)
- Avoid attempting to use color modulation, alpha modulation or blend modes on cursor images: they are not supported
- Leverage cloning to efficiently share cursor resources across multiple game states
- Use the Image ID only for informational purposes, saving, or renaming, not for visual modifications
- Access the manager exclusively through Main::cursorMgr()

Note
  The Cursor Manager is a singleton, automatically created once Main is instantiated. You can get a reference to this manager using Main::cursorMgr() method.
  The Cursor Manager is automatically released when Main::terminate() is called. At this time, any resource still loaded will be released, avoiding resource leaks.

## Classes
class | CRM64Pro::Cursor
| Cursor Object class. More...
class | CRM64Pro::CursorMgr
| Cursor Manager class. More...