include/SDL_keyboard.h
author Sam Lantinga <slouken@libsdl.org>
Fri, 08 Apr 2011 13:03:26 -0700
changeset 5535 96594ac5fd1a
parent 5326 4a4095fe12e3
child 6029 4a8bbaa52b9b
permissions -rw-r--r--
SDL 1.3 is now under the zlib license.
slouken@0
     1
/*
slouken@5535
     2
  Simple DirectMedia Layer
slouken@5535
     3
  Copyright (C) 1997-2011 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@3407
   114
 *  \return A pointer to a UTF-8 string that stays valid at least until the next
slouken@3407
   115
 *          call to this function. If you need it around any longer, you must 
slouken@3407
   116
 *          copy it.  If the scancode doesn't have a name, this function returns
slouken@3407
   117
 *          an empty string ("").
slouken@2303
   118
 *
slouken@5218
   119
 *  \sa SDL_Scancode
slouken@2303
   120
 */
slouken@5218
   121
extern DECLSPEC const char *SDLCALL SDL_GetScancodeName(SDL_Scancode
slouken@2303
   122
                                                        scancode);
slouken@2303
   123
slouken@2303
   124
/**
slouken@3407
   125
 *  \brief Get a human-readable name for a key.
slouken@3407
   126
 *  
slouken@3407
   127
 *  \return A pointer to a UTF-8 string that stays valid at least until the next
slouken@3407
   128
 *          call to this function. If you need it around any longer, you must 
slouken@3407
   129
 *          copy it.  If the key doesn't have a name, this function returns an 
slouken@3407
   130
 *          empty string ("").
slouken@3407
   131
 *  
slouken@5219
   132
 *  \sa SDL_Key
slouken@2268
   133
 */
slouken@5220
   134
extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDL_Keycode key);
slouken@0
   135
slouken@3280
   136
/**
slouken@3407
   137
 *  \brief Start accepting Unicode text input events.
slouken@3407
   138
 *  
slouken@3407
   139
 *  \sa SDL_StopTextInput()
slouken@3407
   140
 *  \sa SDL_SetTextInputRect()
slouken@3280
   141
 */
dewyatt@4753
   142
extern DECLSPEC void SDLCALL SDL_StartTextInput(void);
slouken@3280
   143
slouken@3280
   144
/**
slouken@3407
   145
 *  \brief Stop receiving any text input events.
slouken@3407
   146
 *  
slouken@3407
   147
 *  \sa SDL_StartTextInput()
slouken@3280
   148
 */
dewyatt@4753
   149
extern DECLSPEC void SDLCALL SDL_StopTextInput(void);
slouken@3280
   150
slouken@3280
   151
/**
slouken@3407
   152
 *  \brief Set the rectangle used to type Unicode text inputs.
slouken@3407
   153
 *  
slouken@3407
   154
 *  \sa SDL_StartTextInput()
slouken@3280
   155
 */
slouken@3280
   156
extern DECLSPEC void SDLCALL SDL_SetTextInputRect(SDL_Rect *rect);
slouken@3280
   157
slouken@0
   158
slouken@0
   159
/* Ends C function definitions when using C++ */
slouken@0
   160
#ifdef __cplusplus
slouken@1895
   161
/* *INDENT-OFF* */
slouken@0
   162
}
slouken@1895
   163
/* *INDENT-ON* */
slouken@0
   164
#endif
slouken@0
   165
#include "close_code.h"
slouken@0
   166
slouken@0
   167
#endif /* _SDL_keyboard_h */
slouken@1895
   168
slouken@1895
   169
/* vi: set ts=4 sw=4 expandtab: */