Cursor

Detailed Description

v2.00 (22 June 2023)
The Cursor module includes the Cursor Manager and Cursor for handling all the operations with the mouse and mouse cursor.

This system is build over the SDL cursor and always has the 12 SDL system cursors available for selecting:

SDL_SYSTEM_CURSOR_ARROW	Arrow  (typically the default cursor)
SDL_SYSTEM_CURSOR_IBEAM	I-beam
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_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 pointing north, south, east, and west
SDL_SYSTEM_CURSOR_NO	Slashed circle or crossbones
SDL_SYSTEM_CURSOR_HAND	Hand

(From SDL_SystemCursor)

Before to create/load cursors, a valid screen must exist or these methods will fail.
Each cursor (but SDL system cursors) owns an Image id. Although there is a method for getting this Image id, it only should be used for showing image info, saving it or changing the image name. Other attributes like color modulation, alpha modulation and blend modes dont work with the cursor. Only colorkey works but as it needs a cursor rebuild, CursorMgr has its own setColorKey() that does this task.

The storage layer(CursorMgr::load() and Cursor::save() methods) are using the CDC v1.x specification.
Internally, Main::update() call to CursorMgr::update() for updating the cursor status (buttons and position).

This is an advance "cloning" manager: when loading from a CDC file a cursor which is already loaded/created (using the name as the key), it will create a new child cursor.
Only a single instance of the Cursor Manager exists which is created once Main is instantiated.
You can get a reference to this manager using Main::ICursorMgr() method.

Note

The Cursor Manager is automatically released when Main::Terminate() is called.
At this time, any resource still loaded, will be released avoding 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 (Sint32 iHotX, Sint32 iHotY)
	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.

For displaying the information, it uses 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

the object ID.

assignImage()

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

Assign an Image to this cursor.

It is mainly used for associating an Image to the cursor when it is created via CursorMgr::create().

Parameters

idImage	Image id.
iOwnership	0 for creating our own copy of the image or any other integer for taking the ownership of the image, in this case, the image can not be already owned by other item. By default it is set to 0.

Returns

0 on success or a negative error code on failure.

Note

The image name associated to this cursor will be internally modified: starts with the reserved character '#' + an internal code + the cursor name.
When re-assigning a new image, the old one will be closed.
SDL system cursors dont 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, a call to this method will re-build the cursor to reflect the changes.
Other Image attributes as color and alpha modulation will not have any effect with the cursors.

Returns

0 on success or a negative error code on failure.

Note

Cursors are dinamically built on the first time they are selected. You can use this method for building them in advance.

setHotSpot()

Sint32 CRM64Pro::Cursor::setHotSpot	(	Sint32	iHotX,
		Sint32	iHotY
	)

Set the cursor hotspots.

Parameters

iHotX	the x hotspot position of the cursor. You can set any value or PH_CENTER and PH_END enum values.
iHotY	the y hotspot position of the cursor. You can set any value or PH_CENTER and PH_END enum values.

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).

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 in to the same CDC file.

Parameters

sFileCDC

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

Returns

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

Note

If the cursor already exists, it will be overwritten.
Can not save child cursors.
SDL system cursors can not be saved.

save() [2/2]

Sint32 CRM64Pro::Cursor::save

(

Sint32

idCDC

)

Save the cursor to a CDC file.

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

Parameters

idCDC

CDC id.

Returns

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

Note

If the cursor already exists, it will be overwritten.
If the font is a child, it will call the save method of its parent.
SDL system cursors can not be saved.