include/SDL_keyboard.h
branchSDL-1.3
changeset 1673 624e1412fbba
parent 1668 4da1ee79c9af
child 1674 7688a73b25b1
     1.1 --- a/include/SDL_keyboard.h	Fri Jun 09 07:06:12 2006 +0000
     1.2 +++ b/include/SDL_keyboard.h	Sat Jun 10 09:11:59 2006 +0000
     1.3 @@ -41,82 +41,116 @@
     1.4  /* *INDENT-ON* */
     1.5  #endif
     1.6  
     1.7 -/* Keysym structure
     1.8 -   - The scancode is hardware dependent, and should not be used by general
     1.9 -     applications.  If no hardware scancode is available, it will be 0.
    1.10 -
    1.11 -   - The 'unicode' translated character is only available when character
    1.12 -     translation is enabled by the SDL_EnableUNICODE() API.  If non-zero,
    1.13 -     this is a UNICODE character corresponding to the keypress.  If the
    1.14 -     high 9 bits of the character are 0, then this maps to the equivalent
    1.15 -     ASCII character:
    1.16 -	char ch;
    1.17 -	if ( (keysym.unicode & 0xFF80) == 0 ) {
    1.18 -		ch = keysym.unicode & 0x7F;
    1.19 -	} else {
    1.20 -		An international character..
    1.21 -	}
    1.22 +/**
    1.23 + * \struct SDL_keysym
    1.24 + *
    1.25 + * \brief The SDL keysym structure, used in key events.
    1.26   */
    1.27  typedef struct SDL_keysym
    1.28  {
    1.29 -    Uint8 scancode;             /* hardware specific scancode */
    1.30 -    SDLKey sym;                 /* SDL virtual keysym */
    1.31 -    SDLMod mod;                 /* current key modifiers */
    1.32 -    Uint16 unicode;             /* translated character */
    1.33 +    Uint8 scancode;             /**< keyboard specific scancode */
    1.34 +    SDLKey sym;                 /**< SDL virtual keysym */
    1.35 +    SDLMod mod;                 /**< current key modifiers */
    1.36  } SDL_keysym;
    1.37  
    1.38 -/* This is the mask which refers to all hotkey bindings */
    1.39 -#define SDL_ALL_HOTKEYS		0xFFFFFFFF
    1.40 +/* Function prototypes */
    1.41 +
    1.42 +/**
    1.43 + * \fn int SDL_GetNumKeyboards(void)
    1.44 + *
    1.45 + * \brief Get the number of keyboard input devices available.
    1.46 + *
    1.47 + * \sa SDL_SelectKeyboard()
    1.48 + */
    1.49 +extern DECLSPEC int SDLCALL SDL_GetNumKeyboards(void);
    1.50  
    1.51 -/* Function prototypes */
    1.52 -/*
    1.53 - * Enable/Disable UNICODE translation of keyboard input.
    1.54 - * This translation has some overhead, so translation defaults off.
    1.55 - * If 'enable' is 1, translation is enabled.
    1.56 - * If 'enable' is 0, translation is disabled.
    1.57 - * If 'enable' is -1, the translation state is not changed.
    1.58 - * It returns the previous state of keyboard translation.
    1.59 +/**
    1.60 + * \fn int SDL_SelectKeyboard(int index)
    1.61 + *
    1.62 + * \brief Set the index of the currently selected keyboard.
    1.63 + *
    1.64 + * \return The index of the previously selected keyboard.
    1.65 + *
    1.66 + * \note You can query the currently selected keyboard by passing an index of -1.
    1.67 + *
    1.68 + * \sa SDL_GetNumKeyboards()
    1.69 + */
    1.70 +extern DECLSPEC int SDLCALL SDL_SelectKeyboard(int index);
    1.71 +
    1.72 +/**
    1.73 + * \fn int SDL_EnableUNICODE(int enable)
    1.74 + *
    1.75 + * \brief Enable/Disable UNICODE translation of keyboard input.
    1.76 + *
    1.77 + * \param enable 1 to enable translation, 0 to disable translation, -1 to query translation
    1.78 + *
    1.79 + * \return The previous state of keyboard translation
    1.80 + *
    1.81 + * \note This translation has some overhead, so translation defaults off.
    1.82   */
    1.83  extern DECLSPEC int SDLCALL SDL_EnableUNICODE(int enable);
    1.84  
    1.85 -/*
    1.86 - * Enable/Disable keyboard repeat.  Keyboard repeat defaults to off.
    1.87 - * 'delay' is the initial delay in ms between the time when a key is
    1.88 - * pressed, and keyboard repeat begins.
    1.89 - * 'interval' is the time in ms between keyboard repeat events.
    1.90 +/**
    1.91 + * \fn int SDL_EnableKeyRepeat(int delay, int interval)
    1.92 + * 
    1.93 + * \brief Enable keyboard repeat for the selected keyboard.
    1.94 + *
    1.95 + * \param delay The initial delay in milliseconds between the time when a
    1.96 + *              key is pressed and keyboard repeat begins.  Setting a delay
    1.97 + *              of 0 will disable keyboard repeat.
    1.98 + * \param interval The time in milliseconds between keyboard repeat events.
    1.99 + *
   1.100 + * \return 0 on success, or -1 if there was an error.
   1.101 + *
   1.102 + * \note Keyboard repeat defaults to off.
   1.103   */
   1.104  #define SDL_DEFAULT_REPEAT_DELAY	500
   1.105  #define SDL_DEFAULT_REPEAT_INTERVAL	30
   1.106 -/*
   1.107 - * If 'delay' is set to 0, keyboard repeat is disabled.
   1.108 + /**/
   1.109 +    extern DECLSPEC int SDLCALL SDL_EnableKeyRepeat(int delay, int interval);
   1.110 +
   1.111 +/**
   1.112 + * \fn void SDL_GetKeyRepeat(int *delay, int *interval)
   1.113 + *
   1.114 + * \brief Get the current keyboard repeat setting for the selected keyboard.
   1.115   */
   1.116 -extern DECLSPEC int SDLCALL SDL_EnableKeyRepeat(int delay, int interval);
   1.117  extern DECLSPEC void SDLCALL SDL_GetKeyRepeat(int *delay, int *interval);
   1.118  
   1.119 -/*
   1.120 - * Get a snapshot of the current state of the keyboard.
   1.121 - * Returns an array of keystates, indexed by the SDLK_* syms.
   1.122 - * Used:
   1.123 +/**
   1.124 + * \fn Uint8 *SDL_GetKeyState(int *numkeys)
   1.125 + *
   1.126 + * \brief Get a snapshot of the current state of the selected keyboard.
   1.127 + *
   1.128 + * \return An array of keystates, indexed by the SDLK_* syms.
   1.129 + *
   1.130 + * Example:
   1.131   * 	Uint8 *keystate = SDL_GetKeyState(NULL);
   1.132   *	if ( keystate[SDLK_RETURN] ) ... <RETURN> is pressed.
   1.133   */
   1.134  extern DECLSPEC Uint8 *SDLCALL SDL_GetKeyState(int *numkeys);
   1.135  
   1.136 -/*
   1.137 - * Get the current key modifier state
   1.138 +/**
   1.139 + * \fn SDLMod SDL_GetModState(void)
   1.140 + *
   1.141 + * \brief Get the current key modifier state for the selected keyboard.
   1.142   */
   1.143  extern DECLSPEC SDLMod SDLCALL SDL_GetModState(void);
   1.144  
   1.145 -/*
   1.146 - * Set the current key modifier state
   1.147 - * This does not change the keyboard state, only the key modifier flags.
   1.148 +/**
   1.149 + * \fn void SDL_SetModState(SDLMod modstate)
   1.150 + *
   1.151 + * \brief Set the current key modifier state for the selected keyboard.
   1.152 + *
   1.153 + * \note This does not change the keyboard state, only the key modifier flags.
   1.154   */
   1.155  extern DECLSPEC void SDLCALL SDL_SetModState(SDLMod modstate);
   1.156  
   1.157 -/*
   1.158 - * Get the name of an SDL virtual keysym
   1.159 +/**
   1.160 + * \fn const char *SDL_GetKeyName(SDLKey key)
   1.161 + * 
   1.162 + * \brief Get the name of an SDL virtual keysym
   1.163   */
   1.164 -extern DECLSPEC char *SDLCALL SDL_GetKeyName(SDLKey key);
   1.165 +extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDLKey key);
   1.166  
   1.167  
   1.168  /* Ends C function definitions when using C++ */