Mercurial > sdl-ios-xcode

comparison include/SDL_keyboard.h @ 3407:d3baf5ac4e37

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Partial fix for bug #859 Header file update from Ken for improved doxygen output
author Sam Lantinga <slouken@libsdl.org>
date Mon, 19 Oct 2009 13:31:58 +0000
parents 00cace2d9080
children f7b03b6838cb
comparison
equal deleted inserted replaced
3406:8ae607392409 3407:d3baf5ac4e37
19 Sam Lantinga 19 Sam Lantinga
20 slouken@libsdl.org 20 slouken@libsdl.org
21 */ 21 */
22 22
23 /** 23 /**
24 * \file SDL_keyboard.h 24 * \file SDL_keyboard.h
25 * 25 *
26 * Include file for SDL keyboard event handling 26 * Include file for SDL keyboard event handling
27 */ 27 */
28 28
29 #ifndef _SDL_keyboard_h 29 #ifndef _SDL_keyboard_h
30 #define _SDL_keyboard_h 30 #define _SDL_keyboard_h
31 31
40 extern "C" { 40 extern "C" {
41 /* *INDENT-ON* */ 41 /* *INDENT-ON* */
42 #endif 42 #endif
43 43
44 /** 44 /**
45 * \struct SDL_keysym 45 * \brief The SDL keysym structure, used in key events.
46 *
47 * \brief The SDL keysym structure, used in key events.
48 */ 46 */
49 typedef struct SDL_keysym 47 typedef struct SDL_keysym
50 { 48 {
51 SDL_scancode scancode; /**< SDL physical key code - see ::SDL_scancode for details */ 49 SDL_scancode scancode; /**< SDL physical key code - see ::SDL_scancode for details */
52 SDLKey sym; /**< SDL virtual key code - see ::SDLKey for details */ 50 SDLKey sym; /**< SDL virtual key code - see ::SDLKey for details */
53 Uint16 mod; /**< current key modifiers */ 51 Uint16 mod; /**< current key modifiers */
54 Uint32 unicode; /**< OBSOLETE, use SDL_TextInputEvent instead */ 52 Uint32 unicode; /**< \deprecated use SDL_TextInputEvent instead */
55 } SDL_keysym; 53 } SDL_keysym;
56 54
57 /* Function prototypes */ 55 /* Function prototypes */
58 56
59 /** 57 /**
60 * \fn int SDL_GetNumKeyboards(void) 58 * \brief Get the number of keyboard input devices available.
61 * 59 *
62 * \brief Get the number of keyboard input devices available. 60 * \sa SDL_SelectKeyboard()
63 *
64 * \sa SDL_SelectKeyboard()
65 */ 61 */
66 extern DECLSPEC int SDLCALL SDL_GetNumKeyboards(void); 62 extern DECLSPEC int SDLCALL SDL_GetNumKeyboards(void);
67 63
68 /** 64 /**
69 * \fn int SDL_SelectKeyboard(int index) 65 * \brief Set the index of the currently selected keyboard.
70 * 66 *
71 * \brief Set the index of the currently selected keyboard. 67 * \return The index of the previously selected keyboard.
72 * 68 *
73 * \return The index of the previously selected keyboard. 69 * \note You can query the currently selected keyboard by passing an index of -1.
74 * 70 *
75 * \note You can query the currently selected keyboard by passing an index of -1. 71 * \sa SDL_GetNumKeyboards()
76 *
77 * \sa SDL_GetNumKeyboards()
78 */ 72 */
79 extern DECLSPEC int SDLCALL SDL_SelectKeyboard(int index); 73 extern DECLSPEC int SDLCALL SDL_SelectKeyboard(int index);
80 74
81 /** 75 /**
82 * \fn Uint8 *SDL_GetKeyboardState(int *numkeys) 76 * \brief Get a snapshot of the current state of the selected keyboard.
83 * 77 *
84 * \brief Get a snapshot of the current state of the selected keyboard. 78 * \param numkeys if non-NULL, receives the length of the returned array.
85 * 79 *
86 * \param numkeys if non-NULL, receives the length of the returned array. 80 * \return An array of key states. Indexes into this array are obtained by using ::SDL_scancode values.
87 * 81 *
88 * \return An array of key states. Indexes into this array are obtained by using ::SDL_scancode values. 82 * \b Example:
89 * 83 * \code
90 * Example: 84 * Uint8 *state = SDL_GetKeyboardState(NULL);
91 * Uint8 *state = SDL_GetKeyboardState(NULL); 85 * if ( state[SDL_SCANCODE_RETURN] ) {
92 * if ( state[SDL_SCANCODE_RETURN)] ) ... <RETURN> is pressed. 86 * printf("<RETURN> is pressed.\n");
87 * }
88 * \endcode
93 */ 89 */
94 extern DECLSPEC Uint8 *SDLCALL SDL_GetKeyboardState(int *numkeys); 90 extern DECLSPEC Uint8 *SDLCALL SDL_GetKeyboardState(int *numkeys);
95 91
96 /** 92 /**
97 * \fn SDLMod SDL_GetModState(void) 93 * \brief Get the current key modifier state for the selected keyboard.
98 *
99 * \brief Get the current key modifier state for the selected keyboard.
100 */ 94 */
101 extern DECLSPEC SDLMod SDLCALL SDL_GetModState(void); 95 extern DECLSPEC SDLMod SDLCALL SDL_GetModState(void);
102 96
103 /** 97 /**
104 * \fn void SDL_SetModState(SDLMod modstate) 98 * \brief Set the current key modifier state for the selected keyboard.
105 * 99 *
106 * \brief Set the current key modifier state for the selected keyboard. 100 * \note This does not change the keyboard state, only the key modifier flags.
107 *
108 * \note This does not change the keyboard state, only the key modifier flags.
109 */ 101 */
110 extern DECLSPEC void SDLCALL SDL_SetModState(SDLMod modstate); 102 extern DECLSPEC void SDLCALL SDL_SetModState(SDLMod modstate);
111 103
112 /** 104 /**
113 * \fn SDLKey SDL_GetKeyFromScancode(SDL_scancode scancode) 105 * \brief Get the key code corresponding to the given scancode according to the
114 * 106 * current keyboard layout.
115 * \brief Get the key code corresponding to the given scancode according to the current keyboard layout. 107 *
116 * 108 * See ::SDLKey for details.
117 * See ::SDLKey for details. 109 *
118 * 110 * \sa SDL_GetKeyName()
119 * \sa SDL_GetKeyName()
120 */ 111 */
121 extern DECLSPEC SDLKey SDLCALL SDL_GetKeyFromScancode(SDL_scancode scancode); 112 extern DECLSPEC SDLKey SDLCALL SDL_GetKeyFromScancode(SDL_scancode scancode);
122 113
123 /** 114 /**
124 * \fn SDL_scancode SDL_GetScancodeFromKey(SDLKey key) 115 * \brief Get the scancode corresponding to the given key code according to the
125 * 116 * current keyboard layout.
126 * \brief Get the scancode corresponding to the given key code according to the current keyboard layout. 117 *
127 * 118 * See ::SDL_scancode for details.
128 * See ::SDL_scancode for details. 119 *
129 * 120 * \sa SDL_GetScancodeName()
130 * \sa SDL_GetScancodeName()
131 */ 121 */
132 extern DECLSPEC SDL_scancode SDLCALL SDL_GetScancodeFromKey(SDLKey key); 122 extern DECLSPEC SDL_scancode SDLCALL SDL_GetScancodeFromKey(SDLKey key);
133 123
134 /** 124 /**
135 * \fn const char *SDL_GetScancodeName(SDL_scancode scancode) 125 * \brief Get a human-readable name for a scancode.
136 * 126 *
137 * \brief Get a human-readable name for a scancode. 127 * \return A pointer to a UTF-8 string that stays valid at least until the next
128 * call to this function. If you need it around any longer, you must
129 * copy it. If the scancode doesn't have a name, this function returns
130 * an empty string ("").
138 * 131 *
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 "". 132 * \sa SDL_scancode
140 *
141 * \sa SDL_scancode
142 */ 133 */
143 extern DECLSPEC const char *SDLCALL SDL_GetScancodeName(SDL_scancode 134 extern DECLSPEC const char *SDLCALL SDL_GetScancodeName(SDL_scancode
144 scancode); 135 scancode);
145 136
146 /** 137 /**
147 * \fn const char *SDL_GetKeyName(SDLKey key) 138 * \brief Get a human-readable name for a key.
148 * 139 *
149 * \brief Get a human-readable name for a key. 140 * \return A pointer to a UTF-8 string that stays valid at least until the next
150 * 141 * call to this function. If you need it around any longer, you must
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 "". 142 * copy it. If the key doesn't have a name, this function returns an
152 * 143 * empty string ("").
153 * \sa SDLKey 144 *
145 * \sa SDLKey
154 */ 146 */
155 extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDLKey key); 147 extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDLKey key);
156 148
157 /** 149 /**
158 * \fn void SDL_StartTextInput(void) 150 * \brief Start accepting Unicode text input events.
159 * 151 *
160 * \brief Start accepting Unicode text input events. 152 * \sa SDL_StopTextInput()
161 * 153 * \sa SDL_SetTextInputRect()
162 * \sa SDL_StopTextInput()
163 * \sa SDL_SetTextInputRect()
164 */ 154 */
165 extern DECLSPEC void SDLCALL SDL_StartTextInput(void); 155 extern DECLSPEC void SDLCALL SDL_StartTextInput(void);
166 156
167 /** 157 /**
168 * \fn void SDL_StopTextInput(void) 158 * \brief Stop receiving any text input events.
169 * 159 *
170 * \brief Stop receiving any text input events. 160 * \sa SDL_StartTextInput()
171 *
172 * \sa SDL_StartTextInput()
173 */ 161 */
174 extern DECLSPEC void SDLCALL SDL_StopTextInput(void); 162 extern DECLSPEC void SDLCALL SDL_StopTextInput(void);
175 163
176 /** 164 /**
177 * \fn void SDL_SetTextInputRect(SDL_Rect *rect) 165 * \brief Set the rectangle used to type Unicode text inputs.
178 * 166 *
179 * \brief Set the rectangle used to type Unicode text inputs. 167 * \sa SDL_StartTextInput()
180 *
181 * \sa SDL_StartTextInput()
182 */ 168 */
183 extern DECLSPEC void SDLCALL SDL_SetTextInputRect(SDL_Rect *rect); 169 extern DECLSPEC void SDLCALL SDL_SetTextInputRect(SDL_Rect *rect);
184 170
185 171
186 /* Ends C function definitions when using C++ */ 172 /* Ends C function definitions when using C++ */