dep/sdl/include/SDL_keyboard.h

   1 /*
   2   Simple DirectMedia Layer
   3   Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
   4
   5   This software is provided 'as-is', without any express or implied
   6   warranty.  In no event will the authors be held liable for any damages
   7   arising from the use of this software.
   8
   9   Permission is granted to anyone to use this software for any purpose,
  10   including commercial applications, and to alter it and redistribute it
  11   freely, subject to the following restrictions:
  12
  13   1. The origin of this software must not be misrepresented; you must not
  14      claim that you wrote the original software. If you use this software
  15      in a product, an acknowledgment in the product documentation would be
  16      appreciated but is not required.
  17   2. Altered source versions must be plainly marked as such, and must not be
  18      misrepresented as being the original software.
  19   3. This notice may not be removed or altered from any source distribution.
  20 */
  21
  22 /**
  23  *  \file SDL_keyboard.h
  24  *
  25  *  Include file for SDL keyboard event handling
  26  */
  27
  28 #ifndef SDL_keyboard_h_
  29 #define SDL_keyboard_h_
  30
  31 #include "SDL_stdinc.h"
  32 #include "SDL_error.h"
  33 #include "SDL_keycode.h"
  34 #include "SDL_video.h"
  35
  36 #include "begin_code.h"
  37 /* Set up for C function definitions, even when using C++ */
  38 #ifdef __cplusplus
  39 extern "C" {
  40 #endif
  41
  42 /**
  43  *  \brief The SDL keysym structure, used in key events.
  44  *
  45  *  \note  If you are looking for translated character input, see the ::SDL_TEXTINPUT event.
  46  */
  47 typedef struct SDL_Keysym
  48 {
  49     SDL_Scancode scancode;      /**< SDL physical key code - see ::SDL_Scancode for details */
  50     SDL_Keycode sym;            /**< SDL virtual key code - see ::SDL_Keycode for details */
  51     Uint16 mod;                 /**< current key modifiers */
  52     Uint32 unused;
  53 } SDL_Keysym;
  54
  55 /* Function prototypes */
  56
  57 /**
  58  * Query the window which currently has keyboard focus.
  59  *
  60  * \returns the window with keyboard focus.
  61  *
  62  * \since This function is available since SDL 2.0.0.
  63  */
  64 extern DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void);
  65
  66 /**
  67  * Get a snapshot of the current state of the keyboard.
  68  *
  69  * The pointer returned is a pointer to an internal SDL array. It will be
  70  * valid for the whole lifetime of the application and should not be freed by
  71  * the caller.
  72  *
  73  * A array element with a value of 1 means that the key is pressed and a value
  74  * of 0 means that it is not. Indexes into this array are obtained by using
  75  * SDL_Scancode values.
  76  *
  77  * Use SDL_PumpEvents() to update the state array.
  78  *
  79  * This function gives you the current state after all events have been
  80  * processed, so if a key or button has been pressed and released before you
  81  * process events, then the pressed state will never show up in the
  82  * SDL_GetKeyboardState() calls.
  83  *
  84  * Note: This function doesn't take into account whether shift has been
  85  * pressed or not.
  86  *
  87  * \param numkeys if non-NULL, receives the length of the returned array
  88  * \returns a pointer to an array of key states.
  89  *
  90  * \since This function is available since SDL 2.0.0.
  91  *
  92  * \sa SDL_PumpEvents
  93  * \sa SDL_ResetKeyboard
  94  */
  95 extern DECLSPEC const Uint8 *SDLCALL SDL_GetKeyboardState(int *numkeys);
  96
  97 /**
  98  * Clear the state of the keyboard
  99  *
 100  * This function will generate key up events for all pressed keys.
 101  *
 102  * \since This function is available since SDL 2.24.0.
 103  *
 104  * \sa SDL_GetKeyboardState
 105  */
 106 extern DECLSPEC void SDLCALL SDL_ResetKeyboard(void);
 107
 108 /**
 109  * Get the current key modifier state for the keyboard.
 110  *
 111  * \returns an OR'd combination of the modifier keys for the keyboard. See
 112  *          SDL_Keymod for details.
 113  *
 114  * \since This function is available since SDL 2.0.0.
 115  *
 116  * \sa SDL_GetKeyboardState
 117  * \sa SDL_SetModState
 118  */
 119 extern DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void);
 120
 121 /**
 122  * Set the current key modifier state for the keyboard.
 123  *
 124  * The inverse of SDL_GetModState(), SDL_SetModState() allows you to impose
 125  * modifier key states on your application. Simply pass your desired modifier
 126  * states into `modstate`. This value may be a bitwise, OR'd combination of
 127  * SDL_Keymod values.
 128  *
 129  * This does not change the keyboard state, only the key modifier flags that
 130  * SDL reports.
 131  *
 132  * \param modstate the desired SDL_Keymod for the keyboard
 133  *
 134  * \since This function is available since SDL 2.0.0.
 135  *
 136  * \sa SDL_GetModState
 137  */
 138 extern DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate);
 139
 140 /**
 141  * Get the key code corresponding to the given scancode according to the
 142  * current keyboard layout.
 143  *
 144  * See SDL_Keycode for details.
 145  *
 146  * \param scancode the desired SDL_Scancode to query
 147  * \returns the SDL_Keycode that corresponds to the given SDL_Scancode.
 148  *
 149  * \since This function is available since SDL 2.0.0.
 150  *
 151  * \sa SDL_GetKeyName
 152  * \sa SDL_GetScancodeFromKey
 153  */
 154 extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode);
 155
 156 /**
 157  * Get the scancode corresponding to the given key code according to the
 158  * current keyboard layout.
 159  *
 160  * See SDL_Scancode for details.
 161  *
 162  * \param key the desired SDL_Keycode to query
 163  * \returns the SDL_Scancode that corresponds to the given SDL_Keycode.
 164  *
 165  * \since This function is available since SDL 2.0.0.
 166  *
 167  * \sa SDL_GetKeyFromScancode
 168  * \sa SDL_GetScancodeName
 169  */
 170 extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromKey(SDL_Keycode key);
 171
 172 /**
 173  * Get a human-readable name for a scancode.
 174  *
 175  * See SDL_Scancode for details.
 176  *
 177  * **Warning**: The returned name is by design not stable across platforms,
 178  * e.g. the name for `SDL_SCANCODE_LGUI` is "Left GUI" under Linux but "Left
 179  * Windows" under Microsoft Windows, and some scancodes like
 180  * `SDL_SCANCODE_NONUSBACKSLASH` don't have any name at all. There are even
 181  * scancodes that share names, e.g. `SDL_SCANCODE_RETURN` and
 182  * `SDL_SCANCODE_RETURN2` (both called "Return"). This function is therefore
 183  * unsuitable for creating a stable cross-platform two-way mapping between
 184  * strings and scancodes.
 185  *
 186  * \param scancode the desired SDL_Scancode to query
 187  * \returns a pointer to the name for the scancode. If the scancode doesn't
 188  *          have a name this function returns an empty string ("").
 189  *
 190  * \since This function is available since SDL 2.0.0.
 191  *
 192  * \sa SDL_GetScancodeFromKey
 193  * \sa SDL_GetScancodeFromName
 194  */
 195 extern DECLSPEC const char *SDLCALL SDL_GetScancodeName(SDL_Scancode scancode);
 196
 197 /**
 198  * Get a scancode from a human-readable name.
 199  *
 200  * \param name the human-readable scancode name
 201  * \returns the SDL_Scancode, or `SDL_SCANCODE_UNKNOWN` if the name wasn't
 202  *          recognized; call SDL_GetError() for more information.
 203  *
 204  * \since This function is available since SDL 2.0.0.
 205  *
 206  * \sa SDL_GetKeyFromName
 207  * \sa SDL_GetScancodeFromKey
 208  * \sa SDL_GetScancodeName
 209  */
 210 extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *name);
 211
 212 /**
 213  * Get a human-readable name for a key.
 214  *
 215  * See SDL_Scancode and SDL_Keycode for details.
 216  *
 217  * \param key the desired SDL_Keycode to query
 218  * \returns a pointer to a UTF-8 string that stays valid at least until the
 219  *          next call to this function. If you need it around any longer, you
 220  *          must copy it. If the key doesn't have a name, this function
 221  *          returns an empty string ("").
 222  *
 223  * \since This function is available since SDL 2.0.0.
 224  *
 225  * \sa SDL_GetKeyFromName
 226  * \sa SDL_GetKeyFromScancode
 227  * \sa SDL_GetScancodeFromKey
 228  */
 229 extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDL_Keycode key);
 230
 231 /**
 232  * Get a key code from a human-readable name.
 233  *
 234  * \param name the human-readable key name
 235  * \returns key code, or `SDLK_UNKNOWN` if the name wasn't recognized; call
 236  *          SDL_GetError() for more information.
 237  *
 238  * \since This function is available since SDL 2.0.0.
 239  *
 240  * \sa SDL_GetKeyFromScancode
 241  * \sa SDL_GetKeyName
 242  * \sa SDL_GetScancodeFromName
 243  */
 244 extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name);
 245
 246 /**
 247  * Start accepting Unicode text input events.
 248  *
 249  * This function will start accepting Unicode text input events in the focused
 250  * SDL window, and start emitting SDL_TextInputEvent (SDL_TEXTINPUT) and
 251  * SDL_TextEditingEvent (SDL_TEXTEDITING) events. Please use this function in
 252  * pair with SDL_StopTextInput().
 253  *
 254  * On some platforms using this function activates the screen keyboard.
 255  *
 256  * \since This function is available since SDL 2.0.0.
 257  *
 258  * \sa SDL_SetTextInputRect
 259  * \sa SDL_StopTextInput
 260  */
 261 extern DECLSPEC void SDLCALL SDL_StartTextInput(void);
 262
 263 /**
 264  * Check whether or not Unicode text input events are enabled.
 265  *
 266  * \returns SDL_TRUE if text input events are enabled else SDL_FALSE.
 267  *
 268  * \since This function is available since SDL 2.0.0.
 269  *
 270  * \sa SDL_StartTextInput
 271  */
 272 extern DECLSPEC SDL_bool SDLCALL SDL_IsTextInputActive(void);
 273
 274 /**
 275  * Stop receiving any text input events.
 276  *
 277  * \since This function is available since SDL 2.0.0.
 278  *
 279  * \sa SDL_StartTextInput
 280  */
 281 extern DECLSPEC void SDLCALL SDL_StopTextInput(void);
 282
 283 /**
 284  * Dismiss the composition window/IME without disabling the subsystem.
 285  *
 286  * \since This function is available since SDL 2.0.22.
 287  *
 288  * \sa SDL_StartTextInput
 289  * \sa SDL_StopTextInput
 290  */
 291 extern DECLSPEC void SDLCALL SDL_ClearComposition(void);
 292
 293 /**
 294  * Returns if an IME Composite or Candidate window is currently shown.
 295  *
 296  * \since This function is available since SDL 2.0.22.
 297  */
 298 extern DECLSPEC SDL_bool SDLCALL SDL_IsTextInputShown(void);
 299
 300 /**
 301  * Set the rectangle used to type Unicode text inputs.
 302  *
 303  * To start text input in a given location, this function is intended to be
 304  * called before SDL_StartTextInput, although some platforms support moving
 305  * the rectangle even while text input (and a composition) is active.
 306  *
 307  * Note: If you want to use the system native IME window, try setting hint
 308  * **SDL_HINT_IME_SHOW_UI** to **1**, otherwise this function won't give you
 309  * any feedback.
 310  *
 311  * \param rect the SDL_Rect structure representing the rectangle to receive
 312  *             text (ignored if NULL)
 313  *
 314  * \since This function is available since SDL 2.0.0.
 315  *
 316  * \sa SDL_StartTextInput
 317  */
 318 extern DECLSPEC void SDLCALL SDL_SetTextInputRect(const SDL_Rect *rect);
 319
 320 /**
 321  * Check whether the platform has screen keyboard support.
 322  *
 323  * \returns SDL_TRUE if the platform has some screen keyboard support or
 324  *          SDL_FALSE if not.
 325  *
 326  * \since This function is available since SDL 2.0.0.
 327  *
 328  * \sa SDL_StartTextInput
 329  * \sa SDL_IsScreenKeyboardShown
 330  */
 331 extern DECLSPEC SDL_bool SDLCALL SDL_HasScreenKeyboardSupport(void);
 332
 333 /**
 334  * Check whether the screen keyboard is shown for given window.
 335  *
 336  * \param window the window for which screen keyboard should be queried
 337  * \returns SDL_TRUE if screen keyboard is shown or SDL_FALSE if not.
 338  *
 339  * \since This function is available since SDL 2.0.0.
 340  *
 341  * \sa SDL_HasScreenKeyboardSupport
 342  */
 343 extern DECLSPEC SDL_bool SDLCALL SDL_IsScreenKeyboardShown(SDL_Window *window);
 344
 345 /* Ends C function definitions when using C++ */
 346 #ifdef __cplusplus
 347 }
 348 #endif
 349 #include "close_code.h"
 350
 351 #endif /* SDL_keyboard_h_ */
 352
 353 /* vi: set ts=4 sw=4 expandtab: */