include/SDL_keyboard.h
author Sam Lantinga <slouken@libsdl.org>
Sun, 02 Jun 2013 01:09:12 -0700
changeset 7258 89d47188c9a4
parent 7191 75360622e65f
child 7312 b36811d7db33
permissions -rw-r--r--
Fixed bug 1882 - SDL_GetKeyboardState should return const.

Yuri K. Schlesner

The array returned by SDL_GetKeyboardState is also used internally by SDL to keep track of pressed/released keys and must not be modified, lest weird behaviour occurs. Because of this I believe it's return type should be changed to return a const pointer, which will provide a code indication of that fact.
slouken@0
     1
/*
slouken@5535
     2
  Simple DirectMedia Layer
slouken@6885
     3
  Copyright (C) 1997-2013 Sam Lantinga <slouken@libsdl.org>
slouken@0
     4
slouken@5535
     5
  This software is provided 'as-is', without any express or implied
slouken@5535
     6
  warranty.  In no event will the authors be held liable for any damages
slouken@5535
     7
  arising from the use of this software.
slouken@0
     8
slouken@5535
     9
  Permission is granted to anyone to use this software for any purpose,
slouken@5535
    10
  including commercial applications, and to alter it and redistribute it
slouken@5535
    11
  freely, subject to the following restrictions:
slouken@0
    12
slouken@5535
    13
  1. The origin of this software must not be misrepresented; you must not
slouken@5535
    14
     claim that you wrote the original software. If you use this software
slouken@5535
    15
     in a product, an acknowledgment in the product documentation would be
slouken@5535
    16
     appreciated but is not required.
slouken@5535
    17
  2. Altered source versions must be plainly marked as such, and must not be
slouken@5535
    18
     misrepresented as being the original software.
slouken@5535
    19
  3. This notice may not be removed or altered from any source distribution.
slouken@0
    20
*/
slouken@0
    21
slouken@1895
    22
/**
slouken@3407
    23
 *  \file SDL_keyboard.h
slouken@7191
    24
 *
slouken@3407
    25
 *  Include file for SDL keyboard event handling
slouken@1895
    26
 */
slouken@0
    27
slouken@0
    28
#ifndef _SDL_keyboard_h
slouken@0
    29
#define _SDL_keyboard_h
slouken@0
    30
slouken@1356
    31
#include "SDL_stdinc.h"
slouken@1358
    32
#include "SDL_error.h"
slouken@5326
    33
#include "SDL_keycode.h"
slouken@4465
    34
#include "SDL_video.h"
slouken@0
    35
slouken@0
    36
#include "begin_code.h"
slouken@0
    37
/* Set up for C function definitions, even when using C++ */
slouken@0
    38
#ifdef __cplusplus
slouken@0
    39
extern "C" {
slouken@0
    40
#endif
slouken@0
    41
slouken@1895
    42
/**
slouken@3407
    43
 *  \brief The SDL keysym structure, used in key events.
slouken@0
    44
 */
slouken@5218
    45
typedef struct SDL_Keysym
slouken@1895
    46
{
slouken@5218
    47
    SDL_Scancode scancode;      /**< SDL physical key code - see ::SDL_Scancode for details */
slouken@5220
    48
    SDL_Keycode sym;            /**< SDL virtual key code - see ::SDL_Keycode for details */
slouken@1895
    49
    Uint16 mod;                 /**< current key modifiers */
slouken@3407
    50
    Uint32 unicode;             /**< \deprecated use SDL_TextInputEvent instead */
slouken@5218
    51
} SDL_Keysym;
slouken@0
    52
slouken@1895
    53
/* Function prototypes */
slouken@0
    54
slouken@1895
    55
/**
slouken@4465
    56
 *  \brief Get the window which currently has keyboard focus.
slouken@1895
    57
 */
slouken@4465
    58
extern DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void);
slouken@1895
    59
slouken@1895
    60
/**
slouken@4465
    61
 *  \brief Get a snapshot of the current state of the keyboard.
slouken@7191
    62
 *
slouken@3407
    63
 *  \param numkeys if non-NULL, receives the length of the returned array.
slouken@7191
    64
 *
slouken@5218
    65
 *  \return An array of key states. Indexes into this array are obtained by using ::SDL_Scancode values.
slouken@7191
    66
 *
slouken@3407
    67
 *  \b Example:
slouken@3407
    68
 *  \code
slouken@7258
    69
 *  const Uint8 *state = SDL_GetKeyboardState(NULL);
slouken@3407
    70
 *  if ( state[SDL_SCANCODE_RETURN] )   {
slouken@3407
    71
 *      printf("<RETURN> is pressed.\n");
slouken@3407
    72
 *  }
slouken@3407
    73
 *  \endcode
slouken@0
    74
 */
slouken@7258
    75
extern DECLSPEC const Uint8 *SDLCALL SDL_GetKeyboardState(int *numkeys);
slouken@0
    76
slouken@1895
    77
/**
slouken@4465
    78
 *  \brief Get the current key modifier state for the keyboard.
slouken@0
    79
 */
slouken@5220
    80
extern DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void);
slouken@0
    81
slouken@1895
    82
/**
slouken@4465
    83
 *  \brief Set the current key modifier state for the keyboard.
slouken@7191
    84
 *
slouken@3407
    85
 *  \note This does not change the keyboard state, only the key modifier flags.
slouken@0
    86
 */
slouken@5220
    87
extern DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate);
slouken@0
    88
slouken@1895
    89
/**
slouken@4465
    90
 *  \brief Get the key code corresponding to the given scancode according
slouken@4465
    91
 *         to the current keyboard layout.
slouken@7191
    92
 *
slouken@5220
    93
 *  See ::SDL_Keycode for details.
slouken@7191
    94
 *
slouken@3407
    95
 *  \sa SDL_GetKeyName()
slouken@0
    96
 */
slouken@5220
    97
extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode);
slouken@2268
    98
slouken@2268
    99
/**
slouken@3407
   100
 *  \brief Get the scancode corresponding to the given key code according to the
slouken@3407
   101
 *         current keyboard layout.
slouken@7191
   102
 *
slouken@5218
   103
 *  See ::SDL_Scancode for details.
slouken@7191
   104
 *
slouken@3407
   105
 *  \sa SDL_GetScancodeName()
slouken@2303
   106
 */
slouken@5220
   107
extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromKey(SDL_Keycode key);
slouken@2303
   108
slouken@2303
   109
/**
slouken@3407
   110
 *  \brief Get a human-readable name for a scancode.
slouken@7191
   111
 *
slouken@6029
   112
 *  \return A pointer to the name for the scancode.
slouken@6029
   113
 *          If the scancode doesn't have a name, this function returns
slouken@3407
   114
 *          an empty string ("").
slouken@2303
   115
 *
slouken@5218
   116
 *  \sa SDL_Scancode
slouken@2303
   117
 */
slouken@6029
   118
extern DECLSPEC const char *SDLCALL SDL_GetScancodeName(SDL_Scancode scancode);
slouken@6029
   119
slouken@6029
   120
/**
slouken@6029
   121
 *  \brief Get a scancode from a human-readable name
slouken@7191
   122
 *
slouken@6029
   123
 *  \return scancode, or SDL_SCANCODE_UNKNOWN if the name wasn't recognized
slouken@6029
   124
 *
slouken@6029
   125
 *  \sa SDL_Scancode
slouken@6029
   126
 */
slouken@6029
   127
extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *name);
slouken@2303
   128
slouken@2303
   129
/**
slouken@3407
   130
 *  \brief Get a human-readable name for a key.
slouken@7191
   131
 *
slouken@3407
   132
 *  \return A pointer to a UTF-8 string that stays valid at least until the next
slouken@7191
   133
 *          call to this function. If you need it around any longer, you must
slouken@7191
   134
 *          copy it.  If the key doesn't have a name, this function returns an
slouken@3407
   135
 *          empty string ("").
slouken@7191
   136
 *
slouken@5219
   137
 *  \sa SDL_Key
slouken@2268
   138
 */
slouken@5220
   139
extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDL_Keycode key);
slouken@0
   140
slouken@3280
   141
/**
slouken@6029
   142
 *  \brief Get a key code from a human-readable name
slouken@7191
   143
 *
slouken@6029
   144
 *  \return key code, or SDLK_UNKNOWN if the name wasn't recognized
slouken@6029
   145
 *
slouken@6029
   146
 *  \sa SDL_Keycode
slouken@6029
   147
 */
slouken@6029
   148
extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name);
slouken@6029
   149
slouken@6029
   150
/**
slouken@3407
   151
 *  \brief Start accepting Unicode text input events.
slouken@6654
   152
 *         This function will show the on-screen keyboard if supported.
slouken@7191
   153
 *
slouken@3407
   154
 *  \sa SDL_StopTextInput()
slouken@3407
   155
 *  \sa SDL_SetTextInputRect()
slouken@6654
   156
 *  \sa SDL_HasScreenKeyboardSupport()
slouken@3280
   157
 */
dewyatt@4753
   158
extern DECLSPEC void SDLCALL SDL_StartTextInput(void);
slouken@3280
   159
slouken@3280
   160
/**
slouken@6654
   161
 *  \brief Return whether or not Unicode text input events are enabled.
slouken@6654
   162
 *
slouken@6654
   163
 *  \sa SDL_StartTextInput()
slouken@6654
   164
 *  \sa SDL_StopTextInput()
slouken@6654
   165
 */
slouken@6654
   166
extern DECLSPEC SDL_bool SDLCALL SDL_IsTextInputActive(void);
slouken@6654
   167
slouken@6654
   168
/**
slouken@3407
   169
 *  \brief Stop receiving any text input events.
slouken@6654
   170
 *         This function will hide the on-screen keyboard if supported.
slouken@7191
   171
 *
slouken@3407
   172
 *  \sa SDL_StartTextInput()
slouken@6654
   173
 *  \sa SDL_HasScreenKeyboardSupport()
slouken@3280
   174
 */
dewyatt@4753
   175
extern DECLSPEC void SDLCALL SDL_StopTextInput(void);
slouken@3280
   176
slouken@3280
   177
/**
slouken@3407
   178
 *  \brief Set the rectangle used to type Unicode text inputs.
slouken@6654
   179
 *         This is used as a hint for IME and on-screen keyboard placement.
slouken@7191
   180
 *
slouken@3407
   181
 *  \sa SDL_StartTextInput()
slouken@3280
   182
 */
slouken@3280
   183
extern DECLSPEC void SDLCALL SDL_SetTextInputRect(SDL_Rect *rect);
slouken@3280
   184
slouken@6392
   185
/**
slouken@6392
   186
 *  \brief Returns whether the platform has some screen keyboard support.
slouken@7191
   187
 *
slouken@6392
   188
 *  \return SDL_TRUE if some keyboard support is available else SDL_FALSE.
slouken@7191
   189
 *
slouken@6392
   190
 *  \note Not all screen keyboard functions are supported on all platforms.
slouken@7191
   191
 *
slouken@6392
   192
 *  \sa SDL_IsScreenKeyboardShown()
slouken@6392
   193
 */
tim@6820
   194
extern DECLSPEC SDL_bool SDLCALL SDL_HasScreenKeyboardSupport(void);
slouken@6392
   195
slouken@6392
   196
/**
slouken@6392
   197
 *  \brief Returns whether the screen keyboard is shown for given window.
slouken@7191
   198
 *
slouken@6392
   199
 *  \param window The window for which screen keyboard should be queried.
slouken@7191
   200
 *
slouken@6392
   201
 *  \return SDL_TRUE if screen keyboard is shown else SDL_FALSE.
slouken@7191
   202
 *
slouken@6392
   203
 *  \sa SDL_HasScreenKeyboardSupport()
slouken@6392
   204
 */
slouken@6392
   205
extern DECLSPEC SDL_bool SDLCALL SDL_IsScreenKeyboardShown(SDL_Window *window);
slouken@0
   206
slouken@0
   207
/* Ends C function definitions when using C++ */
slouken@0
   208
#ifdef __cplusplus
slouken@0
   209
}
slouken@0
   210
#endif
slouken@0
   211
#include "close_code.h"
slouken@0
   212
slouken@0
   213
#endif /* _SDL_keyboard_h */
slouken@1895
   214
slouken@1895
   215
/* vi: set ts=4 sw=4 expandtab: */