CRM64Pro GDK  v0.97
A free cross-platform game development kit built on top of SDL 2.0
Classes | Functions
Cursor Manager

Classes

class  CRM64Pro::Cursor
 
class  CRM64Pro::CursorMgr
 

Functions

Sint32 CRM64Pro::Cursor::info (Sint32 iMode=0)
 
Sint32 CRM64Pro::Cursor::getName (string &sName)
 
Uint32 CRM64Pro::Cursor::getID ()
 
Sint32 CRM64Pro::Cursor::assignImage (Sint32 idImage, Sint32 iOwnership=0)
 
Sint32 CRM64Pro::Cursor::getImage ()
 
Sint32 CRM64Pro::Cursor::build ()
 
Sint32 CRM64Pro::Cursor::setHotSpot (Sint32 iHotX, Sint32 iHotY)
 
Sint32 CRM64Pro::Cursor::getHotSpot (Sint32 *iHotX, Sint32 *iHotY)
 
Sint32 CRM64Pro::Cursor::save (const string &sFileCDC)
 
Sint32 CRM64Pro::Cursor::save (Sint32 idCDC)
 
Sint32 CRM64Pro::CursorMgr::info (Sint32 iMode=0)
 
Sint32 CRM64Pro::CursorMgr::create (const string &sName, Uint32 iVersion=10)
 
Sint32 CRM64Pro::CursorMgr::close (Sint32 idCur)
 
Sint32 CRM64Pro::CursorMgr::getNum ()
 
Sint32 CRM64Pro::CursorMgr::setName (Sint32 idCur, const string &sName)
 
CursorCRM64Pro::CursorMgr::get (Sint32 idCur)
 
Sint32 CRM64Pro::CursorMgr::select (Sint32 idCur)
 
Sint32 CRM64Pro::CursorMgr::getSelect ()
 
Sint32 CRM64Pro::CursorMgr::show ()
 
Sint32 CRM64Pro::CursorMgr::hide ()
 
Sint32 CRM64Pro::CursorMgr::setPosition (Sint32 iX, Sint32 iY, Sint32 idScreen=0)
 
Sint32 CRM64Pro::CursorMgr::getPosition (Sint32 *iX, Sint32 *iY)
 
Sint32 CRM64Pro::CursorMgr::getButtons ()
 
Sint32 CRM64Pro::CursorMgr::getButtonsPrev ()
 
Sint32 CRM64Pro::CursorMgr::getFocus ()
 
Sint32 CRM64Pro::CursorMgr::child (Sint32 idCur)
 
Sint32 CRM64Pro::CursorMgr::load (const string &sFileCDC, const string &sName)
 
Sint32 CRM64Pro::CursorMgr::load (const Sint32 idCDC, const string &sName)
 
Sint32 CRM64Pro::CursorMgr::remove (Sint32 idCDC, const string &sName)
 

Detailed Description

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

SDL_SYSTEM_CURSOR_ARROW - Arrow
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

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.

Function Documentation

◆ info() [1/2]

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

Request Cursor object information.

For displaying the information, it uses the default log.

Parameters
iModeunused 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
sNamea 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
idImageImage id.
iOwnership0 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
iHotXthe x hotspot position of the cursor. You can set any value or PH_CENTER and PH_END enum values.
iHotYthe 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
iHotXan integer pointer filled in with x hotspot position of the cursor. If nullptr is passed, the method ignores the retrieving of this value.
iHotYan 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
sFileCDCstring 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
idCDCCDC 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.

◆ info() [2/2]

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

Request Cursor Manager information.

For displaying the information, it uses the default log.

Parameters
iMode-1 for displaying only Manager information.
0 for displaying Manager and all Objects information. This is the default value.
idCursor for displaying Manager and given Cursor id information.
Returns
0 on success or a negative error code on failure.

◆ create()

Sint32 CRM64Pro::CursorMgr::create ( const string &  sName,
Uint32  iVersion = 10 
)

Create a new cursor.

This method will create an empty cursor (no image assigned), use Cursor::assignImage() method for assigning the image.

Parameters
sNameThe name to give to the cursor e.g. 'myCursor'.
The object name must be unique and with a maximum size of 64 characters or will be truncated.
iVersionCursor version. 10 means 1.0 which is the only version supported (as of now).
v1.0 is set by default.
Returns
greater than 0 on success(the Cursor id) or a negative error code on failure.
Note
If the provided name already exists, it does nothing and return an error code.

◆ close()

Sint32 CRM64Pro::CursorMgr::close ( Sint32  idCur)

Close and destroy a cursor.

Parameters
idCur0 for closing all cursors or the Cursor id.
Stand-alone and child cursors can be closed but parent ones, can not as they have at least one dependency(a child).
Returns
0 on success or a negative error code on failure.
Note
If you forget to close a Cursor, it will be automatically closed once the GDK is terminated.

◆ getNum()

Sint32 CRM64Pro::CursorMgr::getNum ( )

Get number of loaded objects.

Returns
the number of cursors.

◆ setName()

Sint32 CRM64Pro::CursorMgr::setName ( Sint32  idCur,
const string &  sName 
)

Change the object name.

Parameters
idCurCursor id.
sNameThe name to give to the cursor e.g. 'myCursor'.
The object name must be unique and with a maximum size of 64 characters or will be truncated.
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.

◆ get()

Cursor * CRM64Pro::CursorMgr::get ( Sint32  idCur)

Get a pointer to the cursor using its handler.

Parameters
idCurCursor id.
Returns
nullptr the cursor was not found.
A pointer to the cursor object.

◆ select()

Sint32 CRM64Pro::CursorMgr::select ( Sint32  idCur)

Select a mouse cursor.

Parameters
idCurCursor id. It also supports any SDL_SystemCursor.
Returns
0 on success or a negative error code on failure.
Note
Cursors are dinamically build on the first time they are selected. You can use Cursor::build() for building them in advance.

◆ getSelect()

Sint32 CRM64Pro::CursorMgr::getSelect ( )

Get selected mouse cursor.

Returns
Current selected Cursor id.

◆ show()

Sint32 CRM64Pro::CursorMgr::show ( )

Make visible the selected mouse cursor.

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

◆ hide()

Sint32 CRM64Pro::CursorMgr::hide ( )

Hide the mouse cursor.

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

◆ setPosition()

Sint32 CRM64Pro::CursorMgr::setPosition ( Sint32  iX,
Sint32  iY,
Sint32  idScreen = 0 
)

Set the mouse cursor position.

Parameters
iXinteger with x position.
iYinteger with y position.
idScreenScreen id.
By default it is set to 0 for using the screen with the mouse focus.
Returns
0 on success or a negative error code on failure.

◆ getPosition()

Sint32 CRM64Pro::CursorMgr::getPosition ( Sint32 *  iX,
Sint32 *  iY 
)

Get the mouse cursor position.

Parameters
iXan integer pointer filled in with X mouse position. If nullptr is passed, the method ignores the retrieving of this value.
iYan integer pointer filled in with Y mouse position. 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.

◆ getButtons()

Sint32 CRM64Pro::CursorMgr::getButtons ( )

Get the mouse buttons.

Returns
32 bit button bitmask of the current button state.
Note
The mouse buttons are internally updated in Main::update() each Logic Frame update. The button bitmask can be tested using the SDL_BUTTON(X) macros where X is generally 1 for the left, 2 for middle, 3 for the right button.

◆ getButtonsPrev()

Sint32 CRM64Pro::CursorMgr::getButtonsPrev ( )

Get the previous mouse buttons.

Returns
32 bit button bitmask of the previous(the last Logic Frame) button state.
Note
The mouse buttons are internally updated in Main::update() each Logic Frame update. The button bitmask can be tested using the SDL_BUTTON(X) macros where X is generally 1 for the left, 2 for middle, 3 for the right button.

◆ getFocus()

Sint32 CRM64Pro::CursorMgr::getFocus ( )

Get the Screen id which currently has mouse focus.

Returns
0 or greater on success(the Screen id) or a negative error code on failure.
Note
For getting the keyboard focus you can use Main::getKeyboardFocus() method.

◆ child()

Sint32 CRM64Pro::CursorMgr::child ( Sint32  idCur)

Create a child cursor dependant on the provided one(the parent).

A child cursor uses the attributes of the parent and creates also a parent child image for having different attributes, for the time being, only different Hotspots as the colorkey can not be modified on child images and other image attributes are not supported on the SDL cursors system.

Parameters
idCurparent Cursor id.
If the provided cursor is a child, internally it will redirect this request to the parent in order to create the new child.
Returns
greater than 0 on success(the Cursor id) or a negative error code on failure.
Note
The child use the parent's name.

◆ load() [1/2]

Sint32 CRM64Pro::CursorMgr::load ( const string &  sFileCDC,
const string &  sName 
)

Load a cursor stored in a CDC file.

Parameters
sFileCDCstring containing the [directory]+filename.
Directory separators '\' and '/' are supported.
sNamestring with the cursor name (maximum size of 64 characters).
If the Cursor is already created, this method will call child() for creating a child.
Returns
0 or greater on success(the Cursor id) or a negative error code on failure.

◆ load() [2/2]

Sint32 CRM64Pro::CursorMgr::load ( const Sint32  idCDC,
const string &  sName 
)

Load a cursor stored in a CDC file.

Parameters
idCDCCDC id.
sNamestring with the cursor name (maximum size of 64 characters).
If the Cursor is already created, this method will call child() for creating a child.
Returns
greater than 0 on success(the Cursor id) or a negative error code on failure.

◆ remove()

Sint32 CRM64Pro::CursorMgr::remove ( Sint32  idCDC,
const string &  sName 
)

Remove a cursor stored in a CDC file.

Parameters
idCDCCDC id.
sNamestring with the cursor name (maximum size of 64 characters).
Returns
greater than 0 on success or a negative error code on failure.
Note
The cursor must be closed before trying to remove it from the CDC.