include/SDL_events.h
author Sam Lantinga <slouken@libsdl.org>
Sat, 31 Dec 2011 09:16:08 -0500
branchSDL-1.2
changeset 6137 4720145f848b
parent 4217 4c4113c2162c
permissions -rw-r--r--
Happy New Year!
     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
    42 extern "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 */
    52 typedef 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))
    88 typedef 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 */
   119 typedef 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 */
   126 typedef 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 */
   134 typedef 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 */
   144 typedef 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 */
   153 typedef 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 */
   161 typedef 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 */
   170 typedef 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 */
   183 typedef 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  */
   194 typedef 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 */
   201 typedef struct SDL_ExposeEvent {
   202 	Uint8 type;	/**< SDL_VIDEOEXPOSE */
   203 } SDL_ExposeEvent;
   204 
   205 /** The "quit requested" event */
   206 typedef struct SDL_QuitEvent {
   207 	Uint8 type;	/**< SDL_QUIT */
   208 } SDL_QuitEvent;
   209 
   210 /** A user-defined event type */
   211 typedef 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 */
   219 struct SDL_SysWMmsg;
   220 typedef struct SDL_SysWMmsg SDL_SysWMmsg;
   221 typedef struct SDL_SysWMEvent {
   222 	Uint8 type;
   223 	SDL_SysWMmsg *msg;
   224 } SDL_SysWMEvent;
   225 
   226 /** General event structure */
   227 typedef 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  */
   251 extern DECLSPEC void SDLCALL SDL_PumpEvents(void);
   252 
   253 typedef 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  */
   277 extern 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  */
   284 extern 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  */
   290 extern 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  */
   296 extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event *event);
   297 
   298 /** @name Event Filtering */
   299 /*@{*/
   300 typedef 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  */
   323 extern 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  */
   329 extern 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 */
   348 extern 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 */