Mercurial > sdl-ios-xcode

comparison include/SDL_mouse.h @ 3407:d3baf5ac4e37

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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 f8816ffa210b
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_mouse.h 24 * \file SDL_mouse.h
25 * 25 *
26 * Include file for SDL mouse event handling 26 * Include file for SDL mouse event handling.
27 */ 27 */
28 28
29 #ifndef _SDL_mouse_h 29 #ifndef _SDL_mouse_h
30 #define _SDL_mouse_h 30 #define _SDL_mouse_h
31 31
44 typedef struct SDL_Cursor SDL_Cursor; /* Implementation dependent */ 44 typedef struct SDL_Cursor SDL_Cursor; /* Implementation dependent */
45 45
46 /* Function prototypes */ 46 /* Function prototypes */
47 47
48 /** 48 /**
49 * \fn int SDL_GetNumMice(void) 49 * \brief Get the number of mouse input devices available.
50 * 50 *
51 * \brief Get the number of mouse input devices available. 51 * \sa SDL_SelectMouse()
52 *
53 * \sa SDL_SelectMouse()
54 */ 52 */
55 extern DECLSPEC int SDLCALL SDL_GetNumMice(void); 53 extern DECLSPEC int SDLCALL SDL_GetNumMice(void);
56 54
57 /** 55 /**
58 * \fn char* SDL_GetMouseName(int index) 56 * \brief Gets the name of a mouse with the given index.
59 * 57 *
60 * \brief Gets the name of a mouse with the given index. 58 * \param index is the index of the mouse, which name is to be returned.
61 * 59 *
62 * \param index is the index of the mouse, which name is to be returned. 60 * \return the name of the mouse with the specified index
63 *
64 * \return the name of the mouse with the specified index
65 */ 61 */
66 extern DECLSPEC char *SDLCALL SDL_GetMouseName(int index); 62 extern DECLSPEC char *SDLCALL SDL_GetMouseName(int index);
67 63
68 /** 64 /**
69 * \fn int SDL_SelectMouse(int index) 65 * \brief Set the index of the currently selected mouse.
70 * 66 *
71 * \brief Set the index of the currently selected mouse. 67 * \return The index of the previously selected mouse.
72 * 68 *
73 * \return The index of the previously selected mouse. 69 * \note You can query the currently selected mouse by passing an index of -1.
74 * 70 *
75 * \note You can query the currently selected mouse by passing an index of -1. 71 * \sa SDL_GetNumMice()
76 *
77 * \sa SDL_GetNumMice()
78 */ 72 */
79 extern DECLSPEC int SDLCALL SDL_SelectMouse(int index); 73 extern DECLSPEC int SDLCALL SDL_SelectMouse(int index);
80 74
81 /** 75 /**
82 * \fn SDL_WindowID SDL_GetMouseFocusWindow(int index) 76 * \brief Get the window which currently has focus for the specified mouse.
83 *
84 * \brief Get the window which currently has focus for the currently selected mouse.
85 */ 77 */
86 extern DECLSPEC SDL_WindowID SDLCALL SDL_GetMouseFocusWindow(int index); 78 extern DECLSPEC SDL_WindowID SDLCALL SDL_GetMouseFocusWindow(int index);
87 79
88 /** 80 /**
89 * \fn int SDL_SetRelativeMouseMode(int index, SDL_bool enabled) 81 * \brief Set relative mouse mode for the specified mouse.
90 * 82 *
91 * \brief Set relative mouse mode for the currently selected mouse. 83 * \param enabled Whether or not to enable relative mode
92 * 84 *
93 * \param enabled Whether or not to enable relative mode 85 * \return 0 on success, or -1 if relative mode is not supported.
94 * 86 *
95 * \return 0 on success, or -1 if relative mode is not supported. 87 * While the mouse is in relative mode, the cursor is hidden, and the
96 * 88 * driver will try to report continuous motion in the current window.
97 * While the mouse is in relative mode, the cursor is hidden, and the 89 * Only relative motion events will be delivered, the mouse position
98 * driver will try to report continuous motion in the current window. 90 * will not change.
99 * Only relative motion events will be delivered, the mouse position 91 *
100 * will not change. 92 * \note This function will flush any pending mouse motion.
101 * 93 *
102 * \note This function will flush any pending mouse motion. 94 * \sa SDL_GetRelativeMouseMode()
103 *
104 * \sa SDL_GetRelativeMouseMode()
105 */ 95 */
106 extern DECLSPEC int SDLCALL SDL_SetRelativeMouseMode(int index, 96 extern DECLSPEC int SDLCALL SDL_SetRelativeMouseMode(int index,
107 SDL_bool enabled); 97 SDL_bool enabled);
108 98
109 /** 99 /**
110 * \fn SDL_bool SDL_GetRelativeMouseMode(int index) 100 * \brief Query whether relative mouse mode is enabled for the specified mouse.
101 *
102 * \sa SDL_SetRelativeMouseMode()
103 */
104 extern DECLSPEC SDL_bool SDLCALL SDL_GetRelativeMouseMode(int index);
105
106 /**
107 * \brief Retrieve the current state of the specified mouse.
108 *
109 * The current button state is returned as a button bitmask, which can
110 * be tested using the SDL_BUTTON(X) macros, and x and y are set to the
111 * mouse cursor position relative to the focus window for the currently
112 * selected mouse. You can pass NULL for either x or y.
113 */
114 extern DECLSPEC Uint8 SDLCALL SDL_GetMouseState(int index, int *x, int *y);
115
116 /**
117 * \brief Retrieve the state of the specified mouse.
111 * 118 *
112 * \brief Query whether relative mouse mode is enabled for the currently selected mouse. 119 * The current button state is returned as a button bitmask, which can
113 * 120 * be tested using the SDL_BUTTON(X) macros, and x and y are set to the
114 * \sa SDL_SetRelativeMouseMode() 121 * mouse deltas since the last call to SDL_GetRelativeMouseState().
115 */
116 extern DECLSPEC SDL_bool SDLCALL SDL_GetRelativeMouseMode(int index);
117
118 /**
119 * \fn Uint8 SDL_GetMouseState(int index, int *x, int *y)
120 *
121 * \brief Retrieve the current state of the currently selected mouse.
122 *
123 * The current button state is returned as a button bitmask, which can
124 * be tested using the SDL_BUTTON(X) macros, and x and y are set to the
125 * mouse cursor position relative to the focus window for the currently
126 * selected mouse. You can pass NULL for either x or y.
127 */
128 extern DECLSPEC Uint8 SDLCALL SDL_GetMouseState(int index, int *x, int *y);
129
130 /**
131 * \fn Uint8 SDL_GetRelativeMouseState(int index, int *x, int *y)
132 *
133 * \brief Retrieve the state of the currently selected mouse.
134 *
135 * The current button state is returned as a button bitmask, which can
136 * be tested using the SDL_BUTTON(X) macros, and x and y are set to the
137 * mouse deltas since the last call to SDL_GetRelativeMouseState().
138 */ 122 */
139 extern DECLSPEC Uint8 SDLCALL SDL_GetRelativeMouseState(int index, int *x, 123 extern DECLSPEC Uint8 SDLCALL SDL_GetRelativeMouseState(int index, int *x,
140 int *y); 124 int *y);
141 125
142 /** 126 /**
143 * \fn void SDL_WarpMouseInWindow(SDL_WindowID windowID, int x, int y) 127 * \brief Moves the currently selected mouse to the given position within the window.
144 * 128 *
145 * \brief Moves the currently selected mouse to the given position within the window. 129 * \param windowID The window to move the mouse into, or 0 for the current mouse focus
146 * 130 * \param x The x coordinate within the window
147 * \param windowID The window to move the mouse into, or 0 for the current mouse focus 131 * \param y The y coordinate within the window
148 * \param x The x coordinate within the window 132 *
149 * \param y The y coordinate within the window 133 * \note This function generates a mouse motion event
150 *
151 * \note This function generates a mouse motion event
152 */ 134 */
153 extern DECLSPEC void SDLCALL SDL_WarpMouseInWindow(SDL_WindowID windowID, 135 extern DECLSPEC void SDLCALL SDL_WarpMouseInWindow(SDL_WindowID windowID,
154 int x, int y); 136 int x, int y);
155 137
156 /** 138 /**
157 * \fn SDL_Cursor *SDL_CreateCursor (const Uint8 * data, const Uint8 * mask, int w, int h, int hot_x, int hot_y) 139 * \brief Create a cursor for the currently selected mouse, using the
158 * 140 * specified bitmap data and mask (in MSB format).
159 * \brief Create a cursor for the currently selected mouse, using the 141 *
160 * specified bitmap data and mask (in MSB format). 142 * The cursor width must be a multiple of 8 bits.
161 * 143 *
162 * The cursor width must be a multiple of 8 bits. 144 * The cursor is created in black and white according to the following:
163 * 145 * <table>
164 * The cursor is created in black and white according to the following: 146 * <tr><td> data </td><td> mask </td><td> resulting pixel on screen </td></tr>
165 * data mask resulting pixel on screen 147 * <tr><td> 0 </td><td> 1 </td><td> White </td></tr>
166 * 0 1 White 148 * <tr><td> 1 </td><td> 1 </td><td> Black </td></tr>
167 * 1 1 Black 149 * <tr><td> 0 </td><td> 0 </td><td> Transparent </td></tr>
168 * 0 0 Transparent 150 * <tr><td> 1 </td><td> 0 </td><td> Inverted color if possible, black
169 * 1 0 Inverted color if possible, black if not. 151 if not. </td></tr>
170 * 152 * </table>
171 * \sa SDL_FreeCursor() 153 *
154 * \sa SDL_FreeCursor()
172 */ 155 */
173 extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateCursor(const Uint8 * data, 156 extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateCursor(const Uint8 * data,
174 const Uint8 * mask, 157 const Uint8 * mask,
175 int w, int h, int hot_x, 158 int w, int h, int hot_x,
176 int hot_y); 159 int hot_y);
177 160
178 /** 161 /**
179 * \fn void SDL_SetCursor(SDL_Cursor * cursor) 162 * \brief Set the active cursor for the currently selected mouse.
180 * 163 *
181 * \brief Set the active cursor for the currently selected mouse. 164 * \note The cursor must have been created for the selected mouse.
182 *
183 * \note The cursor must have been created for the selected mouse.
184 */ 165 */
185 extern DECLSPEC void SDLCALL SDL_SetCursor(SDL_Cursor * cursor); 166 extern DECLSPEC void SDLCALL SDL_SetCursor(SDL_Cursor * cursor);
186 167
187 /** 168 /**
188 * \fn SDL_Cursor *SDL_GetCursor(void) 169 * \brief Return the active cursor for the currently selected mouse.
189 *
190 * \brief Return the active cursor for the currently selected mouse.
191 */ 170 */
192 extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetCursor(void); 171 extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetCursor(void);
193 172
194 /** 173 /**
195 * \fn void SDL_FreeCursor(SDL_Cursor * cursor) 174 * \brief Frees a cursor created with SDL_CreateCursor().
196 * 175 *
197 * \brief Frees a cursor created with SDL_CreateCursor(). 176 * \sa SDL_CreateCursor()
198 *
199 * \sa SDL_CreateCursor()
200 */ 177 */
201 extern DECLSPEC void SDLCALL SDL_FreeCursor(SDL_Cursor * cursor); 178 extern DECLSPEC void SDLCALL SDL_FreeCursor(SDL_Cursor * cursor);
202 179
203 /** 180 /**
204 * \fn int SDL_ShowCursor(int toggle) 181 * \brief Toggle whether or not the cursor is shown for the currently selected
205 * 182 * mouse.
206 * \brief Toggle whether or not the cursor is shown for the currently selected mouse. 183 *
207 * 184 * \param toggle 1 to show the cursor, 0 to hide it, -1 to query the current
208 * \param toggle 1 to show the cursor, 0 to hide it, -1 to query the current state. 185 * state.
209 * 186 *
210 * \return 1 if the cursor is shown, or 0 if the cursor is hidden. 187 * \return 1 if the cursor is shown, or 0 if the cursor is hidden.
211 */ 188 */
212 extern DECLSPEC int SDLCALL SDL_ShowCursor(int toggle); 189 extern DECLSPEC int SDLCALL SDL_ShowCursor(int toggle);
213 190
214 /* Used as a mask when testing buttons in buttonstate 191 /**
215 Button 1: Left mouse button 192 * \brief Gets the number of cursors a pointing device supports.
216 Button 2: Middle mouse button 193 *
217 Button 3: Right mouse button 194 * Useful for tablet users. Useful only under Windows.
218 */ 195 *
219 196 * \param index is the index of the pointing device, which number of cursors we
220 /** 197 * want to receive.
221 * \fn int SDL_GetCursorsNumber(int index) 198 *
222 * 199 * \return the number of cursors supported by the pointing device. On Windows
223 * \brief Gets the number of cursors a pointing device supports. 200 * if a device is a tablet it returns a number >=1. Normal mice always
224 * Useful for tablet users. Useful only under Windows. 201 * return 1.
225 * 202 *
226 * \param index is the index of the pointing device, which number of cursors we 203 * On Linux every device reports one cursor.
227 * want to receive.
228 *
229 * \return the number of cursors supported by the pointing device. On Windows
230 * if a device is a tablet it returns a number >=1. Normal mice always return 1.
231 * On Linux every device reports one cursor.
232 */ 204 */
233 extern DECLSPEC int SDLCALL SDL_GetCursorsNumber(int index); 205 extern DECLSPEC int SDLCALL SDL_GetCursorsNumber(int index);
234 206
235 /** 207 /**
236 * \fn int SDL_GetCurrentCursor(int index) 208 * \brief Returns the index of the current cursor used by a specific pointing
237 * 209 * device.
238 * \brief Returns the index of the current cursor used by a specific pointing 210 *
239 * device. Useful only under Windows. 211 * Useful only under Windows.
240 * 212 *
241 * \param index is the index of the pointing device, which cursor index we want 213 * \param index is the index of the pointing device, which cursor index we want
242 * to receive. 214 * to receive.
243 * 215 *
244 * \return the index of the cursor currently used by a specific pointing device. 216 * \return the index of the cursor currently used by a specific pointing
245 * Always 0 under Linux. On Windows if the device isn't a tablet it returns 0. 217 * device. Always 0 under Linux. On Windows if the device isn't a
246 * If the device is the tablet it returns the cursor index. 218 * tablet it returns 0. If the device is the tablet it returns the
247 * 0 - stylus, 1 - eraser, 2 - cursor. 219 * cursor index. 0 - stylus, 1 - eraser, 2 - cursor.
248 */ 220 */
249 extern DECLSPEC int SDLCALL SDL_GetCurrentCursor(int index); 221 extern DECLSPEC int SDLCALL SDL_GetCurrentCursor(int index);
250 222
223 /**
224 * Used as a mask when testing buttons in buttonstate.
225 * - Button 1: Left mouse button
226 * - Button 2: Middle mouse button
227 * - Button 3: Right mouse button
228 */
251 #define SDL_BUTTON(X) (1 << ((X)-1)) 229 #define SDL_BUTTON(X) (1 << ((X)-1))
252 #define SDL_BUTTON_LEFT 1 230 #define SDL_BUTTON_LEFT 1
253 #define SDL_BUTTON_MIDDLE 2 231 #define SDL_BUTTON_MIDDLE 2
254 #define SDL_BUTTON_RIGHT 3 232 #define SDL_BUTTON_RIGHT 3
255 #define SDL_BUTTON_X1 4 233 #define SDL_BUTTON_X1 4