include/SDL_keyboard.h
changeset 2268 4baee598306d
parent 2129 047245361002
child 2303 d87417504c75
     1.1 --- a/include/SDL_keyboard.h	Sat Aug 18 05:39:09 2007 +0000
     1.2 +++ b/include/SDL_keyboard.h	Sun Aug 19 14:52:52 2007 +0000
     1.3 @@ -50,7 +50,7 @@
     1.4  {
     1.5      Uint8 scancode;             /**< keyboard specific scancode */
     1.6      Uint8 padding[3];           /**< alignment padding */
     1.7 -    Uint16 sym;                 /**< SDL virtual keysym */
     1.8 +    SDLKey sym;                 /**< SDL virtual key code - see ::SDLKey for details */
     1.9      Uint16 mod;                 /**< current key modifiers */
    1.10      Uint32 unicode;             /**< OBSOLETE, use SDL_TextInputEvent instead */
    1.11  } SDL_keysym;
    1.12 @@ -97,11 +97,13 @@
    1.13   *
    1.14   * \brief Get a snapshot of the current state of the selected keyboard.
    1.15   *
    1.16 - * \return An array of keystates, indexed by the SDLK_* syms.
    1.17 + * \param numkeys if non-NULL, receives the length of the returned array.
    1.18 + *
    1.19 + * \return An array of key states. Indexes into this array are obtained by using the SDLK_INDEX() macro on the \link ::SDLPhysicalKey SDLK_* \endlink syms.
    1.20   *
    1.21   * Example:
    1.22   * 	Uint8 *keystate = SDL_GetKeyState(NULL);
    1.23 - *	if ( keystate[SDLK_RETURN] ) ... <RETURN> is pressed.
    1.24 + *	if ( keystate[SDLK_INDEX(SDLK_RETURN)] ) ... <RETURN> is pressed.
    1.25   */
    1.26  extern DECLSPEC Uint8 *SDLCALL SDL_GetKeyState(int *numkeys);
    1.27  
    1.28 @@ -122,11 +124,32 @@
    1.29  extern DECLSPEC void SDLCALL SDL_SetModState(SDLMod modstate);
    1.30  
    1.31  /**
    1.32 - * \fn const char *SDL_GetKeyName(SDLKey key)
    1.33 + * \fn SDLKey SDL_GetLayoutKey(SDLKey physicalKey)
    1.34   * 
    1.35 - * \brief Get the name of an SDL virtual keysym
    1.36 + * \brief Get the layout key code corresponding to the given physical key code according to the current keyboard layout.
    1.37 + *
    1.38 + * See ::SDLKey for details.
    1.39 + *
    1.40 + * If \a physicalKey is not a physical key code, it is returned unchanged.
    1.41 + *
    1.42 + * \sa SDL_GetKeyName()
    1.43   */
    1.44 -extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDLKey key);
    1.45 +extern DECLSPEC SDLKey SDLCALL SDL_GetLayoutKey(SDLKey physicalKey);
    1.46 +
    1.47 +/**
    1.48 + * \fn const char *SDL_GetKeyName(SDLKey layoutKey)
    1.49 + * 
    1.50 + * \brief Get a human-readable name for a key.
    1.51 + *
    1.52 + * \param layoutKey An SDL layout key code.
    1.53 + *
    1.54 + * If what you have is a physical key code, e.g. from the \link SDL_keysym::sym key.keysym.sym \endlink field of the SDL_Event structure, convert it to a layout key code using SDL_GetLayoutKey() first. Doing this ensures that the returned name matches what users see on their keyboards. Calling this function directly on a physical key code (that is not also a layout key code) is possible, but is not recommended except for debugging purposes. The name returned in that case is the name of the \link ::SDLPhysicalKey SDLK_* \endlink constant and is not suitable for display to users.
    1.55 + *
    1.56 + * \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. Always non-NULL.
    1.57 + *
    1.58 + * \sa SDLKey
    1.59 + */
    1.60 +extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDLKey layoutKey);
    1.61  
    1.62  
    1.63  /* Ends C function definitions when using C++ */