include/SDL_keyboard.h
changeset 1895 c121d94672cb
parent 1507 1ff64ad478b2
child 2129 047245361002
     1.1 --- a/include/SDL_keyboard.h	Thu Jul 06 18:01:37 2006 +0000
     1.2 +++ b/include/SDL_keyboard.h	Mon Jul 10 21:04:37 2006 +0000
     1.3 @@ -20,7 +20,11 @@
     1.4      slouken@libsdl.org
     1.5  */
     1.6  
     1.7 -/* Include file for SDL keyboard event handling */
     1.8 +/**
     1.9 + * \file SDL_keyboard.h
    1.10 + *
    1.11 + * Include file for SDL keyboard event handling
    1.12 + */
    1.13  
    1.14  #ifndef _SDL_keyboard_h
    1.15  #define _SDL_keyboard_h
    1.16 @@ -32,90 +36,133 @@
    1.17  #include "begin_code.h"
    1.18  /* Set up for C function definitions, even when using C++ */
    1.19  #ifdef __cplusplus
    1.20 +/* *INDENT-OFF* */
    1.21  extern "C" {
    1.22 +/* *INDENT-ON* */
    1.23  #endif
    1.24  
    1.25 -/* Keysym structure
    1.26 -   - The scancode is hardware dependent, and should not be used by general
    1.27 -     applications.  If no hardware scancode is available, it will be 0.
    1.28 -
    1.29 -   - The 'unicode' translated character is only available when character
    1.30 -     translation is enabled by the SDL_EnableUNICODE() API.  If non-zero,
    1.31 -     this is a UNICODE character corresponding to the keypress.  If the
    1.32 -     high 9 bits of the character are 0, then this maps to the equivalent
    1.33 -     ASCII character:
    1.34 -	char ch;
    1.35 -	if ( (keysym.unicode & 0xFF80) == 0 ) {
    1.36 -		ch = keysym.unicode & 0x7F;
    1.37 -	} else {
    1.38 -		An international character..
    1.39 -	}
    1.40 +/**
    1.41 + * \struct SDL_keysym
    1.42 + *
    1.43 + * \brief The SDL keysym structure, used in key events.
    1.44   */
    1.45 -typedef struct SDL_keysym {
    1.46 -	Uint8 scancode;			/* hardware specific scancode */
    1.47 -	SDLKey sym;			/* SDL virtual keysym */
    1.48 -	SDLMod mod;			/* current key modifiers */
    1.49 -	Uint16 unicode;			/* translated character */
    1.50 +typedef struct SDL_keysym
    1.51 +{
    1.52 +    Uint8 scancode;             /**< keyboard specific scancode */
    1.53 +    Uint8 padding[3];           /**< alignment padding */
    1.54 +    Uint16 sym;                 /**< SDL virtual keysym */
    1.55 +    Uint16 mod;                 /**< current key modifiers */
    1.56 +    Uint32 unicode;             /**< OBSOLETE, use SDL_TextInputEvent instead */
    1.57  } SDL_keysym;
    1.58  
    1.59 -/* This is the mask which refers to all hotkey bindings */
    1.60 -#define SDL_ALL_HOTKEYS		0xFFFFFFFF
    1.61 +/* Function prototypes */
    1.62  
    1.63 -/* Function prototypes */
    1.64 -/*
    1.65 - * Enable/Disable UNICODE translation of keyboard input.
    1.66 - * This translation has some overhead, so translation defaults off.
    1.67 - * If 'enable' is 1, translation is enabled.
    1.68 - * If 'enable' is 0, translation is disabled.
    1.69 - * If 'enable' is -1, the translation state is not changed.
    1.70 - * It returns the previous state of keyboard translation.
    1.71 +/**
    1.72 + * \fn int SDL_GetNumKeyboards(void)
    1.73 + *
    1.74 + * \brief Get the number of keyboard input devices available.
    1.75 + *
    1.76 + * \sa SDL_SelectKeyboard()
    1.77 + */
    1.78 +extern DECLSPEC int SDLCALL SDL_GetNumKeyboards(void);
    1.79 +
    1.80 +/**
    1.81 + * \fn int SDL_SelectKeyboard(int index)
    1.82 + *
    1.83 + * \brief Set the index of the currently selected keyboard.
    1.84 + *
    1.85 + * \return The index of the previously selected keyboard.
    1.86 + *
    1.87 + * \note You can query the currently selected keyboard by passing an index of -1.
    1.88 + *
    1.89 + * \sa SDL_GetNumKeyboards()
    1.90 + */
    1.91 +extern DECLSPEC int SDLCALL SDL_SelectKeyboard(int index);
    1.92 +
    1.93 +/**
    1.94 + * \fn int SDL_EnableUNICODE(int enable)
    1.95 + *
    1.96 + * \brief Enable/Disable UNICODE translation of keyboard input.
    1.97 + *
    1.98 + * \param enable 1 to enable translation, 0 to disable translation, -1 to query translation
    1.99 + *
   1.100 + * \return The previous state of keyboard translation
   1.101 + *
   1.102 + * \note This translation has some overhead, so translation defaults off.
   1.103   */
   1.104  extern DECLSPEC int SDLCALL SDL_EnableUNICODE(int enable);
   1.105  
   1.106 -/*
   1.107 - * Enable/Disable keyboard repeat.  Keyboard repeat defaults to off.
   1.108 - * 'delay' is the initial delay in ms between the time when a key is
   1.109 - * pressed, and keyboard repeat begins.
   1.110 - * 'interval' is the time in ms between keyboard repeat events.
   1.111 +/**
   1.112 + * \fn int SDL_EnableKeyRepeat(int delay, int interval)
   1.113 + * 
   1.114 + * \brief Enable keyboard repeat for the selected keyboard.
   1.115 + *
   1.116 + * \param delay The initial delay in milliseconds between the time when a
   1.117 + *              key is pressed and keyboard repeat begins.  Setting a delay
   1.118 + *              of 0 will disable keyboard repeat.
   1.119 + * \param interval The time in milliseconds between keyboard repeat events.
   1.120 + *
   1.121 + * \return 0 on success, or -1 if there was an error.
   1.122 + *
   1.123 + * \note Keyboard repeat defaults to off.
   1.124   */
   1.125  #define SDL_DEFAULT_REPEAT_DELAY	500
   1.126  #define SDL_DEFAULT_REPEAT_INTERVAL	30
   1.127 -/*
   1.128 - * If 'delay' is set to 0, keyboard repeat is disabled.
   1.129 + /**/
   1.130 +    extern DECLSPEC int SDLCALL SDL_EnableKeyRepeat(int delay, int interval);
   1.131 +
   1.132 +/**
   1.133 + * \fn void SDL_GetKeyRepeat(int *delay, int *interval)
   1.134 + *
   1.135 + * \brief Get the current keyboard repeat setting for the selected keyboard.
   1.136   */
   1.137 -extern DECLSPEC int SDLCALL SDL_EnableKeyRepeat(int delay, int interval);
   1.138  extern DECLSPEC void SDLCALL SDL_GetKeyRepeat(int *delay, int *interval);
   1.139  
   1.140 -/*
   1.141 - * Get a snapshot of the current state of the keyboard.
   1.142 - * Returns an array of keystates, indexed by the SDLK_* syms.
   1.143 - * Used:
   1.144 +/**
   1.145 + * \fn Uint8 *SDL_GetKeyState(int *numkeys)
   1.146 + *
   1.147 + * \brief Get a snapshot of the current state of the selected keyboard.
   1.148 + *
   1.149 + * \return An array of keystates, indexed by the SDLK_* syms.
   1.150 + *
   1.151 + * Example:
   1.152   * 	Uint8 *keystate = SDL_GetKeyState(NULL);
   1.153   *	if ( keystate[SDLK_RETURN] ) ... <RETURN> is pressed.
   1.154   */
   1.155 -extern DECLSPEC Uint8 * SDLCALL SDL_GetKeyState(int *numkeys);
   1.156 +extern DECLSPEC Uint8 *SDLCALL SDL_GetKeyState(int *numkeys);
   1.157  
   1.158 -/*
   1.159 - * Get the current key modifier state
   1.160 +/**
   1.161 + * \fn SDLMod SDL_GetModState(void)
   1.162 + *
   1.163 + * \brief Get the current key modifier state for the selected keyboard.
   1.164   */
   1.165  extern DECLSPEC SDLMod SDLCALL SDL_GetModState(void);
   1.166  
   1.167 -/*
   1.168 - * Set the current key modifier state
   1.169 - * This does not change the keyboard state, only the key modifier flags.
   1.170 +/**
   1.171 + * \fn void SDL_SetModState(SDLMod modstate)
   1.172 + *
   1.173 + * \brief Set the current key modifier state for the selected keyboard.
   1.174 + *
   1.175 + * \note This does not change the keyboard state, only the key modifier flags.
   1.176   */
   1.177  extern DECLSPEC void SDLCALL SDL_SetModState(SDLMod modstate);
   1.178  
   1.179 -/*
   1.180 - * Get the name of an SDL virtual keysym
   1.181 +/**
   1.182 + * \fn const char *SDL_GetKeyName(SDLKey key)
   1.183 + * 
   1.184 + * \brief Get the name of an SDL virtual keysym
   1.185   */
   1.186 -extern DECLSPEC char * SDLCALL SDL_GetKeyName(SDLKey key);
   1.187 +extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDLKey key);
   1.188  
   1.189  
   1.190  /* Ends C function definitions when using C++ */
   1.191  #ifdef __cplusplus
   1.192 +/* *INDENT-OFF* */
   1.193  }
   1.194 +/* *INDENT-ON* */
   1.195  #endif
   1.196  #include "close_code.h"
   1.197  
   1.198  #endif /* _SDL_keyboard_h */
   1.199 +
   1.200 +/* vi: set ts=4 sw=4 expandtab: */