sparrowMapping is for handling different mappings of controls. You don’t to have think like “A is jumping” but “Jump button is jumping”. You define your own buttons with mapping to real existing buttons, which are changeable. ;)
You first have to define a pool with every button the user shall be able to choice. Afterwards you can add buttons and give the users possibilites to change the button mapping.
| sparrowMapping | sparrowMapping is for handling different mappings of controls. |
| Macros | |
| SP_MAPPING_SET_MAX | The total number of different mapping sets to create. |
| SP_MAPPING_MAX | The maximal number of buttons to create. |
| Defines for the strategy of <spMapSetStrategy>. | |
| Functions | |
| spInitMapping | Inits sparrowMapping. |
| spMapClean(); | Deletes all mappings and all buttons in the pool. |
| spMapPoolAdd | Every button, which shall be useable by the user have to be added to the button pool. |
| spMapSetStrategy | Sets the strategy to be used if a button mapping is changed, but the mapping already exists. |
| spMapButtonAdd | Adds a semantic button identified by name or a self given ID (advise: Use #define MY_FIRE_BUTTON 0 or similar for the id). |
| spMapChange | Changes the mapping of an existing button with the setup strategy (see spMapSetStrategy). |
| spMapChangeNextInPool | Sets the mapping to the next possible button in the pool. |
| spMapChangePreviousInPool | Sets the mapping to the previous possible button in the pool. |
| spMapGetByID | Returns the state of the button given by the id. |
| spMapSetByID | Sets the state of the button given by the id. |
| spMapGetByName | Returns the state of the button given by the name. |
| spMapSetByName | Sets the state of the button given by the name. |
| spMapCaptionByID | Returns the caption of the semantic button via it’s ID. |
| spMapCaptionByName | Returns the caption of the semantic button via it’s name. |
| spMapButtonByID | Returns the caption of the real button behind the mapping via it’s ID. |
| spMapButtonByName | Returns the caption of the real button behind the mapping via it’s name. |
| spMapPoolByID | Returns the real button id of the real button behind the mapping via it’s ID. |
| spMapPoolByName | Returns the real button id of the real button behind the mapping via it’s name. |
| spMapStartChangeByID | Starts the changing of the mapping of a buttons identified by it’s ID. |
| spMapStartChangeByName | Starts the changing of the mapping of a buttons identified by it’s name. |
| spMapContinueChange | Interpretates to user input to change the mapping of a semantic button. |
| spMapLastCollisionName | Returns the name of the semantic button caption of last collision if spMapContinueChange returned 2. |
| spMapLastCollisionPool | Returns the name of the pool button of last collision if spMapContinueChange returned 2. |
| spMapCancelChange | Cancels the mapping change started with spMapStartChangeByID or spMapStartChangeByName. |
| spMapLoad | Loads a mapping. |
| spMapSave | Saves a mapping. |
PREFIX void spInitMapping( void )
Inits sparrowMapping. This function should be called by spInitCore.
PREFIX void spMapPoolAdd( int button_id, char * caption )
Every button, which shall be useable by the user have to be added to the button pool.
| button_id | the real sparrow3d button id of the button, e.g. SP_BUTTON_A or SP_BUTTON_LEFT. |
| caption | the caption of the button. Later used from spMapButtonByID and spMapButtonByName. |
PREFIX void spMapSetStrategy( int strategy )
Sets the strategy to be used if a button mapping is changed, but the mapping already exists.
| strategy | may be SP_MAPPING_NONE, which means no strategy use, SP_MAPPING_SWITCH, which means, that the mappings are switched at conflict, SP_MAPPING_OTHER_INVALID, which deletes the conflict mapping if it already exists or SP_MAPPING_CANCEL, which means, if the button is already used, don’t set it to the new mapping, but keep the old one. |
PREFIX void spMapButtonAdd( int id, char * name, char * caption, int poolButton )
Adds a semantic button identified by name or a self given ID (advise: Use #define MY_FIRE_BUTTON 0 or similar for the id).
| id | the self choosen id. Have to be between 0 and SP_MAPPING_MAX-1. |
| name | the name of the semantic button. However identifying via id is much faster! However name is needed for saving the button mapping in a config file |
| caption | the caption of the button, may be “Fire” or “Select”, whatever you need. The user should semanticly understand this caption |
| poolButton | the real sparrow3d button (e.g. SP_BUTTON_A) to be used. Don’t forget to add this button via spMapPoolAdd before! |
PREFIX int spMapChange( int id, int poolButton )
Changes the mapping of an existing button with the setup strategy (see spMapSetStrategy).
| id | button id to change |
| poolButton | real sparrow3d button to change the mapping to. Don’t forget to add this button to the pool first with spMapPoolAdd! |
| int | 0 if the button was changed or 1 if not. This can happen, if the strategy is SP_MAPPING_CANCEL and the button was already used. |
PREFIX int spMapGetByID( int id )
Returns the state of the button given by the id. This is much faster than spMapGetByName.
| id | the id of the button |
| int | 0 not pressed, 1 pressed |
PREFIX void spMapSetByID( int id, int value )
Sets the state of the button given by the id. This is much faster than spMapSetByName.
| id | the id of the button |
| value | value to set, where 0 means not pressed and 1 means pressed |
PREFIX int spMapGetByName( char * name )
Returns the state of the button given by the name. This is much slower than spMapGetByID.
| name | the name of the button |
| int | 0 not pressed, 1 pressed |
PREFIX void spMapSetByName( char * name, int value )
Sets the state of the button given by the name. This is much slower than spMapSetByID.
| name | the name of the button |
| value | value to set, where 0 means not pressed and 1 means pressed |
PREFIX char* spMapCaptionByID( int id )
Returns the caption of the semantic button via it’s ID. Much faster than spMapCaptionByName.
| id | the id of the button |
| char* | the name of the button |
PREFIX char* spMapCaptionByName( char * name )
Returns the caption of the semantic button via it’s name. Much slower than spMapCaptionByID.
| name | the name of the button |
| char* | the name of the button |
PREFIX char* spMapButtonByID( int id )
Returns the caption of the real button behind the mapping via it’s ID. Much faster than spMapButtonByName.
| id | the id of the button |
| char* | the name of the mapped button |
PREFIX char* spMapButtonByName( char * name )
Returns the caption of the real button behind the mapping via it’s name. Much slower than spMapButtonByID.
| name | the name of the button |
| char* | the name of the mapped button |
PREFIX int spMapPoolByName( char * name )
Returns the real button id of the real button behind the mapping via it’s name. Much slower than spMapPoolByID.
| name | the name of the button |
| int | the button id of the mapped button like SP_BUTTON_A |
PREFIX void spMapStartChangeByID( int id )
Starts the changing of the mapping of a buttons identified by it’s ID. Use spMapContinueChange to interpretate the user input.
| id | the id of the semantic button to change it’s mapping |
PREFIX void spMapStartChangeByName( char * name )
Starts the changing of the mapping of a buttons identified by it’s name. Use spMapContinueChange to interpretate the user input.
| name | the name of the semantic button to change it’s mapping |
PREFIX int spMapContinueChange( void )
Interpretates to user input to change the mapping of a semantic button. The whole process is started with spMapStartChangeByID or spMapStartChangeByName.
| int | 0 means changes are still in progress, so maybe some functions of the program should be supressed like going back to another menu or similar. 1 means the button mapping has been changed just now with this call, what is e.g. a good time to save the mapping. -1 means no button changing process is running right know. If 2 is returned the function is done, but no new button was set. That is the case, if the strategy is SP_MAPPING_CANCEL, but the mapped was already in use. The collision semantic button and pool button can be read via spMapLastCollisionName and spMapLastCollisionPool. |
Returns the name of the semantic button caption of last collision if spMapContinueChange returned 2.
| char* | caption of the semantic button, may be NULL! |
PREFIX char* spMapLastCollisionPool( void )
Returns the name of the pool button of last collision if spMapContinueChange returned 2.
| char* | name of the pool button, may be NULL! |
PREFIX void spMapCancelChange( void )
Cancels the mapping change started with spMapStartChangeByID or spMapStartChangeByName. No new mapping is set! spMapContinueChange will just throw -1 like always when nothing is to do. ;)
PREFIX void spMapLoad( char * subfolder, char * filename )
Loads a mapping. Important: You should first create the pool, than add your semantic buttons (same as in the saved mapping!) and then load the config. If no config is there yet, the value set by you will be kept.
| subfolder | subfolder for the config to be used. Not used on any system, but this should be the name of your application, so that the config is read e.g. from ~/.config/subfolder/filename |
| filename | filename to read from |
PREFIX void spMapSave( char * subfolder, char * filename )
Saves a mapping. Important: You should first create the pool, than add your semantic buttons (same as in the saved mapping!) and then load the config. If no config is there yet, the value set by you will be kept.
| subfolder | subfolder for the config to be used. Not used on any system, but this should be the name of your application, so that the config is saved e.g. to ~/.config/subfolder/filename |
| filename | filename to save to |
Inits sparrowMapping.
PREFIX void spInitMapping( void )
Deletes all mappings and all buttons in the pool.
PREFIX void spMapClean( void )
Every button, which shall be useable by the user have to be added to the button pool.
PREFIX void spMapPoolAdd( int button_id, char * caption )
Sets the strategy to be used if a button mapping is changed, but the mapping already exists.
PREFIX void spMapSetStrategy( int strategy )
Adds a semantic button identified by name or a self given ID (advise: Use #define MY_FIRE_BUTTON 0 or similar for the id).
PREFIX void spMapButtonAdd( int id, char * name, char * caption, int poolButton )
Changes the mapping of an existing button with the setup strategy (see spMapSetStrategy).
PREFIX int spMapChange( int id, int poolButton )
Sets the mapping to the next possible button in the pool.
PREFIX void spMapChangeNextInPool( int id )
Sets the mapping to the previous possible button in the pool.
PREFIX void spMapChangePreviousInPool( int id )
Returns the state of the button given by the id.
PREFIX int spMapGetByID( int id )
Sets the state of the button given by the id.
PREFIX void spMapSetByID( int id, int value )
Returns the state of the button given by the name.
PREFIX int spMapGetByName( char * name )
Sets the state of the button given by the name.
PREFIX void spMapSetByName( char * name, int value )
Returns the caption of the semantic button via it’s ID.
PREFIX char* spMapCaptionByID( int id )
Returns the caption of the semantic button via it’s name.
PREFIX char* spMapCaptionByName( char * name )
Returns the caption of the real button behind the mapping via it’s ID.
PREFIX char* spMapButtonByID( int id )
Returns the caption of the real button behind the mapping via it’s name.
PREFIX char* spMapButtonByName( char * name )
Returns the real button id of the real button behind the mapping via it’s ID.
PREFIX int spMapPoolByID( int id )
Returns the real button id of the real button behind the mapping via it’s name.
PREFIX int spMapPoolByName( char * name )
Starts the changing of the mapping of a buttons identified by it’s ID.
PREFIX void spMapStartChangeByID( int id )
Starts the changing of the mapping of a buttons identified by it’s name.
PREFIX void spMapStartChangeByName( char * name )
Interpretates to user input to change the mapping of a semantic button.
PREFIX int spMapContinueChange( void )
Returns the name of the pool button of last collision if spMapContinueChange returned 2.
PREFIX char* spMapLastCollisionPool( void )
Cancels the mapping change started with spMapStartChangeByID or spMapStartChangeByName.
PREFIX void spMapCancelChange( void )
Loads a mapping.
PREFIX void spMapLoad( char * subfolder, char * filename )
Saves a mapping.
PREFIX void spMapSave( char * subfolder, char * filename )
spInitCore initializes SDL, SDL_TTF and other stuff.
PREFIX void spInitCore( void )