Cursor

Description

Cursor Manager and Cursor objects for mouse and cursor handling [v26.01.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_ARROW	Arrow (typically the default cursor)
SDL_SYSTEM_CURSOR_IBEAM	I-beam (text selection)
SDL_SYSTEM_CURSOR_WAIT	Wait
SDL_SYSTEM_CURSOR_CROSSHAIR	Crosshair
SDL_SYSTEM_CURSOR_WAITARROW	Small wait cursor (or Wait if not available)
SDL_SYSTEM_CURSOR_NO	Slashed circle or crossbones
SDL_SYSTEM_CURSOR_HAND	Hand (pointer)

Resize cursors

SDL_SYSTEM_CURSOR_SIZENWSE	Double arrow pointing northwest and southeast
SDL_SYSTEM_CURSOR_SIZENESW	Double arrow pointing northeast and southwest
SDL_SYSTEM_CURSOR_SIZEWE	Double arrow pointing west and east
SDL_SYSTEM_CURSOR_SIZENS	Double arrow pointing north and south
SDL_SYSTEM_CURSOR_SIZEALL	Four pointed arrow (north, south, east, west)

Window resize cursors

SDL_SYSTEM_CURSOR_WINDOW_TOPLEFT	Window resize top-left (or SIZENWSE)
SDL_SYSTEM_CURSOR_WINDOW_TOP	Window resize top (or SIZENS)
SDL_SYSTEM_CURSOR_WINDOW_TOPRIGHT	Window resize top-right (or SIZENESW)
SDL_SYSTEM_CURSOR_WINDOW_RIGHT	Window resize right (or SIZEWE)
SDL_SYSTEM_CURSOR_WINDOW_BOTTOMRIGHT	Window resize bottom-right (or SIZENWSE)
SDL_SYSTEM_CURSOR_WINDOW_BOTTOM	Window resize bottom (or SIZENS)
SDL_SYSTEM_CURSOR_WINDOW_BOTTOMLEFT	Window resize bottom-left (or SIZENESW)
SDL_SYSTEM_CURSOR_WINDOW_LEFT	Window resize left (or SIZEWE)

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.

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::ICursorMgr()

Note

The Cursor Manager is a singleton, automatically created once Main is instantiated. You can get a reference to this manager using Main::ICursorMgr() 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...