Description

Cursor Manager and Cursor objects for mouse and cursor handling [v25.12.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...

Functions
Sint32	CRM64Pro::Cursor::info (Sint32 iMode=0)
	Request Cursor object information.
Sint32	CRM64Pro::Cursor::getName (string &sName)
	Get the name.
Uint32	CRM64Pro::Cursor::getID ()
	Get the ID.
Sint32	CRM64Pro::Cursor::assignImage (Sint32 idImage, Sint32 iOwnership=0)
	Assign an Image to this cursor.
Sint32	CRM64Pro::Cursor::getImage ()
	Get the assigned Image of this cursor.
Sint32	CRM64Pro::Cursor::build ()
	Build the cursor.
Sint32	CRM64Pro::Cursor::setHotSpot (const Position &posHotX, const Position &posHotY)
	Set the cursor hotspots.
Sint32	CRM64Pro::Cursor::getHotSpot (Sint32 iHotX, Sint32 iHotY)
	Get the cursor hotspots.
Sint32	CRM64Pro::Cursor::save (const string &sFileCDC)
	Save the cursor to a CDC file.
Sint32	CRM64Pro::Cursor::save (Sint32 idCDC)
	Save the cursor to a CDC file.

Function Documentation

◆ info()

Sint32 CRM64Pro::Cursor::info ( Sint32 iMode = 0 )

Request Cursor object information.

Writes information to the default log.

Parameters

iMode unused for the time being.

Returns: 0 on success, or a negative error code on failure.

◆ getName()

Sint32 CRM64Pro::Cursor::getName ( string & sName )

Get the name.

Parameters

sName a string containing the cursor name.

Returns: 0 on success, or a negative error code on failure.

◆ getID()

Uint32 CRM64Pro::Cursor::getID ( )

Get the ID.

Returns: Object ID.

◆ assignImage()

Sint32 CRM64Pro::Cursor::assignImage	(	Sint32	idImage,
		Sint32	iOwnership = 0 )

Assign an Image to this cursor.

Used for associating an Image to cursors created via CursorMgr::create().

Parameters

idImage	Image id.
iOwnership	0 (default) creates a copy; any other value takes ownership (image cannot be owned by another item).

Returns: 0 on success, or a negative error code on failure.

Note: Image name is internally modified (prefixed with '#' + internal code + cursor name). Re-assigning closes the old image. SDL system cursors don't support image assignments.

◆ getImage()

Sint32 CRM64Pro::Cursor::getImage ( )

Get the assigned Image of this cursor.

Returns: greater than 0 on success, or a negative error code on failure.

◆ build()

Sint32 CRM64Pro::Cursor::build ( )

Build the cursor.

If the assigned Image colorkey is modified, this method rebuilds the cursor. Other Image attributes (color/alpha modulation) have no effect on cursors.

Returns: 0 on success, or a negative error code on failure.

Note: Cursors are dynamically built when first selected. Use this method to build them in advance.

◆ setHotSpot()

Sint32 CRM64Pro::Cursor::setHotSpot	(	const Position &	posHotX,
		const Position &	posHotY )

Set the cursor hotspots.

Parameters

posHotX	Position with x hotspot. Can be absolute (float) or use ::PH_CENTER / ::PH_SIZE helpers.
posHotY	Position with y hotspot. Can be absolute (float) or use ::PH_CENTER / ::PH_SIZE helpers.

Returns: 0 on success, or a negative error code on failure.

Note: Hotspot of SDL system cursors can not be modified, they are fixed to (0,0).; Supports implicit conversion: setHotSpot(10.0f, 20.0f) or setHotSpot(Position(PH_CENTER), Position(PH_SIZE))

◆ getHotSpot()

Sint32 CRM64Pro::Cursor::getHotSpot	(	Sint32 *	iHotX,
		Sint32 *	iHotY )

Get the cursor hotspots.

Parameters

iHotX	an integer pointer filled in with x hotspot position of the cursor. If nullptr is passed, the method ignores the retrieving of this value.
iHotY	an integer pointer filled in with y hotspot position of the cursor. If nullptr is passed, the method ignores the retrieving of this value.

Returns: 0 on success, or a negative error code on failure.

Note: The mouse cursor position is internally updated in Main::update() each Logic Frame update.

◆ save() [1/2]

Sint32 CRM64Pro::Cursor::save ( const string & sFileCDC )

Save the cursor to a CDC file.

The associated image will also be saved to the same CDC file.

Parameters

sFileCDC string containing [directory]+filename+[extension]. Directory separators '\' and '/' are supported.

Returns: 0 or greater on success or a negative error code on failure.

Note: Existing cursor is overwritten. Cannot save child cursors or SDL system cursors.

◆ save() [2/2]

Sint32 CRM64Pro::Cursor::save ( Sint32 idCDC )

Save the cursor to a CDC file.

The associated image will also be saved to the same CDC file.

Parameters

idCDC CDC id.

Returns: 0 or greater on success or a negative error code on failure.

Note: Existing cursor is overwritten. If a child, calls parent's save method. Cannot save SDL system cursors.

Description

Overview

Key features

SDL system cursors

Custom cursor images

Storage layer

Update mechanism

Manager type

Best practices

Classes

Functions

Function Documentation

◆ info()

◆ getName()

◆ getID()

◆ assignImage()

◆ getImage()

◆ build()

◆ setHotSpot()

◆ getHotSpot()

◆ save() [1/2]

◆ save() [2/2]