Expose the keymap separately from the event keycode
This adds functions to query the keymap: * SDL_GetCurrentKeymap() * SDL_GetKeymapKeycode() * SDL_GetKeymapScancode() * SDL_ReleaseKeymap() and these are distinct from the function to query the event keycode associated with a scancode, which might be affected by SDL_HINT_KEYCODE_OPTIONS. Also added an SDL_bool parameter to SDL_GetKeyName() and SDL_GetKeyFromName() to enable upper case handling of the name.
This commit is contained in:
Sam Lantinga
parent
d68d32e12c
commit
c298a3749b
15 changed files with 241 additions and 191 deletions
|
|
@ -185,81 +185,92 @@ extern SDL_DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void);
|
|||
extern SDL_DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate);
|
||||
|
||||
/**
|
||||
* Get the key code corresponding to the given scancode according to a default
|
||||
* en_US keyboard layout.
|
||||
* A keymap is a mapping from scancode and modifier state to keycode.
|
||||
*
|
||||
* See SDL_Keycode for details.
|
||||
*
|
||||
* \param scancode the desired SDL_Scancode to query.
|
||||
* \param modstate the modifier state to use when translating the scancode to
|
||||
* a keycode.
|
||||
* \returns the SDL_Keycode that corresponds to the given SDL_Scancode.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_GetKeyName
|
||||
* \sa SDL_GetScancodeFromKey
|
||||
* \sa SDL_GetCurrentKeymap
|
||||
* \sa SDL_GetKeymapKeycode
|
||||
* \sa SDL_GetKeymapScancode
|
||||
* \sa SDL_ReleaseKeymap
|
||||
*/
|
||||
extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetDefaultKeyFromScancode(SDL_Scancode scancode, SDL_Keymod modstate);
|
||||
typedef struct SDL_Keymap SDL_Keymap;
|
||||
|
||||
/**
|
||||
* Get the key code corresponding to the given scancode according to the
|
||||
* current keyboard layout.
|
||||
* Get a reference to the current keyboard layout.
|
||||
*
|
||||
* See SDL_Keycode for details.
|
||||
* You should release the reference to the keymap with SDL_ReleaseKeymap() when you're done with it.
|
||||
*
|
||||
* \param scancode the desired SDL_Scancode to query.
|
||||
* \returns the current keymap, or NULL if the default US-QWERTY keymap is being used.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_GetKeymapKeycode
|
||||
* \sa SDL_GetKeymapScancode
|
||||
* \sa SDL_ReleaseKeymap
|
||||
*/
|
||||
extern SDL_DECLSPEC SDL_Keymap * SDLCALL SDL_GetCurrentKeymap(void);
|
||||
|
||||
/**
|
||||
* Get the key code corresponding to the given scancode and modifier state using the provided keymap.
|
||||
*
|
||||
* Note that this is not the same as the input that would be generated by pressing this key. There are many factors involved, such as dead key composition, input method editors, etc. If you're looking for a way to get text input, you should handle SDL_EVENT_TEXT_INPUT.
|
||||
*
|
||||
* \param keymap the SDL_Keymap to query, or NULL for the default keymap.
|
||||
* \param scancode the SDL_Scancode to translate.
|
||||
* \param modstate the modifier state to use when translating the scancode to
|
||||
* a keycode.
|
||||
* \returns the SDL_Keycode that corresponds to the given SDL_Scancode.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_GetDefaultKeyFromScancode
|
||||
* \sa SDL_GetKeyName
|
||||
* \sa SDL_GetScancodeFromKey
|
||||
* \sa SDL_GetCurrentKeymap
|
||||
* \sa SDL_GetKeymapScancode
|
||||
*/
|
||||
extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeymapKeycode(SDL_Keymap *keymap, SDL_Scancode scancode, SDL_Keymod modstate);
|
||||
|
||||
/**
|
||||
* Get the scancode and modifier state corresponding to the given key code using the provided keymap.
|
||||
*
|
||||
* Note that there may be multiple scancode+modifier states that can generate
|
||||
* this keycode, this will just return the first one found.
|
||||
*
|
||||
* \param keymap the SDL_Keymap to query, or NULL for the default keymap.
|
||||
* \param keycode the SDL_Keycode to translate.
|
||||
* \param modstate a pointer to the modifier state that would be used when the
|
||||
* scancode generates this key, may be NULL.
|
||||
* \returns the SDL_Scancode that corresponds to the given SDL_Keycode.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_GetCurrentKeymap
|
||||
* \sa SDL_GetKeymapKeycode
|
||||
*/
|
||||
extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetKeymapScancode(SDL_Keymap *keymap, SDL_Keycode keycode, SDL_Keymod *modstate);
|
||||
|
||||
/**
|
||||
* Release a reference to the current keyboard layout.
|
||||
*
|
||||
* \param keymap the SDL_Keymap to release, may be NULL.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_GetCurrentKeymap
|
||||
*/
|
||||
extern SDL_DECLSPEC void SDLCALL SDL_ReleaseKeymap(SDL_Keymap *keymap);
|
||||
|
||||
/**
|
||||
* Get the key code that would be sent with the given scancode in a key event.
|
||||
*
|
||||
* This uses the information from the current keymap along with the options specified in SDL_HINT_KEYCODE_OPTIONS to get the keycode that would be delivered to the application in a key event. This is typically the unmodified version of the key based on the current keyboard layout. For example, the keycode for SDL_SCANCODE_A + SDL_KMOD_SHIFT using the US QWERTY layout would be 'a'.
|
||||
*
|
||||
* \param scancode the SDL_Scancode to translate.
|
||||
* \param modstate the modifier state to use when translating the scancode to
|
||||
* a keycode.
|
||||
* \returns the SDL_Keycode that corresponds to the given SDL_Scancode.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*/
|
||||
extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode, SDL_Keymod modstate);
|
||||
|
||||
/**
|
||||
* Get the scancode corresponding to the given key code according to a default
|
||||
* en_US keyboard layout.
|
||||
*
|
||||
* Note that there may be multiple scancode+modifier states that can generate
|
||||
* this keycode, this will just return the first one found.
|
||||
*
|
||||
* \param key the desired SDL_Keycode to query.
|
||||
* \param modstate a pointer to the modifier state that would be used when the
|
||||
* scancode generates this key, may be NULL.
|
||||
* \returns the SDL_Scancode that corresponds to the given SDL_Keycode.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_GetScancodeFromKey
|
||||
* \sa SDL_GetScancodeName
|
||||
*/
|
||||
extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetDefaultScancodeFromKey(SDL_Keycode key, SDL_Keymod *modstate);
|
||||
|
||||
/**
|
||||
* Get the scancode corresponding to the given key code according to the
|
||||
* current keyboard layout.
|
||||
*
|
||||
* Note that there may be multiple scancode+modifier states that can generate
|
||||
* this keycode, this will just return the first one found.
|
||||
*
|
||||
* \param key the desired SDL_Keycode to query.
|
||||
* \param modstate a pointer to the modifier state that would be used when the
|
||||
* scancode generates this key, may be NULL.
|
||||
* \returns the SDL_Scancode that corresponds to the given SDL_Keycode.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_GetDefaultScancodeFromKey
|
||||
* \sa SDL_GetKeyFromScancode
|
||||
* \sa SDL_GetScancodeName
|
||||
*/
|
||||
extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromKey(SDL_Keycode key, SDL_Keymod *modstate);
|
||||
|
||||
/**
|
||||
* Set a human-readable name for a scancode.
|
||||
*
|
||||
|
|
@ -318,12 +329,10 @@ extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *nam
|
|||
/**
|
||||
* Get a human-readable name for a key.
|
||||
*
|
||||
* Both lowercase and uppercase alphabetic keycodes have uppercase names, e.g.
|
||||
* SDL_Keycode 'a' and 'A' both have the name "A".
|
||||
*
|
||||
* If the key doesn't have a name, this function returns an empty string ("").
|
||||
*
|
||||
* \param key the desired SDL_Keycode to query.
|
||||
* \param uppercase SDL_TRUE if the name should be the letter printed on the key on the keyboard, which is usually uppercase, or SDL_FALSE to return the name of the key unchanged.
|
||||
* \returns a UTF-8 encoded string of the key name.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
|
|
@ -332,12 +341,13 @@ extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *nam
|
|||
* \sa SDL_GetKeyFromScancode
|
||||
* \sa SDL_GetScancodeFromKey
|
||||
*/
|
||||
extern SDL_DECLSPEC const char * SDLCALL SDL_GetKeyName(SDL_Keycode key);
|
||||
extern SDL_DECLSPEC const char * SDLCALL SDL_GetKeyName(SDL_Keycode key, SDL_bool uppercase);
|
||||
|
||||
/**
|
||||
* Get a key code from a human-readable name.
|
||||
*
|
||||
* \param name the human-readable key name.
|
||||
* \param uppercase SDL_TRUE if the name is the letter printed on the key on the keyboard, which is usually uppercase, and this function should return the unshifted version of the key, or SDL_FALSE to return the key unchanged.
|
||||
* \returns key code, or `SDLK_UNKNOWN` if the name wasn't recognized; call
|
||||
* SDL_GetError() for more information.
|
||||
*
|
||||
|
|
@ -347,7 +357,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetKeyName(SDL_Keycode key);
|
|||
* \sa SDL_GetKeyName
|
||||
* \sa SDL_GetScancodeFromName
|
||||
*/
|
||||
extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name);
|
||||
extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name, SDL_bool uppercase);
|
||||
|
||||
/**
|
||||
* Start accepting Unicode text input events in a window.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue