include/SDL_keyboard.h
author Ryan C. Gordon <icculus@icculus.org>
Fri, 13 Mar 2015 00:48:30 -0400
changeset 9381 812b2dabf8a4
parent 8149 681eb46b8ac4
child 9619 b94b6d0bff0f
permissions -rw-r--r--
Removed an unnecessary #ifdef.
slouken@0
     1
/*
slouken@5535
     2
  Simple DirectMedia Layer
slouken@8149
     3
  Copyright (C) 1997-2014 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@7312
    44
 *
slouken@7312
    45
 *  \note  If you are looking for translated character input, see the ::SDL_TEXTINPUT event.
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@7312
    52
    Uint32 unused;
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@7191
    64
 *
slouken@3407
    65
 *  \param numkeys if non-NULL, receives the length of the returned array.
slouken@7191
    66
 *
slouken@5218
    67
 *  \return An array of key states. Indexes into this array are obtained by using ::SDL_Scancode values.
slouken@7191
    68
 *
slouken@3407
    69
 *  \b Example:
slouken@3407
    70
 *  \code
slouken@7258
    71
 *  const 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@7258
    77
extern DECLSPEC const 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@7191
    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@7191
    94
 *
slouken@5220
    95
 *  See ::SDL_Keycode for details.
slouken@7191
    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@7191
   104
 *
slouken@5218
   105
 *  See ::SDL_Scancode for details.
slouken@7191
   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@7191
   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@7191
   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@7191
   133
 *
slouken@3407
   134
 *  \return A pointer to a UTF-8 string that stays valid at least until the next
slouken@7191
   135
 *          call to this function. If you need it around any longer, you must
slouken@7191
   136
 *          copy it.  If the key doesn't have a name, this function returns an
slouken@3407
   137
 *          empty string ("").
slouken@7191
   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@7191
   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@6654
   154
 *         This function will show the on-screen keyboard if supported.
slouken@7191
   155
 *
slouken@3407
   156
 *  \sa SDL_StopTextInput()
slouken@3407
   157
 *  \sa SDL_SetTextInputRect()
slouken@6654
   158
 *  \sa SDL_HasScreenKeyboardSupport()
slouken@3280
   159
 */
dewyatt@4753
   160
extern DECLSPEC void SDLCALL SDL_StartTextInput(void);
slouken@3280
   161
slouken@3280
   162
/**
slouken@6654
   163
 *  \brief Return whether or not Unicode text input events are enabled.
slouken@6654
   164
 *
slouken@6654
   165
 *  \sa SDL_StartTextInput()
slouken@6654
   166
 *  \sa SDL_StopTextInput()
slouken@6654
   167
 */
slouken@6654
   168
extern DECLSPEC SDL_bool SDLCALL SDL_IsTextInputActive(void);
slouken@6654
   169
slouken@6654
   170
/**
slouken@3407
   171
 *  \brief Stop receiving any text input events.
slouken@6654
   172
 *         This function will hide the on-screen keyboard if supported.
slouken@7191
   173
 *
slouken@3407
   174
 *  \sa SDL_StartTextInput()
slouken@6654
   175
 *  \sa SDL_HasScreenKeyboardSupport()
slouken@3280
   176
 */
dewyatt@4753
   177
extern DECLSPEC void SDLCALL SDL_StopTextInput(void);
slouken@3280
   178
slouken@3280
   179
/**
slouken@3407
   180
 *  \brief Set the rectangle used to type Unicode text inputs.
slouken@6654
   181
 *         This is used as a hint for IME and on-screen keyboard placement.
slouken@7191
   182
 *
slouken@3407
   183
 *  \sa SDL_StartTextInput()
slouken@3280
   184
 */
slouken@3280
   185
extern DECLSPEC void SDLCALL SDL_SetTextInputRect(SDL_Rect *rect);
slouken@3280
   186
slouken@6392
   187
/**
slouken@6392
   188
 *  \brief Returns whether the platform has some screen keyboard support.
slouken@7191
   189
 *
slouken@6392
   190
 *  \return SDL_TRUE if some keyboard support is available else SDL_FALSE.
slouken@7191
   191
 *
slouken@6392
   192
 *  \note Not all screen keyboard functions are supported on all platforms.
slouken@7191
   193
 *
slouken@6392
   194
 *  \sa SDL_IsScreenKeyboardShown()
slouken@6392
   195
 */
tim@6820
   196
extern DECLSPEC SDL_bool SDLCALL SDL_HasScreenKeyboardSupport(void);
slouken@6392
   197
slouken@6392
   198
/**
slouken@6392
   199
 *  \brief Returns whether the screen keyboard is shown for given window.
slouken@7191
   200
 *
slouken@6392
   201
 *  \param window The window for which screen keyboard should be queried.
slouken@7191
   202
 *
slouken@6392
   203
 *  \return SDL_TRUE if screen keyboard is shown else SDL_FALSE.
slouken@7191
   204
 *
slouken@6392
   205
 *  \sa SDL_HasScreenKeyboardSupport()
slouken@6392
   206
 */
slouken@6392
   207
extern DECLSPEC SDL_bool SDLCALL SDL_IsScreenKeyboardShown(SDL_Window *window);
slouken@0
   208
slouken@0
   209
/* Ends C function definitions when using C++ */
slouken@0
   210
#ifdef __cplusplus
slouken@0
   211
}
slouken@0
   212
#endif
slouken@0
   213
#include "close_code.h"
slouken@0
   214
slouken@0
   215
#endif /* _SDL_keyboard_h */
slouken@1895
   216
slouken@1895
   217
/* vi: set ts=4 sw=4 expandtab: */