Cursor

Description

Cursor Manager and Cursor objects for mouse and cursor handling [v26.02.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::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...