Mercurial > sdl-ios-xcode
comparison include/SDL_joystick.h @ 3407:d3baf5ac4e37
Partial fix for bug #859
Header file update from Ken for improved doxygen output
author | Sam Lantinga <slouken@libsdl.org> |
---|---|
date | Mon, 19 Oct 2009 13:31:58 +0000 |
parents | 99210400e8b9 |
children | f7b03b6838cb |
comparison
equal
deleted
inserted
replaced
3406:8ae607392409 | 3407:d3baf5ac4e37 |
---|---|
19 Sam Lantinga | 19 Sam Lantinga |
20 slouken@libsdl.org | 20 slouken@libsdl.org |
21 */ | 21 */ |
22 | 22 |
23 /** | 23 /** |
24 * \file SDL_joystick.h | 24 * \file SDL_joystick.h |
25 * | 25 * |
26 * Include file for SDL joystick event handling | 26 * Include file for SDL joystick event handling |
27 */ | 27 */ |
28 | 28 |
29 #ifndef _SDL_joystick_h | 29 #ifndef _SDL_joystick_h |
30 #define _SDL_joystick_h | 30 #define _SDL_joystick_h |
31 | 31 |
38 /* *INDENT-OFF* */ | 38 /* *INDENT-OFF* */ |
39 extern "C" { | 39 extern "C" { |
40 /* *INDENT-ON* */ | 40 /* *INDENT-ON* */ |
41 #endif | 41 #endif |
42 | 42 |
43 /* In order to use these functions, SDL_Init() must have been called | 43 /** |
44 with the SDL_INIT_JOYSTICK flag. This causes SDL to scan the system | 44 * \file SDL_joystick.h |
45 for joysticks, and load appropriate drivers. | 45 * |
46 */ | 46 * In order to use these functions, SDL_Init() must have been called |
47 * with the ::SDL_INIT_JOYSTICK flag. This causes SDL to scan the system | |
48 * for joysticks, and load appropriate drivers. | |
49 */ | |
47 | 50 |
48 /* The joystick structure used to identify an SDL joystick */ | 51 /* The joystick structure used to identify an SDL joystick */ |
49 struct _SDL_Joystick; | 52 struct _SDL_Joystick; |
50 typedef struct _SDL_Joystick SDL_Joystick; | 53 typedef struct _SDL_Joystick SDL_Joystick; |
51 | 54 |
52 | 55 |
53 /* Function prototypes */ | 56 /* Function prototypes */ |
54 /* | 57 /** |
55 * Count the number of joysticks attached to the system | 58 * Count the number of joysticks attached to the system |
56 */ | 59 */ |
57 extern DECLSPEC int SDLCALL SDL_NumJoysticks(void); | 60 extern DECLSPEC int SDLCALL SDL_NumJoysticks(void); |
58 | 61 |
59 /* | 62 /** |
60 * Get the implementation dependent name of a joystick. | 63 * Get the implementation dependent name of a joystick. |
61 * This can be called before any joysticks are opened. | 64 * This can be called before any joysticks are opened. |
62 * If no name can be found, this function returns NULL. | 65 * If no name can be found, this function returns NULL. |
63 */ | 66 */ |
64 extern DECLSPEC const char *SDLCALL SDL_JoystickName(int device_index); | 67 extern DECLSPEC const char *SDLCALL SDL_JoystickName(int device_index); |
65 | 68 |
66 /* | 69 /** |
67 * Open a joystick for use - the index passed as an argument refers to | 70 * Open a joystick for use. |
68 * the N'th joystick on the system. This index is the value which will | 71 * The index passed as an argument refers tothe N'th joystick on the system. |
69 * identify this joystick in future joystick events. | 72 * This index is the value which will identify this joystick in future joystick |
70 * | 73 * events. |
71 * This function returns a joystick identifier, or NULL if an error occurred. | 74 * |
75 * \return A joystick identifier, or NULL if an error occurred. | |
72 */ | 76 */ |
73 extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickOpen(int device_index); | 77 extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickOpen(int device_index); |
74 | 78 |
75 /* | 79 /** |
76 * Returns 1 if the joystick has been opened, or 0 if it has not. | 80 * Returns 1 if the joystick has been opened, or 0 if it has not. |
77 */ | 81 */ |
78 extern DECLSPEC int SDLCALL SDL_JoystickOpened(int device_index); | 82 extern DECLSPEC int SDLCALL SDL_JoystickOpened(int device_index); |
79 | 83 |
80 /* | 84 /** |
81 * Get the device index of an opened joystick. | 85 * Get the device index of an opened joystick. |
82 */ | 86 */ |
83 extern DECLSPEC int SDLCALL SDL_JoystickIndex(SDL_Joystick * joystick); | 87 extern DECLSPEC int SDLCALL SDL_JoystickIndex(SDL_Joystick * joystick); |
84 | 88 |
85 /* | 89 /** |
86 * Get the number of general axis controls on a joystick | 90 * Get the number of general axis controls on a joystick. |
87 */ | 91 */ |
88 extern DECLSPEC int SDLCALL SDL_JoystickNumAxes(SDL_Joystick * joystick); | 92 extern DECLSPEC int SDLCALL SDL_JoystickNumAxes(SDL_Joystick * joystick); |
89 | 93 |
90 /* | 94 /** |
91 * Get the number of trackballs on a joystick | 95 * Get the number of trackballs on a joystick. |
92 * Joystick trackballs have only relative motion events associated | 96 * |
93 * with them and their state cannot be polled. | 97 * Joystick trackballs have only relative motion events associated |
98 * with them and their state cannot be polled. | |
94 */ | 99 */ |
95 extern DECLSPEC int SDLCALL SDL_JoystickNumBalls(SDL_Joystick * joystick); | 100 extern DECLSPEC int SDLCALL SDL_JoystickNumBalls(SDL_Joystick * joystick); |
96 | 101 |
97 /* | 102 /** |
98 * Get the number of POV hats on a joystick | 103 * Get the number of POV hats on a joystick. |
99 */ | 104 */ |
100 extern DECLSPEC int SDLCALL SDL_JoystickNumHats(SDL_Joystick * joystick); | 105 extern DECLSPEC int SDLCALL SDL_JoystickNumHats(SDL_Joystick * joystick); |
101 | 106 |
102 /* | 107 /** |
103 * Get the number of buttons on a joystick | 108 * Get the number of buttons on a joystick. |
104 */ | 109 */ |
105 extern DECLSPEC int SDLCALL SDL_JoystickNumButtons(SDL_Joystick * joystick); | 110 extern DECLSPEC int SDLCALL SDL_JoystickNumButtons(SDL_Joystick * joystick); |
106 | 111 |
107 /* | 112 /** |
108 * Update the current state of the open joysticks. | 113 * Update the current state of the open joysticks. |
109 * This is called automatically by the event loop if any joystick | 114 * |
110 * events are enabled. | 115 * This is called automatically by the event loop if any joystick |
116 * events are enabled. | |
111 */ | 117 */ |
112 extern DECLSPEC void SDLCALL SDL_JoystickUpdate(void); | 118 extern DECLSPEC void SDLCALL SDL_JoystickUpdate(void); |
113 | 119 |
114 /* | 120 /** |
115 * Enable/disable joystick event polling. | 121 * Enable/disable joystick event polling. |
116 * If joystick events are disabled, you must call SDL_JoystickUpdate() | 122 * |
117 * yourself and check the state of the joystick when you want joystick | 123 * If joystick events are disabled, you must call SDL_JoystickUpdate() |
118 * information. | 124 * yourself and check the state of the joystick when you want joystick |
119 * The state can be one of SDL_QUERY, SDL_ENABLE or SDL_IGNORE. | 125 * information. |
126 * | |
127 * The state can be one of ::SDL_QUERY, ::SDL_ENABLE or ::SDL_IGNORE. | |
120 */ | 128 */ |
121 extern DECLSPEC int SDLCALL SDL_JoystickEventState(int state); | 129 extern DECLSPEC int SDLCALL SDL_JoystickEventState(int state); |
122 | 130 |
123 /* | 131 /** |
124 * Get the current state of an axis control on a joystick | 132 * Get the current state of an axis control on a joystick. |
125 * The state is a value ranging from -32768 to 32767. | 133 * |
126 * The axis indices start at index 0. | 134 * The state is a value ranging from -32768 to 32767. |
135 * | |
136 * The axis indices start at index 0. | |
127 */ | 137 */ |
128 extern DECLSPEC Sint16 SDLCALL SDL_JoystickGetAxis(SDL_Joystick * joystick, | 138 extern DECLSPEC Sint16 SDLCALL SDL_JoystickGetAxis(SDL_Joystick * joystick, |
129 int axis); | 139 int axis); |
130 | 140 |
131 /* | 141 /** |
132 * Get the current state of a POV hat on a joystick | 142 * \name Hat positions |
133 * The return value is one of the following positions: | 143 */ |
134 */ | 144 /*@{*/ |
135 #define SDL_HAT_CENTERED 0x00 | 145 #define SDL_HAT_CENTERED 0x00 |
136 #define SDL_HAT_UP 0x01 | 146 #define SDL_HAT_UP 0x01 |
137 #define SDL_HAT_RIGHT 0x02 | 147 #define SDL_HAT_RIGHT 0x02 |
138 #define SDL_HAT_DOWN 0x04 | 148 #define SDL_HAT_DOWN 0x04 |
139 #define SDL_HAT_LEFT 0x08 | 149 #define SDL_HAT_LEFT 0x08 |
140 #define SDL_HAT_RIGHTUP (SDL_HAT_RIGHT|SDL_HAT_UP) | 150 #define SDL_HAT_RIGHTUP (SDL_HAT_RIGHT|SDL_HAT_UP) |
141 #define SDL_HAT_RIGHTDOWN (SDL_HAT_RIGHT|SDL_HAT_DOWN) | 151 #define SDL_HAT_RIGHTDOWN (SDL_HAT_RIGHT|SDL_HAT_DOWN) |
142 #define SDL_HAT_LEFTUP (SDL_HAT_LEFT|SDL_HAT_UP) | 152 #define SDL_HAT_LEFTUP (SDL_HAT_LEFT|SDL_HAT_UP) |
143 #define SDL_HAT_LEFTDOWN (SDL_HAT_LEFT|SDL_HAT_DOWN) | 153 #define SDL_HAT_LEFTDOWN (SDL_HAT_LEFT|SDL_HAT_DOWN) |
144 /* | 154 /*@}*/ |
145 * The hat indices start at index 0. | 155 |
156 /** | |
157 * Get the current state of a POV hat on a joystick. | |
158 * | |
159 * The hat indices start at index 0. | |
160 * | |
161 * \return The return value is one of the following positions: | |
162 * - ::SDL_HAT_CENTERED | |
163 * - ::SDL_HAT_UP | |
164 * - ::SDL_HAT_RIGHT | |
165 * - ::SDL_HAT_DOWN | |
166 * - ::SDL_HAT_LEFT | |
167 * - ::SDL_HAT_RIGHTUP | |
168 * - ::SDL_HAT_RIGHTDOWN | |
169 * - ::SDL_HAT_LEFTUP | |
170 * - ::SDL_HAT_LEFTDOWN | |
146 */ | 171 */ |
147 extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetHat(SDL_Joystick * joystick, | 172 extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetHat(SDL_Joystick * joystick, |
148 int hat); | 173 int hat); |
149 | 174 |
150 /* | 175 /** |
151 * Get the ball axis change since the last poll | 176 * Get the ball axis change since the last poll. |
152 * This returns 0, or -1 if you passed it invalid parameters. | 177 * |
153 * The ball indices start at index 0. | 178 * \return 0, or -1 if you passed it invalid parameters. |
179 * | |
180 * The ball indices start at index 0. | |
154 */ | 181 */ |
155 extern DECLSPEC int SDLCALL SDL_JoystickGetBall(SDL_Joystick * joystick, | 182 extern DECLSPEC int SDLCALL SDL_JoystickGetBall(SDL_Joystick * joystick, |
156 int ball, int *dx, int *dy); | 183 int ball, int *dx, int *dy); |
157 | 184 |
158 /* | 185 /** |
159 * Get the current state of a button on a joystick | 186 * Get the current state of a button on a joystick. |
160 * The button indices start at index 0. | 187 * |
188 * The button indices start at index 0. | |
161 */ | 189 */ |
162 extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetButton(SDL_Joystick * joystick, | 190 extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetButton(SDL_Joystick * joystick, |
163 int button); | 191 int button); |
164 | 192 |
165 /* | 193 /** |
166 * Close a joystick previously opened with SDL_JoystickOpen() | 194 * Close a joystick previously opened with SDL_JoystickOpen(). |
167 */ | 195 */ |
168 extern DECLSPEC void SDLCALL SDL_JoystickClose(SDL_Joystick * joystick); | 196 extern DECLSPEC void SDLCALL SDL_JoystickClose(SDL_Joystick * joystick); |
169 | 197 |
170 | 198 |
171 /* Ends C function definitions when using C++ */ | 199 /* Ends C function definitions when using C++ */ |