include/SDL_keyboard.h
changeset 3407 d3baf5ac4e37
parent 3280 00cace2d9080
child 3697 f7b03b6838cb
     1.1 --- a/include/SDL_keyboard.h	Sun Oct 18 23:21:15 2009 +0000
     1.2 +++ b/include/SDL_keyboard.h	Mon Oct 19 13:31:58 2009 +0000
     1.3 @@ -21,9 +21,9 @@
     1.4  */
     1.5  
     1.6  /**
     1.7 - * \file SDL_keyboard.h
     1.8 - *
     1.9 - * Include file for SDL keyboard event handling
    1.10 + *  \file SDL_keyboard.h
    1.11 + *  
    1.12 + *  Include file for SDL keyboard event handling
    1.13   */
    1.14  
    1.15  #ifndef _SDL_keyboard_h
    1.16 @@ -42,143 +42,129 @@
    1.17  #endif
    1.18  
    1.19  /**
    1.20 - * \struct SDL_keysym
    1.21 - *
    1.22 - * \brief The SDL keysym structure, used in key events.
    1.23 + *  \brief The SDL keysym structure, used in key events.
    1.24   */
    1.25  typedef struct SDL_keysym
    1.26  {
    1.27      SDL_scancode scancode;      /**< SDL physical key code - see ::SDL_scancode for details */
    1.28      SDLKey sym;                 /**< SDL virtual key code - see ::SDLKey for details */
    1.29      Uint16 mod;                 /**< current key modifiers */
    1.30 -    Uint32 unicode;             /**< OBSOLETE, use SDL_TextInputEvent instead */
    1.31 +    Uint32 unicode;             /**< \deprecated use SDL_TextInputEvent instead */
    1.32  } SDL_keysym;
    1.33  
    1.34  /* Function prototypes */
    1.35  
    1.36  /**
    1.37 - * \fn int SDL_GetNumKeyboards(void)
    1.38 - *
    1.39 - * \brief Get the number of keyboard input devices available.
    1.40 - *
    1.41 - * \sa SDL_SelectKeyboard()
    1.42 + *  \brief Get the number of keyboard input devices available.
    1.43 + *  
    1.44 + *  \sa SDL_SelectKeyboard()
    1.45   */
    1.46  extern DECLSPEC int SDLCALL SDL_GetNumKeyboards(void);
    1.47  
    1.48  /**
    1.49 - * \fn int SDL_SelectKeyboard(int index)
    1.50 - *
    1.51 - * \brief Set the index of the currently selected keyboard.
    1.52 - *
    1.53 - * \return The index of the previously selected keyboard.
    1.54 - *
    1.55 - * \note You can query the currently selected keyboard by passing an index of -1.
    1.56 - *
    1.57 - * \sa SDL_GetNumKeyboards()
    1.58 + *  \brief Set the index of the currently selected keyboard.
    1.59 + *  
    1.60 + *  \return The index of the previously selected keyboard.
    1.61 + *  
    1.62 + *  \note You can query the currently selected keyboard by passing an index of -1.
    1.63 + *  
    1.64 + *  \sa SDL_GetNumKeyboards()
    1.65   */
    1.66  extern DECLSPEC int SDLCALL SDL_SelectKeyboard(int index);
    1.67  
    1.68  /**
    1.69 - * \fn Uint8 *SDL_GetKeyboardState(int *numkeys)
    1.70 - *
    1.71 - * \brief Get a snapshot of the current state of the selected keyboard.
    1.72 - *
    1.73 - * \param numkeys if non-NULL, receives the length of the returned array.
    1.74 - *
    1.75 - * \return An array of key states. Indexes into this array are obtained by using ::SDL_scancode values.
    1.76 - *
    1.77 - * Example:
    1.78 - * 	Uint8 *state = SDL_GetKeyboardState(NULL);
    1.79 - *	if ( state[SDL_SCANCODE_RETURN)] ) ... <RETURN> is pressed.
    1.80 + *  \brief Get a snapshot of the current state of the selected keyboard.
    1.81 + *  
    1.82 + *  \param numkeys if non-NULL, receives the length of the returned array.
    1.83 + *  
    1.84 + *  \return An array of key states. Indexes into this array are obtained by using ::SDL_scancode values.
    1.85 + *  
    1.86 + *  \b Example:
    1.87 + *  \code
    1.88 + *  Uint8 *state = SDL_GetKeyboardState(NULL);
    1.89 + *  if ( state[SDL_SCANCODE_RETURN] )   {
    1.90 + *      printf("<RETURN> is pressed.\n");
    1.91 + *  }
    1.92 + *  \endcode
    1.93   */
    1.94  extern DECLSPEC Uint8 *SDLCALL SDL_GetKeyboardState(int *numkeys);
    1.95  
    1.96  /**
    1.97 - * \fn SDLMod SDL_GetModState(void)
    1.98 - *
    1.99 - * \brief Get the current key modifier state for the selected keyboard.
   1.100 + *  \brief Get the current key modifier state for the selected keyboard.
   1.101   */
   1.102  extern DECLSPEC SDLMod SDLCALL SDL_GetModState(void);
   1.103  
   1.104  /**
   1.105 - * \fn void SDL_SetModState(SDLMod modstate)
   1.106 - *
   1.107 - * \brief Set the current key modifier state for the selected keyboard.
   1.108 - *
   1.109 - * \note This does not change the keyboard state, only the key modifier flags.
   1.110 + *  \brief Set the current key modifier state for the selected keyboard.
   1.111 + *  
   1.112 + *  \note This does not change the keyboard state, only the key modifier flags.
   1.113   */
   1.114  extern DECLSPEC void SDLCALL SDL_SetModState(SDLMod modstate);
   1.115  
   1.116  /**
   1.117 - * \fn SDLKey SDL_GetKeyFromScancode(SDL_scancode scancode)
   1.118 - * 
   1.119 - * \brief Get the key code corresponding to the given scancode according to the current keyboard layout.
   1.120 - *
   1.121 - * See ::SDLKey for details.
   1.122 - *
   1.123 - * \sa SDL_GetKeyName()
   1.124 + *  \brief Get the key code corresponding to the given scancode according to the
   1.125 + *         current keyboard layout.
   1.126 + *  
   1.127 + *  See ::SDLKey for details.
   1.128 + *  
   1.129 + *  \sa SDL_GetKeyName()
   1.130   */
   1.131  extern DECLSPEC SDLKey SDLCALL SDL_GetKeyFromScancode(SDL_scancode scancode);
   1.132  
   1.133  /**
   1.134 - * \fn SDL_scancode SDL_GetScancodeFromKey(SDLKey key)
   1.135 - * 
   1.136 - * \brief Get the scancode corresponding to the given key code according to the current keyboard layout.
   1.137 - *
   1.138 - * See ::SDL_scancode for details.
   1.139 - *
   1.140 - * \sa SDL_GetScancodeName()
   1.141 + *  \brief Get the scancode corresponding to the given key code according to the
   1.142 + *         current keyboard layout.
   1.143 + *  
   1.144 + *  See ::SDL_scancode for details.
   1.145 + *  
   1.146 + *  \sa SDL_GetScancodeName()
   1.147   */
   1.148  extern DECLSPEC SDL_scancode SDLCALL SDL_GetScancodeFromKey(SDLKey key);
   1.149  
   1.150  /**
   1.151 - * \fn const char *SDL_GetScancodeName(SDL_scancode scancode)
   1.152 - * 
   1.153 - * \brief Get a human-readable name for a scancode.
   1.154 + *  \brief Get a human-readable name for a scancode.
   1.155 + *  
   1.156 + *  \return A pointer to a UTF-8 string that stays valid at least until the next
   1.157 + *          call to this function. If you need it around any longer, you must 
   1.158 + *          copy it.  If the scancode doesn't have a name, this function returns
   1.159 + *          an empty string ("").
   1.160   *
   1.161 - * \return A pointer to a UTF-8 string that stays valid at least until the next call to this function. If you need it around any longer, you must copy it.  If the scancode doesn't have a name, this function returns "".
   1.162 - *
   1.163 - * \sa SDL_scancode
   1.164 + *  \sa SDL_scancode
   1.165   */
   1.166  extern DECLSPEC const char *SDLCALL SDL_GetScancodeName(SDL_scancode
   1.167                                                          scancode);
   1.168  
   1.169  /**
   1.170 - * \fn const char *SDL_GetKeyName(SDLKey key)
   1.171 - * 
   1.172 - * \brief Get a human-readable name for a key.
   1.173 - *
   1.174 - * \return A pointer to a UTF-8 string that stays valid at least until the next call to this function. If you need it around any longer, you must copy it.  If the key doesn't have a name, this function returns "".
   1.175 - *
   1.176 - * \sa SDLKey
   1.177 + *  \brief Get a human-readable name for a key.
   1.178 + *  
   1.179 + *  \return A pointer to a UTF-8 string that stays valid at least until the next
   1.180 + *          call to this function. If you need it around any longer, you must 
   1.181 + *          copy it.  If the key doesn't have a name, this function returns an 
   1.182 + *          empty string ("").
   1.183 + *  
   1.184 + *  \sa SDLKey
   1.185   */
   1.186  extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDLKey key);
   1.187  
   1.188  /**
   1.189 - * \fn void SDL_StartTextInput(void)
   1.190 - *
   1.191 - * \brief Start accepting Unicode text input events.
   1.192 - *
   1.193 - * \sa SDL_StopTextInput()
   1.194 - * \sa SDL_SetTextInputRect()
   1.195 + *  \brief Start accepting Unicode text input events.
   1.196 + *  
   1.197 + *  \sa SDL_StopTextInput()
   1.198 + *  \sa SDL_SetTextInputRect()
   1.199   */
   1.200  extern DECLSPEC void SDLCALL SDL_StartTextInput(void);
   1.201  
   1.202  /**
   1.203 - * \fn void SDL_StopTextInput(void)
   1.204 - *
   1.205 - * \brief Stop receiving any text input events.
   1.206 - *
   1.207 - * \sa SDL_StartTextInput()
   1.208 + *  \brief Stop receiving any text input events.
   1.209 + *  
   1.210 + *  \sa SDL_StartTextInput()
   1.211   */
   1.212  extern DECLSPEC void SDLCALL SDL_StopTextInput(void);
   1.213  
   1.214  /**
   1.215 - * \fn void SDL_SetTextInputRect(SDL_Rect *rect)
   1.216 - *
   1.217 - * \brief Set the rectangle used to type Unicode text inputs.
   1.218 - *
   1.219 - * \sa SDL_StartTextInput()
   1.220 + *  \brief Set the rectangle used to type Unicode text inputs.
   1.221 + *  
   1.222 + *  \sa SDL_StartTextInput()
   1.223   */
   1.224  extern DECLSPEC void SDLCALL SDL_SetTextInputRect(SDL_Rect *rect);
   1.225