include/SDL_keyboard.h
branchSDL-1.2
changeset 4217 4c4113c2162c
parent 4159 a1b03ba2fcd0
child 6137 4720145f848b
     1.1 --- a/include/SDL_keyboard.h	Mon Sep 21 09:27:08 2009 +0000
     1.2 +++ b/include/SDL_keyboard.h	Mon Sep 21 09:38:10 2009 +0000
     1.3 @@ -20,7 +20,9 @@
     1.4      slouken@libsdl.org
     1.5  */
     1.6  
     1.7 -/* Include file for SDL keyboard event handling */
     1.8 +/** @file SDL_keyboard.h
     1.9 + *  Include file for SDL keyboard event handling
    1.10 + */
    1.11  
    1.12  #ifndef _SDL_keyboard_h
    1.13  #define _SDL_keyboard_h
    1.14 @@ -35,78 +37,90 @@
    1.15  extern "C" {
    1.16  #endif
    1.17  
    1.18 -/* Keysym structure
    1.19 -   - The scancode is hardware dependent, and should not be used by general
    1.20 -     applications.  If no hardware scancode is available, it will be 0.
    1.21 -
    1.22 -   - The 'unicode' translated character is only available when character
    1.23 -     translation is enabled by the SDL_EnableUNICODE() API.  If non-zero,
    1.24 -     this is a UNICODE character corresponding to the keypress.  If the
    1.25 -     high 9 bits of the character are 0, then this maps to the equivalent
    1.26 -     ASCII character:
    1.27 -	char ch;
    1.28 -	if ( (keysym.unicode & 0xFF80) == 0 ) {
    1.29 -		ch = keysym.unicode & 0x7F;
    1.30 -	} else {
    1.31 -		An international character..
    1.32 -	}
    1.33 +/** Keysym structure
    1.34 + *
    1.35 + *  - The scancode is hardware dependent, and should not be used by general
    1.36 + *    applications.  If no hardware scancode is available, it will be 0.
    1.37 + *
    1.38 + *  - The 'unicode' translated character is only available when character
    1.39 + *    translation is enabled by the SDL_EnableUNICODE() API.  If non-zero,
    1.40 + *    this is a UNICODE character corresponding to the keypress.  If the
    1.41 + *    high 9 bits of the character are 0, then this maps to the equivalent
    1.42 + *    ASCII character:
    1.43 + *      @code
    1.44 + *	char ch;
    1.45 + *	if ( (keysym.unicode & 0xFF80) == 0 ) {
    1.46 + *		ch = keysym.unicode & 0x7F;
    1.47 + *	} else {
    1.48 + *		An international character..
    1.49 + *	}
    1.50 + *      @endcode
    1.51   */
    1.52  typedef struct SDL_keysym {
    1.53 -	Uint8 scancode;			/* hardware specific scancode */
    1.54 -	SDLKey sym;			/* SDL virtual keysym */
    1.55 -	SDLMod mod;			/* current key modifiers */
    1.56 -	Uint16 unicode;			/* translated character */
    1.57 +	Uint8 scancode;			/**< hardware specific scancode */
    1.58 +	SDLKey sym;			/**< SDL virtual keysym */
    1.59 +	SDLMod mod;			/**< current key modifiers */
    1.60 +	Uint16 unicode;			/**< translated character */
    1.61  } SDL_keysym;
    1.62  
    1.63 -/* This is the mask which refers to all hotkey bindings */
    1.64 +/** This is the mask which refers to all hotkey bindings */
    1.65  #define SDL_ALL_HOTKEYS		0xFFFFFFFF
    1.66  
    1.67  /* Function prototypes */
    1.68 -/*
    1.69 +/**
    1.70   * Enable/Disable UNICODE translation of keyboard input.
    1.71 + *
    1.72   * This translation has some overhead, so translation defaults off.
    1.73 + *
    1.74 + * @param[in] enable
    1.75   * If 'enable' is 1, translation is enabled.
    1.76   * If 'enable' is 0, translation is disabled.
    1.77   * If 'enable' is -1, the translation state is not changed.
    1.78 - * It returns the previous state of keyboard translation.
    1.79 + *
    1.80 + * @return It returns the previous state of keyboard translation.
    1.81   */
    1.82  extern DECLSPEC int SDLCALL SDL_EnableUNICODE(int enable);
    1.83  
    1.84 -/*
    1.85 - * Enable/Disable keyboard repeat.  Keyboard repeat defaults to off.
    1.86 - * 'delay' is the initial delay in ms between the time when a key is
    1.87 - * pressed, and keyboard repeat begins.
    1.88 - * 'interval' is the time in ms between keyboard repeat events.
    1.89 - */
    1.90  #define SDL_DEFAULT_REPEAT_DELAY	500
    1.91  #define SDL_DEFAULT_REPEAT_INTERVAL	30
    1.92 -/*
    1.93 - * If 'delay' is set to 0, keyboard repeat is disabled.
    1.94 +/**
    1.95 + * Enable/Disable keyboard repeat.  Keyboard repeat defaults to off.
    1.96 + *
    1.97 + *  @param[in] delay
    1.98 + *  'delay' is the initial delay in ms between the time when a key is
    1.99 + *  pressed, and keyboard repeat begins.
   1.100 + *
   1.101 + *  @param[in] interval
   1.102 + *  'interval' is the time in ms between keyboard repeat events.
   1.103 + *
   1.104 + *  If 'delay' is set to 0, keyboard repeat is disabled.
   1.105   */
   1.106  extern DECLSPEC int SDLCALL SDL_EnableKeyRepeat(int delay, int interval);
   1.107  extern DECLSPEC void SDLCALL SDL_GetKeyRepeat(int *delay, int *interval);
   1.108  
   1.109 -/*
   1.110 +/**
   1.111   * Get a snapshot of the current state of the keyboard.
   1.112   * Returns an array of keystates, indexed by the SDLK_* syms.
   1.113 - * Used:
   1.114 + * Usage:
   1.115 + *	@code
   1.116   * 	Uint8 *keystate = SDL_GetKeyState(NULL);
   1.117 - *	if ( keystate[SDLK_RETURN] ) ... <RETURN> is pressed.
   1.118 + *	if ( keystate[SDLK_RETURN] ) //... \<RETURN> is pressed.
   1.119 + *	@endcode
   1.120   */
   1.121  extern DECLSPEC Uint8 * SDLCALL SDL_GetKeyState(int *numkeys);
   1.122  
   1.123 -/*
   1.124 +/**
   1.125   * Get the current key modifier state
   1.126   */
   1.127  extern DECLSPEC SDLMod SDLCALL SDL_GetModState(void);
   1.128  
   1.129 -/*
   1.130 - * Set the current key modifier state
   1.131 +/**
   1.132 + * Set the current key modifier state.
   1.133   * This does not change the keyboard state, only the key modifier flags.
   1.134   */
   1.135  extern DECLSPEC void SDLCALL SDL_SetModState(SDLMod modstate);
   1.136  
   1.137 -/*
   1.138 +/**
   1.139   * Get the name of an SDL virtual keysym
   1.140   */
   1.141  extern DECLSPEC char * SDLCALL SDL_GetKeyName(SDLKey key);