include/SDL_keyboard.h
branchSDL-1.2
changeset 4217 4c4113c2162c
parent 4159 a1b03ba2fcd0
child 6137 4720145f848b
equal deleted inserted replaced
4216:5b99971a27b4 4217:4c4113c2162c
    18 
    18 
    19     Sam Lantinga
    19     Sam Lantinga
    20     slouken@libsdl.org
    20     slouken@libsdl.org
    21 */
    21 */
    22 
    22 
    23 /* Include file for SDL keyboard event handling */
    23 /** @file SDL_keyboard.h
       
    24  *  Include file for SDL keyboard event handling
       
    25  */
    24 
    26 
    25 #ifndef _SDL_keyboard_h
    27 #ifndef _SDL_keyboard_h
    26 #define _SDL_keyboard_h
    28 #define _SDL_keyboard_h
    27 
    29 
    28 #include "SDL_stdinc.h"
    30 #include "SDL_stdinc.h"
    33 /* Set up for C function definitions, even when using C++ */
    35 /* Set up for C function definitions, even when using C++ */
    34 #ifdef __cplusplus
    36 #ifdef __cplusplus
    35 extern "C" {
    37 extern "C" {
    36 #endif
    38 #endif
    37 
    39 
    38 /* Keysym structure
    40 /** Keysym structure
    39    - The scancode is hardware dependent, and should not be used by general
    41  *
    40      applications.  If no hardware scancode is available, it will be 0.
    42  *  - The scancode is hardware dependent, and should not be used by general
    41 
    43  *    applications.  If no hardware scancode is available, it will be 0.
    42    - The 'unicode' translated character is only available when character
    44  *
    43      translation is enabled by the SDL_EnableUNICODE() API.  If non-zero,
    45  *  - The 'unicode' translated character is only available when character
    44      this is a UNICODE character corresponding to the keypress.  If the
    46  *    translation is enabled by the SDL_EnableUNICODE() API.  If non-zero,
    45      high 9 bits of the character are 0, then this maps to the equivalent
    47  *    this is a UNICODE character corresponding to the keypress.  If the
    46      ASCII character:
    48  *    high 9 bits of the character are 0, then this maps to the equivalent
    47 	char ch;
    49  *    ASCII character:
    48 	if ( (keysym.unicode & 0xFF80) == 0 ) {
    50  *      @code
    49 		ch = keysym.unicode & 0x7F;
    51  *	char ch;
    50 	} else {
    52  *	if ( (keysym.unicode & 0xFF80) == 0 ) {
    51 		An international character..
    53  *		ch = keysym.unicode & 0x7F;
    52 	}
    54  *	} else {
       
    55  *		An international character..
       
    56  *	}
       
    57  *      @endcode
    53  */
    58  */
    54 typedef struct SDL_keysym {
    59 typedef struct SDL_keysym {
    55 	Uint8 scancode;			/* hardware specific scancode */
    60 	Uint8 scancode;			/**< hardware specific scancode */
    56 	SDLKey sym;			/* SDL virtual keysym */
    61 	SDLKey sym;			/**< SDL virtual keysym */
    57 	SDLMod mod;			/* current key modifiers */
    62 	SDLMod mod;			/**< current key modifiers */
    58 	Uint16 unicode;			/* translated character */
    63 	Uint16 unicode;			/**< translated character */
    59 } SDL_keysym;
    64 } SDL_keysym;
    60 
    65 
    61 /* This is the mask which refers to all hotkey bindings */
    66 /** This is the mask which refers to all hotkey bindings */
    62 #define SDL_ALL_HOTKEYS		0xFFFFFFFF
    67 #define SDL_ALL_HOTKEYS		0xFFFFFFFF
    63 
    68 
    64 /* Function prototypes */
    69 /* Function prototypes */
    65 /*
    70 /**
    66  * Enable/Disable UNICODE translation of keyboard input.
    71  * Enable/Disable UNICODE translation of keyboard input.
       
    72  *
    67  * This translation has some overhead, so translation defaults off.
    73  * This translation has some overhead, so translation defaults off.
       
    74  *
       
    75  * @param[in] enable
    68  * If 'enable' is 1, translation is enabled.
    76  * If 'enable' is 1, translation is enabled.
    69  * If 'enable' is 0, translation is disabled.
    77  * If 'enable' is 0, translation is disabled.
    70  * If 'enable' is -1, the translation state is not changed.
    78  * If 'enable' is -1, the translation state is not changed.
    71  * It returns the previous state of keyboard translation.
    79  *
       
    80  * @return It returns the previous state of keyboard translation.
    72  */
    81  */
    73 extern DECLSPEC int SDLCALL SDL_EnableUNICODE(int enable);
    82 extern DECLSPEC int SDLCALL SDL_EnableUNICODE(int enable);
    74 
    83 
    75 /*
       
    76  * Enable/Disable keyboard repeat.  Keyboard repeat defaults to off.
       
    77  * 'delay' is the initial delay in ms between the time when a key is
       
    78  * pressed, and keyboard repeat begins.
       
    79  * 'interval' is the time in ms between keyboard repeat events.
       
    80  */
       
    81 #define SDL_DEFAULT_REPEAT_DELAY	500
    84 #define SDL_DEFAULT_REPEAT_DELAY	500
    82 #define SDL_DEFAULT_REPEAT_INTERVAL	30
    85 #define SDL_DEFAULT_REPEAT_INTERVAL	30
    83 /*
    86 /**
    84  * If 'delay' is set to 0, keyboard repeat is disabled.
    87  * Enable/Disable keyboard repeat.  Keyboard repeat defaults to off.
       
    88  *
       
    89  *  @param[in] delay
       
    90  *  'delay' is the initial delay in ms between the time when a key is
       
    91  *  pressed, and keyboard repeat begins.
       
    92  *
       
    93  *  @param[in] interval
       
    94  *  'interval' is the time in ms between keyboard repeat events.
       
    95  *
       
    96  *  If 'delay' is set to 0, keyboard repeat is disabled.
    85  */
    97  */
    86 extern DECLSPEC int SDLCALL SDL_EnableKeyRepeat(int delay, int interval);
    98 extern DECLSPEC int SDLCALL SDL_EnableKeyRepeat(int delay, int interval);
    87 extern DECLSPEC void SDLCALL SDL_GetKeyRepeat(int *delay, int *interval);
    99 extern DECLSPEC void SDLCALL SDL_GetKeyRepeat(int *delay, int *interval);
    88 
   100 
    89 /*
   101 /**
    90  * Get a snapshot of the current state of the keyboard.
   102  * Get a snapshot of the current state of the keyboard.
    91  * Returns an array of keystates, indexed by the SDLK_* syms.
   103  * Returns an array of keystates, indexed by the SDLK_* syms.
    92  * Used:
   104  * Usage:
       
   105  *	@code
    93  * 	Uint8 *keystate = SDL_GetKeyState(NULL);
   106  * 	Uint8 *keystate = SDL_GetKeyState(NULL);
    94  *	if ( keystate[SDLK_RETURN] ) ... <RETURN> is pressed.
   107  *	if ( keystate[SDLK_RETURN] ) //... \<RETURN> is pressed.
       
   108  *	@endcode
    95  */
   109  */
    96 extern DECLSPEC Uint8 * SDLCALL SDL_GetKeyState(int *numkeys);
   110 extern DECLSPEC Uint8 * SDLCALL SDL_GetKeyState(int *numkeys);
    97 
   111 
    98 /*
   112 /**
    99  * Get the current key modifier state
   113  * Get the current key modifier state
   100  */
   114  */
   101 extern DECLSPEC SDLMod SDLCALL SDL_GetModState(void);
   115 extern DECLSPEC SDLMod SDLCALL SDL_GetModState(void);
   102 
   116 
   103 /*
   117 /**
   104  * Set the current key modifier state
   118  * Set the current key modifier state.
   105  * This does not change the keyboard state, only the key modifier flags.
   119  * This does not change the keyboard state, only the key modifier flags.
   106  */
   120  */
   107 extern DECLSPEC void SDLCALL SDL_SetModState(SDLMod modstate);
   121 extern DECLSPEC void SDLCALL SDL_SetModState(SDLMod modstate);
   108 
   122 
   109 /*
   123 /**
   110  * Get the name of an SDL virtual keysym
   124  * Get the name of an SDL virtual keysym
   111  */
   125  */
   112 extern DECLSPEC char * SDLCALL SDL_GetKeyName(SDLKey key);
   126 extern DECLSPEC char * SDLCALL SDL_GetKeyName(SDLKey key);
   113 
   127 
   114 
   128