source: trunk/external/sdl-1.2.15/include/SDL_events.h @ 2214

Last change on this file since 2214 was 1586, checked in by sam, 9 years ago

build: update Windows SDL binaries to 1.2.15.

File size: 12.7 KB
Line 
1/*
2    SDL - Simple DirectMedia Layer
3    Copyright (C) 1997-2012 Sam Lantinga
4
5    This library is free software; you can redistribute it and/or
6    modify it under the terms of the GNU Lesser General Public
7    License as published by the Free Software Foundation; either
8    version 2.1 of the License, or (at your option) any later version.
9
10    This library is distributed in the hope that it will be useful,
11    but WITHOUT ANY WARRANTY; without even the implied warranty of
12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13    Lesser General Public License for more details.
14
15    You should have received a copy of the GNU Lesser General Public
16    License along with this library; if not, write to the Free Software
17    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
18
19    Sam Lantinga
20    slouken@libsdl.org
21*/
22
23/**
24 *  @file SDL_events.h
25 *  Include file for SDL event handling
26 */
27
28#ifndef _SDL_events_h
29#define _SDL_events_h
30
31#include "SDL_stdinc.h"
32#include "SDL_error.h"
33#include "SDL_active.h"
34#include "SDL_keyboard.h"
35#include "SDL_mouse.h"
36#include "SDL_joystick.h"
37#include "SDL_quit.h"
38
39#include "begin_code.h"
40/* Set up for C function definitions, even when using C++ */
41#ifdef __cplusplus
42extern "C" {
43#endif
44
45/** @name General keyboard/mouse state definitions */
46/*@{*/
47#define SDL_RELEASED    0
48#define SDL_PRESSED     1
49/*@}*/
50
51/** Event enumerations */
52typedef enum {
53       SDL_NOEVENT = 0,                 /**< Unused (do not remove) */
54       SDL_ACTIVEEVENT,                 /**< Application loses/gains visibility */
55       SDL_KEYDOWN,                     /**< Keys pressed */
56       SDL_KEYUP,                       /**< Keys released */
57       SDL_MOUSEMOTION,                 /**< Mouse moved */
58       SDL_MOUSEBUTTONDOWN,             /**< Mouse button pressed */
59       SDL_MOUSEBUTTONUP,               /**< Mouse button released */
60       SDL_JOYAXISMOTION,               /**< Joystick axis motion */
61       SDL_JOYBALLMOTION,               /**< Joystick trackball motion */
62       SDL_JOYHATMOTION,                /**< Joystick hat position change */
63       SDL_JOYBUTTONDOWN,               /**< Joystick button pressed */
64       SDL_JOYBUTTONUP,                 /**< Joystick button released */
65       SDL_QUIT,                        /**< User-requested quit */
66       SDL_SYSWMEVENT,                  /**< System specific event */
67       SDL_EVENT_RESERVEDA,             /**< Reserved for future use.. */
68       SDL_EVENT_RESERVEDB,             /**< Reserved for future use.. */
69       SDL_VIDEORESIZE,                 /**< User resized video mode */
70       SDL_VIDEOEXPOSE,                 /**< Screen needs to be redrawn */
71       SDL_EVENT_RESERVED2,             /**< Reserved for future use.. */
72       SDL_EVENT_RESERVED3,             /**< Reserved for future use.. */
73       SDL_EVENT_RESERVED4,             /**< Reserved for future use.. */
74       SDL_EVENT_RESERVED5,             /**< Reserved for future use.. */
75       SDL_EVENT_RESERVED6,             /**< Reserved for future use.. */
76       SDL_EVENT_RESERVED7,             /**< Reserved for future use.. */
77       /** Events SDL_USEREVENT through SDL_MAXEVENTS-1 are for your use */
78       SDL_USEREVENT = 24,
79       /** This last event is only for bounding internal arrays
80        *  It is the number of bits in the event mask datatype -- Uint32
81        */
82       SDL_NUMEVENTS = 32
83} SDL_EventType;
84
85/** @name Predefined event masks */
86/*@{*/
87#define SDL_EVENTMASK(X)        (1<<(X))
88typedef enum {
89        SDL_ACTIVEEVENTMASK     = SDL_EVENTMASK(SDL_ACTIVEEVENT),
90        SDL_KEYDOWNMASK         = SDL_EVENTMASK(SDL_KEYDOWN),
91        SDL_KEYUPMASK           = SDL_EVENTMASK(SDL_KEYUP),
92        SDL_KEYEVENTMASK        = SDL_EVENTMASK(SDL_KEYDOWN)|
93                                  SDL_EVENTMASK(SDL_KEYUP),
94        SDL_MOUSEMOTIONMASK     = SDL_EVENTMASK(SDL_MOUSEMOTION),
95        SDL_MOUSEBUTTONDOWNMASK = SDL_EVENTMASK(SDL_MOUSEBUTTONDOWN),
96        SDL_MOUSEBUTTONUPMASK   = SDL_EVENTMASK(SDL_MOUSEBUTTONUP),
97        SDL_MOUSEEVENTMASK      = SDL_EVENTMASK(SDL_MOUSEMOTION)|
98                                  SDL_EVENTMASK(SDL_MOUSEBUTTONDOWN)|
99                                  SDL_EVENTMASK(SDL_MOUSEBUTTONUP),
100        SDL_JOYAXISMOTIONMASK   = SDL_EVENTMASK(SDL_JOYAXISMOTION),
101        SDL_JOYBALLMOTIONMASK   = SDL_EVENTMASK(SDL_JOYBALLMOTION),
102        SDL_JOYHATMOTIONMASK    = SDL_EVENTMASK(SDL_JOYHATMOTION),
103        SDL_JOYBUTTONDOWNMASK   = SDL_EVENTMASK(SDL_JOYBUTTONDOWN),
104        SDL_JOYBUTTONUPMASK     = SDL_EVENTMASK(SDL_JOYBUTTONUP),
105        SDL_JOYEVENTMASK        = SDL_EVENTMASK(SDL_JOYAXISMOTION)|
106                                  SDL_EVENTMASK(SDL_JOYBALLMOTION)|
107                                  SDL_EVENTMASK(SDL_JOYHATMOTION)|
108                                  SDL_EVENTMASK(SDL_JOYBUTTONDOWN)|
109                                  SDL_EVENTMASK(SDL_JOYBUTTONUP),
110        SDL_VIDEORESIZEMASK     = SDL_EVENTMASK(SDL_VIDEORESIZE),
111        SDL_VIDEOEXPOSEMASK     = SDL_EVENTMASK(SDL_VIDEOEXPOSE),
112        SDL_QUITMASK            = SDL_EVENTMASK(SDL_QUIT),
113        SDL_SYSWMEVENTMASK      = SDL_EVENTMASK(SDL_SYSWMEVENT)
114} SDL_EventMask ;
115#define SDL_ALLEVENTS           0xFFFFFFFF
116/*@}*/
117
118/** Application visibility event structure */
119typedef struct SDL_ActiveEvent {
120        Uint8 type;     /**< SDL_ACTIVEEVENT */
121        Uint8 gain;     /**< Whether given states were gained or lost (1/0) */
122        Uint8 state;    /**< A mask of the focus states */
123} SDL_ActiveEvent;
124
125/** Keyboard event structure */
126typedef struct SDL_KeyboardEvent {
127        Uint8 type;     /**< SDL_KEYDOWN or SDL_KEYUP */
128        Uint8 which;    /**< The keyboard device index */
129        Uint8 state;    /**< SDL_PRESSED or SDL_RELEASED */
130        SDL_keysym keysym;
131} SDL_KeyboardEvent;
132
133/** Mouse motion event structure */
134typedef struct SDL_MouseMotionEvent {
135        Uint8 type;     /**< SDL_MOUSEMOTION */
136        Uint8 which;    /**< The mouse device index */
137        Uint8 state;    /**< The current button state */
138        Uint16 x, y;    /**< The X/Y coordinates of the mouse */
139        Sint16 xrel;    /**< The relative motion in the X direction */
140        Sint16 yrel;    /**< The relative motion in the Y direction */
141} SDL_MouseMotionEvent;
142
143/** Mouse button event structure */
144typedef struct SDL_MouseButtonEvent {
145        Uint8 type;     /**< SDL_MOUSEBUTTONDOWN or SDL_MOUSEBUTTONUP */
146        Uint8 which;    /**< The mouse device index */
147        Uint8 button;   /**< The mouse button index */
148        Uint8 state;    /**< SDL_PRESSED or SDL_RELEASED */
149        Uint16 x, y;    /**< The X/Y coordinates of the mouse at press time */
150} SDL_MouseButtonEvent;
151
152/** Joystick axis motion event structure */
153typedef struct SDL_JoyAxisEvent {
154        Uint8 type;     /**< SDL_JOYAXISMOTION */
155        Uint8 which;    /**< The joystick device index */
156        Uint8 axis;     /**< The joystick axis index */
157        Sint16 value;   /**< The axis value (range: -32768 to 32767) */
158} SDL_JoyAxisEvent;
159
160/** Joystick trackball motion event structure */
161typedef struct SDL_JoyBallEvent {
162        Uint8 type;     /**< SDL_JOYBALLMOTION */
163        Uint8 which;    /**< The joystick device index */
164        Uint8 ball;     /**< The joystick trackball index */
165        Sint16 xrel;    /**< The relative motion in the X direction */
166        Sint16 yrel;    /**< The relative motion in the Y direction */
167} SDL_JoyBallEvent;
168
169/** Joystick hat position change event structure */
170typedef struct SDL_JoyHatEvent {
171        Uint8 type;     /**< SDL_JOYHATMOTION */
172        Uint8 which;    /**< The joystick device index */
173        Uint8 hat;      /**< The joystick hat index */
174        Uint8 value;    /**< The hat position value:
175                         *   SDL_HAT_LEFTUP   SDL_HAT_UP       SDL_HAT_RIGHTUP
176                         *   SDL_HAT_LEFT     SDL_HAT_CENTERED SDL_HAT_RIGHT
177                         *   SDL_HAT_LEFTDOWN SDL_HAT_DOWN     SDL_HAT_RIGHTDOWN
178                         *  Note that zero means the POV is centered.
179                         */
180} SDL_JoyHatEvent;
181
182/** Joystick button event structure */
183typedef struct SDL_JoyButtonEvent {
184        Uint8 type;     /**< SDL_JOYBUTTONDOWN or SDL_JOYBUTTONUP */
185        Uint8 which;    /**< The joystick device index */
186        Uint8 button;   /**< The joystick button index */
187        Uint8 state;    /**< SDL_PRESSED or SDL_RELEASED */
188} SDL_JoyButtonEvent;
189
190/** The "window resized" event
191 *  When you get this event, you are responsible for setting a new video
192 *  mode with the new width and height.
193 */
194typedef struct SDL_ResizeEvent {
195        Uint8 type;     /**< SDL_VIDEORESIZE */
196        int w;          /**< New width */
197        int h;          /**< New height */
198} SDL_ResizeEvent;
199
200/** The "screen redraw" event */
201typedef struct SDL_ExposeEvent {
202        Uint8 type;     /**< SDL_VIDEOEXPOSE */
203} SDL_ExposeEvent;
204
205/** The "quit requested" event */
206typedef struct SDL_QuitEvent {
207        Uint8 type;     /**< SDL_QUIT */
208} SDL_QuitEvent;
209
210/** A user-defined event type */
211typedef struct SDL_UserEvent {
212        Uint8 type;     /**< SDL_USEREVENT through SDL_NUMEVENTS-1 */
213        int code;       /**< User defined event code */
214        void *data1;    /**< User defined data pointer */
215        void *data2;    /**< User defined data pointer */
216} SDL_UserEvent;
217
218/** If you want to use this event, you should include SDL_syswm.h */
219struct SDL_SysWMmsg;
220typedef struct SDL_SysWMmsg SDL_SysWMmsg;
221typedef struct SDL_SysWMEvent {
222        Uint8 type;
223        SDL_SysWMmsg *msg;
224} SDL_SysWMEvent;
225
226/** General event structure */
227typedef union SDL_Event {
228        Uint8 type;
229        SDL_ActiveEvent active;
230        SDL_KeyboardEvent key;
231        SDL_MouseMotionEvent motion;
232        SDL_MouseButtonEvent button;
233        SDL_JoyAxisEvent jaxis;
234        SDL_JoyBallEvent jball;
235        SDL_JoyHatEvent jhat;
236        SDL_JoyButtonEvent jbutton;
237        SDL_ResizeEvent resize;
238        SDL_ExposeEvent expose;
239        SDL_QuitEvent quit;
240        SDL_UserEvent user;
241        SDL_SysWMEvent syswm;
242} SDL_Event;
243
244
245/* Function prototypes */
246
247/** Pumps the event loop, gathering events from the input devices.
248 *  This function updates the event queue and internal input device state.
249 *  This should only be run in the thread that sets the video mode.
250 */
251extern DECLSPEC void SDLCALL SDL_PumpEvents(void);
252
253typedef enum {
254        SDL_ADDEVENT,
255        SDL_PEEKEVENT,
256        SDL_GETEVENT
257} SDL_eventaction;
258
259/**
260 *  Checks the event queue for messages and optionally returns them.
261 *
262 *  If 'action' is SDL_ADDEVENT, up to 'numevents' events will be added to
263 *  the back of the event queue.
264 *  If 'action' is SDL_PEEKEVENT, up to 'numevents' events at the front
265 *  of the event queue, matching 'mask', will be returned and will not
266 *  be removed from the queue.
267 *  If 'action' is SDL_GETEVENT, up to 'numevents' events at the front
268 *  of the event queue, matching 'mask', will be returned and will be
269 *  removed from the queue.
270 *
271 *  @return
272 *  This function returns the number of events actually stored, or -1
273 *  if there was an error.
274 *
275 *  This function is thread-safe.
276 */
277extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event *events, int numevents,
278                                SDL_eventaction action, Uint32 mask);
279
280/** Polls for currently pending events, and returns 1 if there are any pending
281 *  events, or 0 if there are none available.  If 'event' is not NULL, the next
282 *  event is removed from the queue and stored in that area.
283 */
284extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event *event);
285
286/** Waits indefinitely for the next available event, returning 1, or 0 if there
287 *  was an error while waiting for events.  If 'event' is not NULL, the next
288 *  event is removed from the queue and stored in that area.
289 */
290extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event *event);
291
292/** Add an event to the event queue.
293 *  This function returns 0 on success, or -1 if the event queue was full
294 *  or there was some other error.
295 */
296extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event *event);
297
298/** @name Event Filtering */
299/*@{*/
300typedef int (SDLCALL *SDL_EventFilter)(const SDL_Event *event);
301/**
302 *  This function sets up a filter to process all events before they
303 *  change internal state and are posted to the internal event queue.
304 *
305 *  The filter is protypted as:
306 *      @code typedef int (SDLCALL *SDL_EventFilter)(const SDL_Event *event); @endcode
307 *
308 * If the filter returns 1, then the event will be added to the internal queue.
309 * If it returns 0, then the event will be dropped from the queue, but the
310 * internal state will still be updated.  This allows selective filtering of
311 * dynamically arriving events.
312 *
313 * @warning  Be very careful of what you do in the event filter function, as
314 *           it may run in a different thread!
315 *
316 * There is one caveat when dealing with the SDL_QUITEVENT event type.  The
317 * event filter is only called when the window manager desires to close the
318 * application window.  If the event filter returns 1, then the window will
319 * be closed, otherwise the window will remain open if possible.
320 * If the quit event is generated by an interrupt signal, it will bypass the
321 * internal queue and be delivered to the application at the next event poll.
322 */
323extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter);
324
325/**
326 *  Return the current event filter - can be used to "chain" filters.
327 *  If there is no event filter set, this function returns NULL.
328 */
329extern DECLSPEC SDL_EventFilter SDLCALL SDL_GetEventFilter(void);
330/*@}*/
331
332/** @name Event State */
333/*@{*/
334#define SDL_QUERY       -1
335#define SDL_IGNORE       0
336#define SDL_DISABLE      0
337#define SDL_ENABLE       1
338/*@}*/
339
340/**
341* This function allows you to set the state of processing certain events.
342* If 'state' is set to SDL_IGNORE, that event will be automatically dropped
343* from the event queue and will not event be filtered.
344* If 'state' is set to SDL_ENABLE, that event will be processed normally.
345* If 'state' is set to SDL_QUERY, SDL_EventState() will return the
346* current processing state of the specified event.
347*/
348extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint8 type, int state);
349
350/* Ends C function definitions when using C++ */
351#ifdef __cplusplus
352}
353#endif
354#include "close_code.h"
355
356#endif /* _SDL_events_h */
Note: See TracBrowser for help on using the repository browser.