include/SDL_joystick.h
changeset 3407 d3baf5ac4e37
parent 2859 99210400e8b9
child 3697 f7b03b6838cb
     1.1 --- a/include/SDL_joystick.h	Sun Oct 18 23:21:15 2009 +0000
     1.2 +++ b/include/SDL_joystick.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_joystick.h
     1.8 - *
     1.9 - * Include file for SDL joystick event handling
    1.10 + *  \file SDL_joystick.h
    1.11 + *  
    1.12 + *  Include file for SDL joystick event handling
    1.13   */
    1.14  
    1.15  #ifndef _SDL_joystick_h
    1.16 @@ -40,10 +40,13 @@
    1.17  /* *INDENT-ON* */
    1.18  #endif
    1.19  
    1.20 -/* In order to use these functions, SDL_Init() must have been called
    1.21 -   with the SDL_INIT_JOYSTICK flag.  This causes SDL to scan the system
    1.22 -   for joysticks, and load appropriate drivers.
    1.23 -*/
    1.24 +/**
    1.25 + *  \file SDL_joystick.h
    1.26 + *
    1.27 + *  In order to use these functions, SDL_Init() must have been called
    1.28 + *  with the ::SDL_INIT_JOYSTICK flag.  This causes SDL to scan the system
    1.29 + *  for joysticks, and load appropriate drivers.
    1.30 + */
    1.31  
    1.32  /* The joystick structure used to identify an SDL joystick */
    1.33  struct _SDL_Joystick;
    1.34 @@ -51,87 +54,94 @@
    1.35  
    1.36  
    1.37  /* Function prototypes */
    1.38 -/*
    1.39 - * Count the number of joysticks attached to the system
    1.40 +/**
    1.41 + *  Count the number of joysticks attached to the system
    1.42   */
    1.43  extern DECLSPEC int SDLCALL SDL_NumJoysticks(void);
    1.44  
    1.45 -/*
    1.46 - * Get the implementation dependent name of a joystick.
    1.47 - * This can be called before any joysticks are opened.
    1.48 - * If no name can be found, this function returns NULL.
    1.49 +/**
    1.50 + *  Get the implementation dependent name of a joystick.
    1.51 + *  This can be called before any joysticks are opened.
    1.52 + *  If no name can be found, this function returns NULL.
    1.53   */
    1.54  extern DECLSPEC const char *SDLCALL SDL_JoystickName(int device_index);
    1.55  
    1.56 -/*
    1.57 - * Open a joystick for use - the index passed as an argument refers to
    1.58 - * the N'th joystick on the system.  This index is the value which will
    1.59 - * identify this joystick in future joystick events.
    1.60 - *
    1.61 - * This function returns a joystick identifier, or NULL if an error occurred.
    1.62 +/**
    1.63 + *  Open a joystick for use.  
    1.64 + *  The index passed as an argument refers tothe N'th joystick on the system.  
    1.65 + *  This index is the value which will identify this joystick in future joystick
    1.66 + *  events.
    1.67 + *  
    1.68 + *  \return A joystick identifier, or NULL if an error occurred.
    1.69   */
    1.70  extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickOpen(int device_index);
    1.71  
    1.72 -/*
    1.73 - * Returns 1 if the joystick has been opened, or 0 if it has not.
    1.74 +/**
    1.75 + *  Returns 1 if the joystick has been opened, or 0 if it has not.
    1.76   */
    1.77  extern DECLSPEC int SDLCALL SDL_JoystickOpened(int device_index);
    1.78  
    1.79 -/*
    1.80 - * Get the device index of an opened joystick.
    1.81 +/**
    1.82 + *  Get the device index of an opened joystick.
    1.83   */
    1.84  extern DECLSPEC int SDLCALL SDL_JoystickIndex(SDL_Joystick * joystick);
    1.85  
    1.86 -/*
    1.87 - * Get the number of general axis controls on a joystick
    1.88 +/**
    1.89 + *  Get the number of general axis controls on a joystick.
    1.90   */
    1.91  extern DECLSPEC int SDLCALL SDL_JoystickNumAxes(SDL_Joystick * joystick);
    1.92  
    1.93 -/*
    1.94 - * Get the number of trackballs on a joystick
    1.95 - * Joystick trackballs have only relative motion events associated
    1.96 - * with them and their state cannot be polled.
    1.97 +/**
    1.98 + *  Get the number of trackballs on a joystick.
    1.99 + *  
   1.100 + *  Joystick trackballs have only relative motion events associated
   1.101 + *  with them and their state cannot be polled.
   1.102   */
   1.103  extern DECLSPEC int SDLCALL SDL_JoystickNumBalls(SDL_Joystick * joystick);
   1.104  
   1.105 -/*
   1.106 - * Get the number of POV hats on a joystick
   1.107 +/**
   1.108 + *  Get the number of POV hats on a joystick.
   1.109   */
   1.110  extern DECLSPEC int SDLCALL SDL_JoystickNumHats(SDL_Joystick * joystick);
   1.111  
   1.112 -/*
   1.113 - * Get the number of buttons on a joystick
   1.114 +/**
   1.115 + *  Get the number of buttons on a joystick.
   1.116   */
   1.117  extern DECLSPEC int SDLCALL SDL_JoystickNumButtons(SDL_Joystick * joystick);
   1.118  
   1.119 -/*
   1.120 - * Update the current state of the open joysticks.
   1.121 - * This is called automatically by the event loop if any joystick
   1.122 - * events are enabled.
   1.123 +/**
   1.124 + *  Update the current state of the open joysticks.
   1.125 + *  
   1.126 + *  This is called automatically by the event loop if any joystick
   1.127 + *  events are enabled.
   1.128   */
   1.129  extern DECLSPEC void SDLCALL SDL_JoystickUpdate(void);
   1.130  
   1.131 -/*
   1.132 - * Enable/disable joystick event polling.
   1.133 - * If joystick events are disabled, you must call SDL_JoystickUpdate()
   1.134 - * yourself and check the state of the joystick when you want joystick
   1.135 - * information.
   1.136 - * The state can be one of SDL_QUERY, SDL_ENABLE or SDL_IGNORE.
   1.137 +/**
   1.138 + *  Enable/disable joystick event polling.
   1.139 + *  
   1.140 + *  If joystick events are disabled, you must call SDL_JoystickUpdate()
   1.141 + *  yourself and check the state of the joystick when you want joystick
   1.142 + *  information.
   1.143 + *  
   1.144 + *  The state can be one of ::SDL_QUERY, ::SDL_ENABLE or ::SDL_IGNORE.
   1.145   */
   1.146  extern DECLSPEC int SDLCALL SDL_JoystickEventState(int state);
   1.147  
   1.148 -/*
   1.149 - * Get the current state of an axis control on a joystick
   1.150 - * The state is a value ranging from -32768 to 32767.
   1.151 - * The axis indices start at index 0.
   1.152 +/**
   1.153 + *  Get the current state of an axis control on a joystick.
   1.154 + *  
   1.155 + *  The state is a value ranging from -32768 to 32767.
   1.156 + *  
   1.157 + *  The axis indices start at index 0.
   1.158   */
   1.159  extern DECLSPEC Sint16 SDLCALL SDL_JoystickGetAxis(SDL_Joystick * joystick,
   1.160                                                     int axis);
   1.161  
   1.162 -/*
   1.163 - * Get the current state of a POV hat on a joystick
   1.164 - * The return value is one of the following positions:
   1.165 +/**
   1.166 + *  \name Hat positions
   1.167   */
   1.168 +/*@{*/
   1.169  #define SDL_HAT_CENTERED	0x00
   1.170  #define SDL_HAT_UP		0x01
   1.171  #define SDL_HAT_RIGHT		0x02
   1.172 @@ -141,29 +151,47 @@
   1.173  #define SDL_HAT_RIGHTDOWN	(SDL_HAT_RIGHT|SDL_HAT_DOWN)
   1.174  #define SDL_HAT_LEFTUP		(SDL_HAT_LEFT|SDL_HAT_UP)
   1.175  #define SDL_HAT_LEFTDOWN	(SDL_HAT_LEFT|SDL_HAT_DOWN)
   1.176 -/*
   1.177 - * The hat indices start at index 0.
   1.178 +/*@}*/
   1.179 +
   1.180 +/**
   1.181 + *  Get the current state of a POV hat on a joystick.
   1.182 + *
   1.183 + *  The hat indices start at index 0.
   1.184 + *  
   1.185 + *  \return The return value is one of the following positions:
   1.186 + *           - ::SDL_HAT_CENTERED
   1.187 + *           - ::SDL_HAT_UP
   1.188 + *           - ::SDL_HAT_RIGHT
   1.189 + *           - ::SDL_HAT_DOWN
   1.190 + *           - ::SDL_HAT_LEFT
   1.191 + *           - ::SDL_HAT_RIGHTUP
   1.192 + *           - ::SDL_HAT_RIGHTDOWN
   1.193 + *           - ::SDL_HAT_LEFTUP
   1.194 + *           - ::SDL_HAT_LEFTDOWN
   1.195   */
   1.196  extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetHat(SDL_Joystick * joystick,
   1.197                                                   int hat);
   1.198  
   1.199 -/*
   1.200 - * Get the ball axis change since the last poll
   1.201 - * This returns 0, or -1 if you passed it invalid parameters.
   1.202 - * The ball indices start at index 0.
   1.203 +/**
   1.204 + *  Get the ball axis change since the last poll.
   1.205 + *  
   1.206 + *  \return 0, or -1 if you passed it invalid parameters.
   1.207 + *  
   1.208 + *  The ball indices start at index 0.
   1.209   */
   1.210  extern DECLSPEC int SDLCALL SDL_JoystickGetBall(SDL_Joystick * joystick,
   1.211                                                  int ball, int *dx, int *dy);
   1.212  
   1.213 -/*
   1.214 - * Get the current state of a button on a joystick
   1.215 - * The button indices start at index 0.
   1.216 +/**
   1.217 + *  Get the current state of a button on a joystick.
   1.218 + *  
   1.219 + *  The button indices start at index 0.
   1.220   */
   1.221  extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetButton(SDL_Joystick * joystick,
   1.222                                                      int button);
   1.223  
   1.224 -/*
   1.225 - * Close a joystick previously opened with SDL_JoystickOpen()
   1.226 +/**
   1.227 + *  Close a joystick previously opened with SDL_JoystickOpen().
   1.228   */
   1.229  extern DECLSPEC void SDLCALL SDL_JoystickClose(SDL_Joystick * joystick);
   1.230