Mercurial > sdl-ios-xcode

comparison include/SDL_joystick.h @ 4217:4c4113c2162c SDL-1.2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fixed bug #706 Ken Bull 2009-02-25 13:22:02 PST Adds Doxygen support for all headers (except config and boilerplate headers) in the include folder for SDL-1.2 revision 4446. While in general SDL is quite thoroughly commented, none of these comments are correctly formatted for Doxygen and are generally inconsistent in their formatting.
author Sam Lantinga <slouken@libsdl.org>
date Mon, 21 Sep 2009 09:38:10 +0000
parents a1b03ba2fcd0
children
comparison
equal deleted inserted replaced
4216:5b99971a27b4 4217:4c4113c2162c
18 18
19 Sam Lantinga 19 Sam Lantinga
20 slouken@libsdl.org 20 slouken@libsdl.org
21 */ 21 */
22 22
23 /* Include file for SDL joystick event handling */ 23 /** @file SDL_joystick.h
24 * Include file for SDL joystick event handling
25 */
24 26
25 #ifndef _SDL_joystick_h 27 #ifndef _SDL_joystick_h
26 #define _SDL_joystick_h 28 #define _SDL_joystick_h
27 29
28 #include "SDL_stdinc.h" 30 #include "SDL_stdinc.h"
32 /* Set up for C function definitions, even when using C++ */ 34 /* Set up for C function definitions, even when using C++ */
33 #ifdef __cplusplus 35 #ifdef __cplusplus
34 extern "C" { 36 extern "C" {
35 #endif 37 #endif
36 38
37 /* In order to use these functions, SDL_Init() must have been called 39 /** @file SDL_joystick.h
38 with the SDL_INIT_JOYSTICK flag. This causes SDL to scan the system 40 * @note In order to use these functions, SDL_Init() must have been called
39 for joysticks, and load appropriate drivers. 41 * with the SDL_INIT_JOYSTICK flag. This causes SDL to scan the system
40 */ 42 * for joysticks, and load appropriate drivers.
43 */
41 44
42 /* The joystick structure used to identify an SDL joystick */ 45 /** The joystick structure used to identify an SDL joystick */
43 struct _SDL_Joystick; 46 struct _SDL_Joystick;
44 typedef struct _SDL_Joystick SDL_Joystick; 47 typedef struct _SDL_Joystick SDL_Joystick;
45 48
46
47 /* Function prototypes */ 49 /* Function prototypes */
48 /* 50 /**
49 * Count the number of joysticks attached to the system 51 * Count the number of joysticks attached to the system
50 */ 52 */
51 extern DECLSPEC int SDLCALL SDL_NumJoysticks(void); 53 extern DECLSPEC int SDLCALL SDL_NumJoysticks(void);
52 54
53 /* 55 /**
54 * Get the implementation dependent name of a joystick. 56 * Get the implementation dependent name of a joystick.
57 *
55 * This can be called before any joysticks are opened. 58 * This can be called before any joysticks are opened.
56 * If no name can be found, this function returns NULL. 59 * If no name can be found, this function returns NULL.
57 */ 60 */
58 extern DECLSPEC const char * SDLCALL SDL_JoystickName(int device_index); 61 extern DECLSPEC const char * SDLCALL SDL_JoystickName(int device_index);
59 62
60 /* 63 /**
61 * Open a joystick for use - the index passed as an argument refers to 64 * Open a joystick for use.
65 *
66 * @param[in] device_index
67 * The index passed as an argument refers to
62 * the N'th joystick on the system. This index is the value which will 68 * the N'th joystick on the system. This index is the value which will
63 * identify this joystick in future joystick events. 69 * identify this joystick in future joystick events.
64 * 70 *
65 * This function returns a joystick identifier, or NULL if an error occurred. 71 * @return This function returns a joystick identifier, or NULL if an error occurred.
66 */ 72 */
67 extern DECLSPEC SDL_Joystick * SDLCALL SDL_JoystickOpen(int device_index); 73 extern DECLSPEC SDL_Joystick * SDLCALL SDL_JoystickOpen(int device_index);
68 74
69 /* 75 /**
70 * Returns 1 if the joystick has been opened, or 0 if it has not. 76 * Returns 1 if the joystick has been opened, or 0 if it has not.
71 */ 77 */
72 extern DECLSPEC int SDLCALL SDL_JoystickOpened(int device_index); 78 extern DECLSPEC int SDLCALL SDL_JoystickOpened(int device_index);
73 79
74 /* 80 /**
75 * Get the device index of an opened joystick. 81 * Get the device index of an opened joystick.
76 */ 82 */
77 extern DECLSPEC int SDLCALL SDL_JoystickIndex(SDL_Joystick *joystick); 83 extern DECLSPEC int SDLCALL SDL_JoystickIndex(SDL_Joystick *joystick);
78 84
79 /* 85 /**
80 * Get the number of general axis controls on a joystick 86 * Get the number of general axis controls on a joystick
81 */ 87 */
82 extern DECLSPEC int SDLCALL SDL_JoystickNumAxes(SDL_Joystick *joystick); 88 extern DECLSPEC int SDLCALL SDL_JoystickNumAxes(SDL_Joystick *joystick);
83 89
84 /* 90 /**
85 * Get the number of trackballs on a joystick 91 * Get the number of trackballs on a joystick
92 *
86 * Joystick trackballs have only relative motion events associated 93 * Joystick trackballs have only relative motion events associated
87 * with them and their state cannot be polled. 94 * with them and their state cannot be polled.
88 */ 95 */
89 extern DECLSPEC int SDLCALL SDL_JoystickNumBalls(SDL_Joystick *joystick); 96 extern DECLSPEC int SDLCALL SDL_JoystickNumBalls(SDL_Joystick *joystick);
90 97
91 /* 98 /**
92 * Get the number of POV hats on a joystick 99 * Get the number of POV hats on a joystick
93 */ 100 */
94 extern DECLSPEC int SDLCALL SDL_JoystickNumHats(SDL_Joystick *joystick); 101 extern DECLSPEC int SDLCALL SDL_JoystickNumHats(SDL_Joystick *joystick);
95 102
96 /* 103 /**
97 * Get the number of buttons on a joystick 104 * Get the number of buttons on a joystick
98 */ 105 */
99 extern DECLSPEC int SDLCALL SDL_JoystickNumButtons(SDL_Joystick *joystick); 106 extern DECLSPEC int SDLCALL SDL_JoystickNumButtons(SDL_Joystick *joystick);
100 107
101 /* 108 /**
102 * Update the current state of the open joysticks. 109 * Update the current state of the open joysticks.
110 *
103 * This is called automatically by the event loop if any joystick 111 * This is called automatically by the event loop if any joystick
104 * events are enabled. 112 * events are enabled.
105 */ 113 */
106 extern DECLSPEC void SDLCALL SDL_JoystickUpdate(void); 114 extern DECLSPEC void SDLCALL SDL_JoystickUpdate(void);
107 115
108 /* 116 /**
109 * Enable/disable joystick event polling. 117 * Enable/disable joystick event polling.
118 *
110 * If joystick events are disabled, you must call SDL_JoystickUpdate() 119 * If joystick events are disabled, you must call SDL_JoystickUpdate()
111 * yourself and check the state of the joystick when you want joystick 120 * yourself and check the state of the joystick when you want joystick
112 * information. 121 * information.
113 * The state can be one of SDL_QUERY, SDL_ENABLE or SDL_IGNORE. 122 *
123 * @param[in] state The state can be one of SDL_QUERY, SDL_ENABLE or SDL_IGNORE.
114 */ 124 */
115 extern DECLSPEC int SDLCALL SDL_JoystickEventState(int state); 125 extern DECLSPEC int SDLCALL SDL_JoystickEventState(int state);
116 126
117 /* 127 /**
118 * Get the current state of an axis control on a joystick 128 * Get the current state of an axis control on a joystick
119 * The state is a value ranging from -32768 to 32767. 129 *
120 * The axis indices start at index 0. 130 * @param[in] axis The axis indices start at index 0.
131 *
132 * @return The state is a value ranging from -32768 to 32767.
121 */ 133 */
122 extern DECLSPEC Sint16 SDLCALL SDL_JoystickGetAxis(SDL_Joystick *joystick, int axis); 134 extern DECLSPEC Sint16 SDLCALL SDL_JoystickGetAxis(SDL_Joystick *joystick, int axis);
123 135
124 /* 136 /**
125 * Get the current state of a POV hat on a joystick 137 * @name Hat Positions
126 * The return value is one of the following positions: 138 * The return value of SDL_JoystickGetHat() is one of the following positions:
127 */ 139 */
140 /*@{*/
128 #define SDL_HAT_CENTERED 0x00 141 #define SDL_HAT_CENTERED 0x00
129 #define SDL_HAT_UP 0x01 142 #define SDL_HAT_UP 0x01
130 #define SDL_HAT_RIGHT 0x02 143 #define SDL_HAT_RIGHT 0x02
131 #define SDL_HAT_DOWN 0x04 144 #define SDL_HAT_DOWN 0x04
132 #define SDL_HAT_LEFT 0x08 145 #define SDL_HAT_LEFT 0x08
133 #define SDL_HAT_RIGHTUP (SDL_HAT_RIGHT|SDL_HAT_UP) 146 #define SDL_HAT_RIGHTUP (SDL_HAT_RIGHT|SDL_HAT_UP)
134 #define SDL_HAT_RIGHTDOWN (SDL_HAT_RIGHT|SDL_HAT_DOWN) 147 #define SDL_HAT_RIGHTDOWN (SDL_HAT_RIGHT|SDL_HAT_DOWN)
135 #define SDL_HAT_LEFTUP (SDL_HAT_LEFT|SDL_HAT_UP) 148 #define SDL_HAT_LEFTUP (SDL_HAT_LEFT|SDL_HAT_UP)
136 #define SDL_HAT_LEFTDOWN (SDL_HAT_LEFT|SDL_HAT_DOWN) 149 #define SDL_HAT_LEFTDOWN (SDL_HAT_LEFT|SDL_HAT_DOWN)
137 /* 150 /*@}*/
138 * The hat indices start at index 0. 151
152 /**
153 * Get the current state of a POV hat on a joystick
154 *
155 * @param[in] hat The hat indices start at index 0.
139 */ 156 */
140 extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetHat(SDL_Joystick *joystick, int hat); 157 extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetHat(SDL_Joystick *joystick, int hat);
141 158
142 /* 159 /**
143 * Get the ball axis change since the last poll 160 * Get the ball axis change since the last poll
144 * This returns 0, or -1 if you passed it invalid parameters. 161 *
145 * The ball indices start at index 0. 162 * @param[in] ball The ball indices start at index 0.
163 *
164 * @return This returns 0, or -1 if you passed it invalid parameters.
146 */ 165 */
147 extern DECLSPEC int SDLCALL SDL_JoystickGetBall(SDL_Joystick *joystick, int ball, int *dx, int *dy); 166 extern DECLSPEC int SDLCALL SDL_JoystickGetBall(SDL_Joystick *joystick, int ball, int *dx, int *dy);
148 167
149 /* 168 /**
150 * Get the current state of a button on a joystick 169 * Get the current state of a button on a joystick
151 * The button indices start at index 0. 170 *
171 * @param[in] button The button indices start at index 0.
152 */ 172 */
153 extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetButton(SDL_Joystick *joystick, int button); 173 extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetButton(SDL_Joystick *joystick, int button);
154 174
155 /* 175 /**
156 * Close a joystick previously opened with SDL_JoystickOpen() 176 * Close a joystick previously opened with SDL_JoystickOpen()
157 */ 177 */
158 extern DECLSPEC void SDLCALL SDL_JoystickClose(SDL_Joystick *joystick); 178 extern DECLSPEC void SDLCALL SDL_JoystickClose(SDL_Joystick *joystick);
159 179
160 180