Mercurial > sdl-ios-xcode

comparison include/SDL_keyboard.h @ 2303:d87417504c75

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
First pass implementation of new SDL scancode concept, as discussed with Christian Walther. Currently only implemented on Mac OS X for sanity checking purposes.
author Sam Lantinga <slouken@libsdl.org>
date Tue, 05 Feb 2008 07:19:23 +0000
parents 4baee598306d
children 99210400e8b9
comparison
equal deleted inserted replaced
2302:7ae1c419b626 2303:d87417504c75
46 * 46 *
47 * \brief The SDL keysym structure, used in key events. 47 * \brief The SDL keysym structure, used in key events.
48 */ 48 */
49 typedef struct SDL_keysym 49 typedef struct SDL_keysym
50 { 50 {
51 Uint8 scancode; /**< keyboard specific scancode */ 51 SDL_scancode scancode; /**< SDL physical key code - see ::SDL_scancode for details */
52 Uint8 padding[3]; /**< alignment padding */
53 SDLKey sym; /**< SDL virtual key code - see ::SDLKey for details */ 52 SDLKey sym; /**< SDL virtual key code - see ::SDLKey for details */
54 Uint16 mod; /**< current key modifiers */ 53 Uint16 mod; /**< current key modifiers */
55 Uint32 unicode; /**< OBSOLETE, use SDL_TextInputEvent instead */ 54 Uint32 unicode; /**< OBSOLETE, use SDL_TextInputEvent instead */
56 } SDL_keysym; 55 } SDL_keysym;
57 56
78 * \sa SDL_GetNumKeyboards() 77 * \sa SDL_GetNumKeyboards()
79 */ 78 */
80 extern DECLSPEC int SDLCALL SDL_SelectKeyboard(int index); 79 extern DECLSPEC int SDLCALL SDL_SelectKeyboard(int index);
81 80
82 /** 81 /**
83 * \fn int SDL_EnableUNICODE(int enable) 82 * \fn Uint8 *SDL_GetKeyboardState(int *numkeys)
84 *
85 * \brief Enable/Disable UNICODE translation of keyboard input.
86 *
87 * \param enable 1 to enable translation, 0 to disable translation, -1 to query translation
88 *
89 * \return The previous state of keyboard translation
90 *
91 * \note This translation has some overhead, so translation defaults off.
92 */
93 extern DECLSPEC int SDLCALL SDL_EnableUNICODE(int enable);
94
95 /**
96 * \fn Uint8 *SDL_GetKeyState(int *numkeys)
97 * 83 *
98 * \brief Get a snapshot of the current state of the selected keyboard. 84 * \brief Get a snapshot of the current state of the selected keyboard.
99 * 85 *
100 * \param numkeys if non-NULL, receives the length of the returned array. 86 * \param numkeys if non-NULL, receives the length of the returned array.
101 * 87 *
102 * \return An array of key states. Indexes into this array are obtained by using the SDLK_INDEX() macro on the \link ::SDLPhysicalKey SDLK_* \endlink syms. 88 * \return An array of key states. Indexes into this array are obtained by using ::SDL_scancode values.
103 * 89 *
104 * Example: 90 * Example:
105 * Uint8 *keystate = SDL_GetKeyState(NULL); 91 * Uint8 *state = SDL_GetKeyboardState(NULL);
106 * if ( keystate[SDLK_INDEX(SDLK_RETURN)] ) ... <RETURN> is pressed. 92 * if ( state[SDL_SCANCODE_RETURN)] ) ... <RETURN> is pressed.
107 */ 93 */
108 extern DECLSPEC Uint8 *SDLCALL SDL_GetKeyState(int *numkeys); 94 extern DECLSPEC Uint8 *SDLCALL SDL_GetKeyboardState(int *numkeys);
109 95
110 /** 96 /**
111 * \fn SDLMod SDL_GetModState(void) 97 * \fn SDLMod SDL_GetModState(void)
112 * 98 *
113 * \brief Get the current key modifier state for the selected keyboard. 99 * \brief Get the current key modifier state for the selected keyboard.
122 * \note This does not change the keyboard state, only the key modifier flags. 108 * \note This does not change the keyboard state, only the key modifier flags.
123 */ 109 */
124 extern DECLSPEC void SDLCALL SDL_SetModState(SDLMod modstate); 110 extern DECLSPEC void SDLCALL SDL_SetModState(SDLMod modstate);
125 111
126 /** 112 /**
127 * \fn SDLKey SDL_GetLayoutKey(SDLKey physicalKey) 113 * \fn SDLKey SDL_GetKeyFromScancode(SDL_scancode scancode)
128 * 114 *
129 * \brief Get the layout key code corresponding to the given physical key code according to the current keyboard layout. 115 * \brief Get the key code corresponding to the given scancode according to the current keyboard layout.
130 * 116 *
131 * See ::SDLKey for details. 117 * See ::SDLKey for details.
132 * 118 *
133 * If \a physicalKey is not a physical key code, it is returned unchanged.
134 *
135 * \sa SDL_GetKeyName() 119 * \sa SDL_GetKeyName()
136 */ 120 */
137 extern DECLSPEC SDLKey SDLCALL SDL_GetLayoutKey(SDLKey physicalKey); 121 extern DECLSPEC SDLKey SDLCALL SDL_GetKeyFromScancode(SDL_scancode scancode);
138 122
139 /** 123 /**
140 * \fn const char *SDL_GetKeyName(SDLKey layoutKey) 124 * \fn SDL_scancode SDL_GetScancodeFromKey(SDLKey key)
125 *
126 * \brief Get the scancode corresponding to the given key code according to the current keyboard layout.
127 *
128 * See ::SDL_scancode for details.
129 *
130 * \sa SDL_GetScancodeName()
131 */
132 extern DECLSPEC SDL_scancode SDLCALL SDL_GetScancodeFromKey(SDLKey key);
133
134 /**
135 * \fn const char *SDL_GetScancodeName(SDL_scancode scancode)
136 *
137 * \brief Get a human-readable name for a scancode.
138 *
139 * \return A pointer to a UTF-8 string that stays valid at least until the next call to this function. If you need it around any longer, you must copy it. If the scancode doesn't have a name, this function returns "".
140 *
141 * \sa SDL_scancode
142 */
143 extern DECLSPEC const char *SDLCALL SDL_GetScancodeName(SDL_scancode
144 scancode);
145
146 /**
147 * \fn const char *SDL_GetKeyName(SDLKey key)
141 * 148 *
142 * \brief Get a human-readable name for a key. 149 * \brief Get a human-readable name for a key.
143 * 150 *
144 * \param layoutKey An SDL layout key code. 151 * \return A pointer to a UTF-8 string that stays valid at least until the next call to this function. If you need it around any longer, you must copy it. If the key doesn't have a name, this function returns "".
145 *
146 * If what you have is a physical key code, e.g. from the \link SDL_keysym::sym key.keysym.sym \endlink field of the SDL_Event structure, convert it to a layout key code using SDL_GetLayoutKey() first. Doing this ensures that the returned name matches what users see on their keyboards. Calling this function directly on a physical key code (that is not also a layout key code) is possible, but is not recommended except for debugging purposes. The name returned in that case is the name of the \link ::SDLPhysicalKey SDLK_* \endlink constant and is not suitable for display to users.
147 *
148 * \return A pointer to a UTF-8 string that stays valid at least until the next call to this function. If you need it around any longer, you must copy it. Always non-NULL.
149 * 152 *
150 * \sa SDLKey 153 * \sa SDLKey
151 */ 154 */
152 extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDLKey layoutKey); 155 extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDLKey key);
153 156
154 157
155 /* Ends C function definitions when using C++ */ 158 /* Ends C function definitions when using C++ */
156 #ifdef __cplusplus 159 #ifdef __cplusplus
157 /* *INDENT-OFF* */ 160 /* *INDENT-OFF* */