include/SDL_keyboard.h
author Sam Lantinga <slouken@libsdl.org>
Sat, 11 Aug 2012 10:15:59 -0700
changeset 6392 fa7eb111f994
parent 6138 4c64952a58fb
child 6654 2ecfb25be1e2
permissions -rw-r--r--
Fixed bug 1564 - SDL has no function to open a screen keyboard on Android.

Philipp Wiesemann implemented a general on-screen keyboard API for SDL, and I switched iOS code over to use it.
slouken@0
     1
/*
slouken@5535
     2
  Simple DirectMedia Layer
slouken@6138
     3
  Copyright (C) 1997-2012 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@3407
    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@1895
    39
/* *INDENT-OFF* */
slouken@0
    40
extern "C" {
slouken@1895
    41
/* *INDENT-ON* */
slouken@0
    42
#endif
slouken@0
    43
slouken@1895
    44
/**
slouken@3407
    45
 *  \brief The SDL keysym structure, used in key events.
slouken@0
    46
 */
slouken@5218
    47
typedef struct SDL_Keysym
slouken@1895
    48
{
slouken@5218
    49
    SDL_Scancode scancode;      /**< SDL physical key code - see ::SDL_Scancode for details */
slouken@5220
    50
    SDL_Keycode sym;            /**< SDL virtual key code - see ::SDL_Keycode for details */
slouken@1895
    51
    Uint16 mod;                 /**< current key modifiers */
slouken@3407
    52
    Uint32 unicode;             /**< \deprecated use SDL_TextInputEvent instead */
slouken@5218
    53
} SDL_Keysym;
slouken@0
    54
slouken@1895
    55
/* Function prototypes */
slouken@0
    56
slouken@1895
    57
/**
slouken@4465
    58
 *  \brief Get the window which currently has keyboard focus.
slouken@1895
    59
 */
slouken@4465
    60
extern DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void);
slouken@1895
    61
slouken@1895
    62
/**
slouken@4465
    63
 *  \brief Get a snapshot of the current state of the keyboard.
slouken@3407
    64
 *  
slouken@3407
    65
 *  \param numkeys if non-NULL, receives the length of the returned array.
slouken@3407
    66
 *  
slouken@5218
    67
 *  \return An array of key states. Indexes into this array are obtained by using ::SDL_Scancode values.
slouken@3407
    68
 *  
slouken@3407
    69
 *  \b Example:
slouken@3407
    70
 *  \code
slouken@3407
    71
 *  Uint8 *state = SDL_GetKeyboardState(NULL);
slouken@3407
    72
 *  if ( state[SDL_SCANCODE_RETURN] )   {
slouken@3407
    73
 *      printf("<RETURN> is pressed.\n");
slouken@3407
    74
 *  }
slouken@3407
    75
 *  \endcode
slouken@0
    76
 */
slouken@2303
    77
extern DECLSPEC Uint8 *SDLCALL SDL_GetKeyboardState(int *numkeys);
slouken@0
    78
slouken@1895
    79
/**
slouken@4465
    80
 *  \brief Get the current key modifier state for the keyboard.
slouken@0
    81
 */
slouken@5220
    82
extern DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void);
slouken@0
    83
slouken@1895
    84
/**
slouken@4465
    85
 *  \brief Set the current key modifier state for the keyboard.
slouken@3407
    86
 *  
slouken@3407
    87
 *  \note This does not change the keyboard state, only the key modifier flags.
slouken@0
    88
 */
slouken@5220
    89
extern DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate);
slouken@0
    90
slouken@1895
    91
/**
slouken@4465
    92
 *  \brief Get the key code corresponding to the given scancode according
slouken@4465
    93
 *         to the current keyboard layout.
slouken@3407
    94
 *  
slouken@5220
    95
 *  See ::SDL_Keycode for details.
slouken@3407
    96
 *  
slouken@3407
    97
 *  \sa SDL_GetKeyName()
slouken@0
    98
 */
slouken@5220
    99
extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode);
slouken@2268
   100
slouken@2268
   101
/**
slouken@3407
   102
 *  \brief Get the scancode corresponding to the given key code according to the
slouken@3407
   103
 *         current keyboard layout.
slouken@3407
   104
 *  
slouken@5218
   105
 *  See ::SDL_Scancode for details.
slouken@3407
   106
 *  
slouken@3407
   107
 *  \sa SDL_GetScancodeName()
slouken@2303
   108
 */
slouken@5220
   109
extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromKey(SDL_Keycode key);
slouken@2303
   110
slouken@2303
   111
/**
slouken@3407
   112
 *  \brief Get a human-readable name for a scancode.
slouken@3407
   113
 *  
slouken@6029
   114
 *  \return A pointer to the name for the scancode.
slouken@6029
   115
 *          If the scancode doesn't have a name, this function returns
slouken@3407
   116
 *          an empty string ("").
slouken@2303
   117
 *
slouken@5218
   118
 *  \sa SDL_Scancode
slouken@2303
   119
 */
slouken@6029
   120
extern DECLSPEC const char *SDLCALL SDL_GetScancodeName(SDL_Scancode scancode);
slouken@6029
   121
slouken@6029
   122
/**
slouken@6029
   123
 *  \brief Get a scancode from a human-readable name
slouken@6029
   124
 *  
slouken@6029
   125
 *  \return scancode, or SDL_SCANCODE_UNKNOWN if the name wasn't recognized
slouken@6029
   126
 *
slouken@6029
   127
 *  \sa SDL_Scancode
slouken@6029
   128
 */
slouken@6029
   129
extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *name);
slouken@2303
   130
slouken@2303
   131
/**
slouken@3407
   132
 *  \brief Get a human-readable name for a key.
slouken@3407
   133
 *  
slouken@3407
   134
 *  \return A pointer to a UTF-8 string that stays valid at least until the next
slouken@3407
   135
 *          call to this function. If you need it around any longer, you must 
slouken@3407
   136
 *          copy it.  If the key doesn't have a name, this function returns an 
slouken@3407
   137
 *          empty string ("").
slouken@3407
   138
 *  
slouken@5219
   139
 *  \sa SDL_Key
slouken@2268
   140
 */
slouken@5220
   141
extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDL_Keycode key);
slouken@0
   142
slouken@3280
   143
/**
slouken@6029
   144
 *  \brief Get a key code from a human-readable name
slouken@6029
   145
 *  
slouken@6029
   146
 *  \return key code, or SDLK_UNKNOWN if the name wasn't recognized
slouken@6029
   147
 *
slouken@6029
   148
 *  \sa SDL_Keycode
slouken@6029
   149
 */
slouken@6029
   150
extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name);
slouken@6029
   151
slouken@6029
   152
/**
slouken@3407
   153
 *  \brief Start accepting Unicode text input events.
slouken@3407
   154
 *  
slouken@3407
   155
 *  \sa SDL_StopTextInput()
slouken@3407
   156
 *  \sa SDL_SetTextInputRect()
slouken@3280
   157
 */
dewyatt@4753
   158
extern DECLSPEC void SDLCALL SDL_StartTextInput(void);
slouken@3280
   159
slouken@3280
   160
/**
slouken@3407
   161
 *  \brief Stop receiving any text input events.
slouken@3407
   162
 *  
slouken@3407
   163
 *  \sa SDL_StartTextInput()
slouken@3280
   164
 */
dewyatt@4753
   165
extern DECLSPEC void SDLCALL SDL_StopTextInput(void);
slouken@3280
   166
slouken@3280
   167
/**
slouken@3407
   168
 *  \brief Set the rectangle used to type Unicode text inputs.
slouken@3407
   169
 *  
slouken@3407
   170
 *  \sa SDL_StartTextInput()
slouken@3280
   171
 */
slouken@3280
   172
extern DECLSPEC void SDLCALL SDL_SetTextInputRect(SDL_Rect *rect);
slouken@3280
   173
slouken@6392
   174
/**
slouken@6392
   175
 *  \brief Returns whether the platform has some screen keyboard support.
slouken@6392
   176
 *  
slouken@6392
   177
 *  \param window The window for which screen keyboard should be checked.
slouken@6392
   178
 *  
slouken@6392
   179
 *  \return SDL_TRUE if some keyboard support is available else SDL_FALSE.
slouken@6392
   180
 *  
slouken@6392
   181
 *  \note Not all screen keyboard functions are supported on all platforms.
slouken@6392
   182
 *  
slouken@6392
   183
 *  \sa SDL_ShowScreenKeyboard()
slouken@6392
   184
 *  \sa SDL_HideScreenKeyboard()
slouken@6392
   185
 *  \sa SDL_IsScreenKeyboardShown()
slouken@6392
   186
 *  \sa SDL_ToggleScreenKeyboard()
slouken@6392
   187
 */
slouken@6392
   188
extern DECLSPEC SDL_bool SDLCALL SDL_HasScreenKeyboardSupport(SDL_Window *window);
slouken@6392
   189
slouken@6392
   190
/**
slouken@6392
   191
 *  \brief Requests to show a screen keyboard for given window.
slouken@6392
   192
 *  
slouken@6392
   193
 *  \param window The window for which screen keyboard should be shown.
slouken@6392
   194
 *  
slouken@6392
   195
 *  \return 0 if request will be processed or -1 on error (e.g. no support).
slouken@6392
   196
 *  
slouken@6392
   197
 *  \note Showing screen keyboards is asynchronous on some platforms.
slouken@6392
   198
 *  
slouken@6392
   199
 *  \sa SDL_HasScreenKeyboardSupport()
slouken@6392
   200
 *  \sa SDL_HideScreenKeyboard()
slouken@6392
   201
 */
slouken@6392
   202
extern DECLSPEC int SDLCALL SDL_ShowScreenKeyboard(SDL_Window *window);
slouken@6392
   203
slouken@6392
   204
/**
slouken@6392
   205
 *  \brief Requests to hide a screen keyboard for given window.
slouken@6392
   206
 *  
slouken@6392
   207
 *  \param window The window for which screen keyboard should be shown.
slouken@6392
   208
 *  
slouken@6392
   209
 *  \return 0 if request will be processed or -1 on error (e.g. no support).
slouken@6392
   210
 *  
slouken@6392
   211
 *  \note Hiding screen keyboards is asynchronous on some platforms.
slouken@6392
   212
 *  
slouken@6392
   213
 *  \sa SDL_HasScreenKeyboardSupport()
slouken@6392
   214
 *  \sa SDL_ShowScreenKeyboard()
slouken@6392
   215
 */
slouken@6392
   216
extern DECLSPEC int SDLCALL SDL_HideScreenKeyboard(SDL_Window *window);
slouken@6392
   217
slouken@6392
   218
/**
slouken@6392
   219
 *  \brief Requests to toggle a screen keyboard for given window.
slouken@6392
   220
 *  
slouken@6392
   221
 *  \param window The window for which screen keyboard should be toggled.
slouken@6392
   222
 *  
slouken@6392
   223
 *  \return 0 if request will be processed or -1 on error (e.g. no support).
slouken@6392
   224
 *  
slouken@6392
   225
 *  \note Showing and hiding screen keyboards is asynchronous on some platforms.
slouken@6392
   226
 *  
slouken@6392
   227
 *  \sa SDL_HasScreenKeyboardSupport()
slouken@6392
   228
 *  \sa SDL_IsScreenKeyboardShown()
slouken@6392
   229
 */
slouken@6392
   230
extern DECLSPEC int SDLCALL SDL_ToggleScreenKeyboard(SDL_Window * window);
slouken@6392
   231
slouken@6392
   232
/**
slouken@6392
   233
 *  \brief Returns whether the screen keyboard is shown for given window.
slouken@6392
   234
 *  
slouken@6392
   235
 *  \param window The window for which screen keyboard should be queried.
slouken@6392
   236
 *  
slouken@6392
   237
 *  \return SDL_TRUE if screen keyboard is shown else SDL_FALSE.
slouken@6392
   238
 *  
slouken@6392
   239
 *  \note May always return SDL_FALSE on some platforms (not implemented there).
slouken@6392
   240
 *  
slouken@6392
   241
 *  \sa SDL_HasScreenKeyboardSupport()
slouken@6392
   242
 *  \sa SDL_ShowScreenKeyboard()
slouken@6392
   243
 *  \sa SDL_HideScreenKeyboard()
slouken@6392
   244
 */
slouken@6392
   245
extern DECLSPEC SDL_bool SDLCALL SDL_IsScreenKeyboardShown(SDL_Window *window);
slouken@0
   246
slouken@0
   247
/* Ends C function definitions when using C++ */
slouken@0
   248
#ifdef __cplusplus
slouken@1895
   249
/* *INDENT-OFF* */
slouken@0
   250
}
slouken@1895
   251
/* *INDENT-ON* */
slouken@0
   252
#endif
slouken@0
   253
#include "close_code.h"
slouken@0
   254
slouken@0
   255
#endif /* _SDL_keyboard_h */
slouken@1895
   256
slouken@1895
   257
/* vi: set ts=4 sw=4 expandtab: */