Mercurial > sdl-ios-xcode
diff include/SDL_keyboard.h @ 1673:624e1412fbba SDL-1.3
Keyboard code update in progress
author | Sam Lantinga <slouken@libsdl.org> |
---|---|
date | Sat, 10 Jun 2006 09:11:59 +0000 |
parents | 4da1ee79c9af |
children | 7688a73b25b1 |
line wrap: on
line diff
--- a/include/SDL_keyboard.h Fri Jun 09 07:06:12 2006 +0000 +++ b/include/SDL_keyboard.h Sat Jun 10 09:11:59 2006 +0000 @@ -41,82 +41,116 @@ /* *INDENT-ON* */ #endif -/* Keysym structure - - The scancode is hardware dependent, and should not be used by general - applications. If no hardware scancode is available, it will be 0. - - - The 'unicode' translated character is only available when character - translation is enabled by the SDL_EnableUNICODE() API. If non-zero, - this is a UNICODE character corresponding to the keypress. If the - high 9 bits of the character are 0, then this maps to the equivalent - ASCII character: - char ch; - if ( (keysym.unicode & 0xFF80) == 0 ) { - ch = keysym.unicode & 0x7F; - } else { - An international character.. - } +/** + * \struct SDL_keysym + * + * \brief The SDL keysym structure, used in key events. */ typedef struct SDL_keysym { - Uint8 scancode; /* hardware specific scancode */ - SDLKey sym; /* SDL virtual keysym */ - SDLMod mod; /* current key modifiers */ - Uint16 unicode; /* translated character */ + Uint8 scancode; /**< keyboard specific scancode */ + SDLKey sym; /**< SDL virtual keysym */ + SDLMod mod; /**< current key modifiers */ } SDL_keysym; -/* This is the mask which refers to all hotkey bindings */ -#define SDL_ALL_HOTKEYS 0xFFFFFFFF +/* Function prototypes */ + +/** + * \fn int SDL_GetNumKeyboards(void) + * + * \brief Get the number of keyboard input devices available. + * + * \sa SDL_SelectKeyboard() + */ +extern DECLSPEC int SDLCALL SDL_GetNumKeyboards(void); -/* Function prototypes */ -/* - * Enable/Disable UNICODE translation of keyboard input. - * This translation has some overhead, so translation defaults off. - * If 'enable' is 1, translation is enabled. - * If 'enable' is 0, translation is disabled. - * If 'enable' is -1, the translation state is not changed. - * It returns the previous state of keyboard translation. +/** + * \fn int SDL_SelectKeyboard(int index) + * + * \brief Set the index of the currently selected keyboard. + * + * \return The index of the previously selected keyboard. + * + * \note You can query the currently selected keyboard by passing an index of -1. + * + * \sa SDL_GetNumKeyboards() + */ +extern DECLSPEC int SDLCALL SDL_SelectKeyboard(int index); + +/** + * \fn int SDL_EnableUNICODE(int enable) + * + * \brief Enable/Disable UNICODE translation of keyboard input. + * + * \param enable 1 to enable translation, 0 to disable translation, -1 to query translation + * + * \return The previous state of keyboard translation + * + * \note This translation has some overhead, so translation defaults off. */ extern DECLSPEC int SDLCALL SDL_EnableUNICODE(int enable); -/* - * Enable/Disable keyboard repeat. Keyboard repeat defaults to off. - * 'delay' is the initial delay in ms between the time when a key is - * pressed, and keyboard repeat begins. - * 'interval' is the time in ms between keyboard repeat events. +/** + * \fn int SDL_EnableKeyRepeat(int delay, int interval) + * + * \brief Enable keyboard repeat for the selected keyboard. + * + * \param delay The initial delay in milliseconds between the time when a + * key is pressed and keyboard repeat begins. Setting a delay + * of 0 will disable keyboard repeat. + * \param interval The time in milliseconds between keyboard repeat events. + * + * \return 0 on success, or -1 if there was an error. + * + * \note Keyboard repeat defaults to off. */ #define SDL_DEFAULT_REPEAT_DELAY 500 #define SDL_DEFAULT_REPEAT_INTERVAL 30 -/* - * If 'delay' is set to 0, keyboard repeat is disabled. + /**/ + extern DECLSPEC int SDLCALL SDL_EnableKeyRepeat(int delay, int interval); + +/** + * \fn void SDL_GetKeyRepeat(int *delay, int *interval) + * + * \brief Get the current keyboard repeat setting for the selected keyboard. */ -extern DECLSPEC int SDLCALL SDL_EnableKeyRepeat(int delay, int interval); extern DECLSPEC void SDLCALL SDL_GetKeyRepeat(int *delay, int *interval); -/* - * Get a snapshot of the current state of the keyboard. - * Returns an array of keystates, indexed by the SDLK_* syms. - * Used: +/** + * \fn Uint8 *SDL_GetKeyState(int *numkeys) + * + * \brief Get a snapshot of the current state of the selected keyboard. + * + * \return An array of keystates, indexed by the SDLK_* syms. + * + * Example: * Uint8 *keystate = SDL_GetKeyState(NULL); * if ( keystate[SDLK_RETURN] ) ... <RETURN> is pressed. */ extern DECLSPEC Uint8 *SDLCALL SDL_GetKeyState(int *numkeys); -/* - * Get the current key modifier state +/** + * \fn SDLMod SDL_GetModState(void) + * + * \brief Get the current key modifier state for the selected keyboard. */ extern DECLSPEC SDLMod SDLCALL SDL_GetModState(void); -/* - * Set the current key modifier state - * This does not change the keyboard state, only the key modifier flags. +/** + * \fn void SDL_SetModState(SDLMod modstate) + * + * \brief Set the current key modifier state for the selected keyboard. + * + * \note This does not change the keyboard state, only the key modifier flags. */ extern DECLSPEC void SDLCALL SDL_SetModState(SDLMod modstate); -/* - * Get the name of an SDL virtual keysym +/** + * \fn const char *SDL_GetKeyName(SDLKey key) + * + * \brief Get the name of an SDL virtual keysym */ -extern DECLSPEC char *SDLCALL SDL_GetKeyName(SDLKey key); +extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDLKey key); /* Ends C function definitions when using C++ */