include/SDL_events.h
author Sam Lantinga <slouken@libsdl.org>
Sun, 02 Aug 2009 12:54:59 +0000
changeset 3220 6290f9bd097d
parent 3191 91b335df6fc8
child 3280 00cace2d9080
permissions -rw-r--r--
Better check which includes #define used in stdint.h
     1 /*
     2     SDL - Simple DirectMedia Layer
     3     Copyright (C) 1997-2009 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  *
    26  * Include file for SDL event handling
    27  */
    28 
    29 #ifndef _SDL_events_h
    30 #define _SDL_events_h
    31 
    32 #include "SDL_stdinc.h"
    33 #include "SDL_error.h"
    34 #include "SDL_video.h"
    35 #include "SDL_keyboard.h"
    36 #include "SDL_mouse.h"
    37 #include "SDL_joystick.h"
    38 #include "SDL_quit.h"
    39 
    40 #include "begin_code.h"
    41 /* Set up for C function definitions, even when using C++ */
    42 #ifdef __cplusplus
    43 /* *INDENT-OFF* */
    44 extern "C" {
    45 /* *INDENT-ON* */
    46 #endif
    47 
    48 /* General keyboard/mouse state definitions */
    49 #define SDL_RELEASED	0
    50 #define SDL_PRESSED	1
    51 
    52 /**
    53  * \enum SDL_EventType
    54  *
    55  * \brief The types of events that can be delivered
    56  */
    57 typedef enum
    58 {
    59     SDL_NOEVENT = 0,            /**< Unused (do not remove) */
    60     SDL_WINDOWEVENT,            /**< Window state change */
    61     SDL_KEYDOWN,                /**< Keys pressed */
    62     SDL_KEYUP,                  /**< Keys released */
    63     SDL_TEXTINPUT,              /**< Keyboard text input */
    64     SDL_MOUSEMOTION,            /**< Mouse moved */
    65     SDL_MOUSEBUTTONDOWN,        /**< Mouse button pressed */
    66     SDL_MOUSEBUTTONUP,          /**< Mouse button released */
    67     SDL_MOUSEWHEEL,             /**< Mouse wheel motion */
    68     SDL_JOYAXISMOTION,          /**< Joystick axis motion */
    69     SDL_JOYBALLMOTION,          /**< Joystick trackball motion */
    70     SDL_JOYHATMOTION,           /**< Joystick hat position change */
    71     SDL_JOYBUTTONDOWN,          /**< Joystick button pressed */
    72     SDL_JOYBUTTONUP,            /**< Joystick button released */
    73     SDL_QUIT,                   /**< User-requested quit */
    74     SDL_SYSWMEVENT,             /**< System specific event */
    75     SDL_PROXIMITYIN,            /**< Proximity In event */
    76     SDL_PROXIMITYOUT,           /**< Proximity Out event */
    77     SDL_EVENT_RESERVED1,        /**< Reserved for future use... */
    78     SDL_EVENT_RESERVED2,
    79     SDL_EVENT_RESERVED3,
    80     /* Events SDL_USEREVENT through SDL_MAXEVENTS-1 are for your use */
    81     SDL_USEREVENT = 24,
    82     /* This last event is only for bounding internal arrays
    83        It is the number of bits in the event mask datatype -- Uint32
    84      */
    85     SDL_NUMEVENTS = 32
    86 } SDL_EventType;
    87 
    88 /**
    89  * \enum SDL_EventMask
    90  *
    91  * \brief Predefined event masks
    92  */
    93 #define SDL_EVENTMASK(X)	(1<<(X))
    94 typedef enum
    95 {
    96     SDL_WINDOWEVENTMASK = SDL_EVENTMASK(SDL_WINDOWEVENT),
    97     SDL_KEYDOWNMASK = SDL_EVENTMASK(SDL_KEYDOWN),
    98     SDL_KEYUPMASK = SDL_EVENTMASK(SDL_KEYUP),
    99     SDL_KEYEVENTMASK = SDL_EVENTMASK(SDL_KEYDOWN) | SDL_EVENTMASK(SDL_KEYUP),
   100     SDL_TEXTINPUTMASK = SDL_EVENTMASK(SDL_TEXTINPUT),
   101     SDL_MOUSEMOTIONMASK = SDL_EVENTMASK(SDL_MOUSEMOTION),
   102     SDL_MOUSEBUTTONDOWNMASK = SDL_EVENTMASK(SDL_MOUSEBUTTONDOWN),
   103     SDL_MOUSEBUTTONUPMASK = SDL_EVENTMASK(SDL_MOUSEBUTTONUP),
   104     SDL_MOUSEWHEELMASK = SDL_EVENTMASK(SDL_MOUSEWHEEL),
   105     SDL_MOUSEEVENTMASK = SDL_EVENTMASK(SDL_MOUSEMOTION) |
   106         SDL_EVENTMASK(SDL_MOUSEBUTTONDOWN) | SDL_EVENTMASK(SDL_MOUSEBUTTONUP),
   107     SDL_JOYAXISMOTIONMASK = SDL_EVENTMASK(SDL_JOYAXISMOTION),
   108     SDL_JOYBALLMOTIONMASK = SDL_EVENTMASK(SDL_JOYBALLMOTION),
   109     SDL_JOYHATMOTIONMASK = SDL_EVENTMASK(SDL_JOYHATMOTION),
   110     SDL_JOYBUTTONDOWNMASK = SDL_EVENTMASK(SDL_JOYBUTTONDOWN),
   111     SDL_JOYBUTTONUPMASK = SDL_EVENTMASK(SDL_JOYBUTTONUP),
   112     SDL_JOYEVENTMASK = SDL_EVENTMASK(SDL_JOYAXISMOTION) |
   113         SDL_EVENTMASK(SDL_JOYBALLMOTION) |
   114         SDL_EVENTMASK(SDL_JOYHATMOTION) |
   115         SDL_EVENTMASK(SDL_JOYBUTTONDOWN) | SDL_EVENTMASK(SDL_JOYBUTTONUP),
   116     SDL_QUITMASK = SDL_EVENTMASK(SDL_QUIT),
   117     SDL_SYSWMEVENTMASK = SDL_EVENTMASK(SDL_SYSWMEVENT),
   118     SDL_PROXIMITYINMASK = SDL_EVENTMASK(SDL_PROXIMITYIN),
   119     SDL_PROXIMITYOUTMASK = SDL_EVENTMASK(SDL_PROXIMITYOUT)
   120 } SDL_EventMask;
   121 #define SDL_ALLEVENTS		0xFFFFFFFF
   122 
   123 /**
   124  * \struct SDL_WindowEvent
   125  *
   126  * \brief Window state change event data (event.window.*)
   127  */
   128 typedef struct SDL_WindowEvent
   129 {
   130     Uint8 type;             /**< SDL_WINDOWEVENT */
   131     SDL_WindowID windowID;  /**< The associated window */
   132     Uint8 event;            /**< SDL_WindowEventID */
   133     int data1;              /**< event dependent data */
   134     int data2;              /**< event dependent data */
   135 } SDL_WindowEvent;
   136 
   137 /**
   138  * \struct SDL_KeyboardEvent
   139  *
   140  * \brief Keyboard button event structure (event.key.*)
   141  */
   142 typedef struct SDL_KeyboardEvent
   143 {
   144     Uint8 type;             /**< SDL_KEYDOWN or SDL_KEYUP */
   145     SDL_WindowID windowID;  /**< The window with keyboard focus, if any */
   146     Uint8 which;            /**< The keyboard device index */
   147     Uint8 state;            /**< SDL_PRESSED or SDL_RELEASED */
   148     SDL_keysym keysym;      /**< The key that was pressed or released */
   149 } SDL_KeyboardEvent;
   150 
   151 /**
   152  * \struct SDL_TextInputEvent
   153  *
   154  * \brief Keyboard text input event structure (event.text.*)
   155  */
   156 #define SDL_TEXTINPUTEVENT_TEXT_SIZE (32)
   157 typedef struct SDL_TextInputEvent
   158 {
   159     Uint8 type;                               /**< SDL_TEXTINPUT */
   160     SDL_WindowID windowID;                    /**< The window with keyboard focus, if any */
   161     Uint8 which;                              /**< The keyboard device index */
   162     char text[SDL_TEXTINPUTEVENT_TEXT_SIZE];  /**< The input text */
   163 } SDL_TextInputEvent;
   164 
   165 /**
   166  * \struct SDL_MouseMotionEvent
   167  *
   168  * \brief Mouse motion event structure (event.motion.*)
   169  */
   170 typedef struct SDL_MouseMotionEvent
   171 {
   172     Uint8 type;             /**< SDL_MOUSEMOTION */
   173     SDL_WindowID windowID;  /**< The window with mouse focus, if any */
   174     Uint8 which;            /**< The mouse device index */
   175     Uint8 state;            /**< The current button state */
   176     int x;                  /**< X coordinate, relative to window */
   177     int y;                  /**< Y coordinate, relative to window */
   178     int z;                  /**< Z coordinate, for future use */
   179     int pressure;           /**< Pressure reported by tablets */
   180     int pressure_max;       /**< Maximum value of the pressure reported by the device */
   181     int pressure_min;       /**< Minimum value of the pressure reported by the device */
   182     int rotation;           /**< For future use */
   183     int tilt;               /**< For future use */
   184     int cursor;             /**< The cursor being used in the event */
   185     int xrel;               /**< The relative motion in the X direction */
   186     int yrel;               /**< The relative motion in the Y direction */
   187 } SDL_MouseMotionEvent;
   188 
   189 /**
   190  * \struct SDL_MouseButtonEvent
   191  *
   192  * \brief Mouse button event structure (event.button.*)
   193  */
   194 typedef struct SDL_MouseButtonEvent
   195 {
   196     Uint8 type;             /**< SDL_MOUSEBUTTONDOWN or SDL_MOUSEBUTTONUP */
   197     SDL_WindowID windowID;  /**< The window with mouse focus, if any */
   198     Uint8 which;            /**< The mouse device index */
   199     Uint8 button;           /**< The mouse button index */
   200     Uint8 state;            /**< SDL_PRESSED or SDL_RELEASED */
   201     int x;                  /**< X coordinate, relative to window */
   202     int y;                  /**< Y coordinate, relative to window */
   203 } SDL_MouseButtonEvent;
   204 
   205 /**
   206  * \struct SDL_MouseWheelEvent
   207  *
   208  * \brief Mouse wheel event structure (event.wheel.*)
   209  */
   210 typedef struct SDL_MouseWheelEvent
   211 {
   212     Uint8 type;             /**< SDL_MOUSEWHEEL */
   213     SDL_WindowID windowID;  /**< The window with mouse focus, if any */
   214     Uint8 which;            /**< The mouse device index */
   215     int x;                  /**< The amount scrolled horizontally */
   216     int y;                  /**< The amount scrolled vertically */
   217 } SDL_MouseWheelEvent;
   218 
   219 /**
   220  * \struct SDL_JoyAxisEvent
   221  *
   222  * \brief Joystick axis motion event structure (event.jaxis.*)
   223  */
   224 typedef struct SDL_JoyAxisEvent
   225 {
   226     Uint8 type;         /**< SDL_JOYAXISMOTION */
   227     Uint8 which;        /**< The joystick device index */
   228     Uint8 axis;         /**< The joystick axis index */
   229     int value;          /**< The axis value (range: -32768 to 32767) */
   230 } SDL_JoyAxisEvent;
   231 
   232 /**
   233  * \struct SDL_JoyBallEvent
   234  *
   235  * \brief Joystick trackball motion event structure (event.jball.*)
   236  */
   237 typedef struct SDL_JoyBallEvent
   238 {
   239     Uint8 type;         /**< SDL_JOYBALLMOTION */
   240     Uint8 which;        /**< The joystick device index */
   241     Uint8 ball;         /**< The joystick trackball index */
   242     int xrel;           /**< The relative motion in the X direction */
   243     int yrel;           /**< The relative motion in the Y direction */
   244 } SDL_JoyBallEvent;
   245 
   246 /**
   247  * \struct SDL_JoyHatEvent
   248  *
   249  * \brief Joystick hat position change event structure (event.jhat.*)
   250  */
   251 typedef struct SDL_JoyHatEvent
   252 {
   253     Uint8 type;         /**< SDL_JOYHATMOTION */
   254     Uint8 which;        /**< The joystick device index */
   255     Uint8 hat;          /**< The joystick hat index */
   256     Uint8 value;        /**< The hat position value:
   257                              SDL_HAT_LEFTUP   SDL_HAT_UP       SDL_HAT_RIGHTUP
   258                              SDL_HAT_LEFT     SDL_HAT_CENTERED SDL_HAT_RIGHT
   259                              SDL_HAT_LEFTDOWN SDL_HAT_DOWN     SDL_HAT_RIGHTDOWN
   260                              Note that zero means the POV is centered.
   261                          */
   262 } SDL_JoyHatEvent;
   263 
   264 /**
   265  * \struct SDL_JoyButtonEvent
   266  *
   267  * \brief Joystick button event structure (event.jbutton.*)
   268  */
   269 typedef struct SDL_JoyButtonEvent
   270 {
   271     Uint8 type;         /**< SDL_JOYBUTTONDOWN or SDL_JOYBUTTONUP */
   272     Uint8 which;        /**< The joystick device index */
   273     Uint8 button;       /**< The joystick button index */
   274     Uint8 state;        /**< SDL_PRESSED or SDL_RELEASED */
   275 } SDL_JoyButtonEvent;
   276 
   277 /**
   278  * \struct SDL_QuitEvent
   279  *
   280  * \brief The "quit requested" event
   281  */
   282 typedef struct SDL_QuitEvent
   283 {
   284     Uint8 type;         /**< SDL_QUIT */
   285 } SDL_QuitEvent;
   286 
   287 /**
   288  * \struct SDL_UserEvent
   289  *
   290  * \brief A user-defined event type (event.user.*)
   291  */
   292 typedef struct SDL_UserEvent
   293 {
   294     Uint8 type;             /**< SDL_USEREVENT through SDL_NUMEVENTS-1 */
   295     SDL_WindowID windowID;  /**< The associated window if any*/
   296     int code;               /**< User defined event code */
   297     void *data1;            /**< User defined data pointer */
   298     void *data2;            /**< User defined data pointer */
   299 } SDL_UserEvent;
   300 
   301 /**
   302  * \struct SDL_SysWMEvent
   303  *
   304  * \brief A video driver dependent system event (event.syswm.*)
   305  *
   306  * \note If you want to use this event, you should include SDL_syswm.h
   307  */
   308 struct SDL_SysWMmsg;
   309 typedef struct SDL_SysWMmsg SDL_SysWMmsg;
   310 typedef struct SDL_SysWMEvent
   311 {
   312     Uint8 type;         /**< SDL_SYSWMEVENT */
   313     SDL_SysWMmsg *msg;  /**< driver dependent data, defined in SDL_syswm.h */
   314 } SDL_SysWMEvent;
   315 
   316 typedef struct SDL_ProximityEvent
   317 {
   318     Uint8 type;
   319     SDL_WindowID windowID;  /**< The associated window */
   320     Uint8 which;
   321     int cursor;
   322     int x;
   323     int y;
   324 } SDL_ProximityEvent;
   325 
   326 /* Typedefs for backwards compatibility */
   327 #ifndef SDL_NO_COMPAT
   328 typedef struct SDL_ActiveEvent
   329 {
   330     Uint8 type;
   331     Uint8 gain;
   332     Uint8 state;
   333 } SDL_ActiveEvent;
   334 
   335 typedef struct SDL_ResizeEvent
   336 {
   337     Uint8 type;
   338     int w;
   339     int h;
   340 } SDL_ResizeEvent;
   341 #endif
   342 
   343 /**
   344  * \union SDL_Event
   345  *
   346  * \brief General event structure
   347  */
   348 typedef union SDL_Event
   349 {
   350     Uint8 type;                     /**< Event type, shared with all events */
   351     SDL_WindowEvent window;         /**< Window event data */
   352     SDL_KeyboardEvent key;          /**< Keyboard event data */
   353     SDL_TextInputEvent text;        /**< Text input event data */
   354     SDL_MouseMotionEvent motion;    /**< Mouse motion event data */
   355     SDL_MouseButtonEvent button;    /**< Mouse button event data */
   356     SDL_MouseWheelEvent wheel;      /**< Mouse wheel event data */
   357     SDL_JoyAxisEvent jaxis;         /**< Joystick axis event data */
   358     SDL_JoyBallEvent jball;         /**< Joystick ball event data */
   359     SDL_JoyHatEvent jhat;           /**< Joystick hat event data */
   360     SDL_JoyButtonEvent jbutton;     /**< Joystick button event data */
   361     SDL_QuitEvent quit;             /**< Quit request event data */
   362     SDL_UserEvent user;             /**< Custom event data */
   363     SDL_SysWMEvent syswm;           /**< System dependent window event data */
   364     SDL_ProximityEvent proximity;   /**< Proximity In or Out event */
   365 
   366     /* Temporarily here for backwards compatibility */
   367 #ifndef SDL_NO_COMPAT
   368     SDL_ActiveEvent active;
   369     SDL_ResizeEvent resize;
   370 #endif
   371 } SDL_Event;
   372 
   373 
   374 /* Function prototypes */
   375 
   376 /* Pumps the event loop, gathering events from the input devices.
   377    This function updates the event queue and internal input device state.
   378    This should only be run in the thread that sets the video mode.
   379 */
   380 extern DECLSPEC void SDLCALL SDL_PumpEvents(void);
   381 
   382 /* Checks the event queue for messages and optionally returns them.
   383    If 'action' is SDL_ADDEVENT, up to 'numevents' events will be added to
   384    the back of the event queue.
   385    If 'action' is SDL_PEEKEVENT, up to 'numevents' events at the front
   386    of the event queue, matching 'mask', will be returned and will not
   387    be removed from the queue.
   388    If 'action' is SDL_GETEVENT, up to 'numevents' events at the front 
   389    of the event queue, matching 'mask', will be returned and will be
   390    removed from the queue.
   391    This function returns the number of events actually stored, or -1
   392    if there was an error.  This function is thread-safe.
   393 */
   394 typedef enum
   395 {
   396     SDL_ADDEVENT,
   397     SDL_PEEKEVENT,
   398     SDL_GETEVENT
   399 } SDL_eventaction;
   400 /* */
   401 extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents,
   402                                            SDL_eventaction action,
   403                                            Uint32 mask);
   404 
   405 /* Checks to see if certain event types are in the event queue.
   406  */
   407 extern DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 mask);
   408 
   409 /* Polls for currently pending events, and returns 1 if there are any pending
   410    events, or 0 if there are none available.  If 'event' is not NULL, the next
   411    event is removed from the queue and stored in that area.
   412  */
   413 extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
   414 
   415 /* Waits indefinitely for the next available event, returning 1, or 0 if there
   416    was an error while waiting for events.  If 'event' is not NULL, the next
   417    event is removed from the queue and stored in that area.
   418  */
   419 extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event * event);
   420 
   421 /* Waits until the specified timeout (in milliseconds) for the next available
   422    event, returning 1, or 0 if there was an error while waiting for events. If
   423    'event' is not NULL, the next event is removed from the queue and stored in
   424    that area.
   425  */
   426 extern DECLSPEC int SDLCALL SDL_WaitEventTimeout(SDL_Event * event,
   427                                                  int timeout);
   428 
   429 /* Add an event to the event queue.
   430    This function returns 1 on success, 0 if the event was filtered,
   431    or -1 if the event queue was full or there was some other error.
   432  */
   433 extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event);
   434 
   435 /*
   436   This function sets up a filter to process all events before they
   437   change internal state and are posted to the internal event queue.
   438 
   439   The filter is protypted as:
   440 */
   441 typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event);
   442 /*
   443   If the filter returns 1, then the event will be added to the internal queue.
   444   If it returns 0, then the event will be dropped from the queue, but the 
   445   internal state will still be updated.  This allows selective filtering of
   446   dynamically arriving events.
   447 
   448   WARNING:  Be very careful of what you do in the event filter function, as 
   449             it may run in a different thread!
   450 
   451   There is one caveat when dealing with the SDL_QUITEVENT event type.  The
   452   event filter is only called when the window manager desires to close the
   453   application window.  If the event filter returns 1, then the window will
   454   be closed, otherwise the window will remain open if possible.
   455   If the quit event is generated by an interrupt signal, it will bypass the
   456   internal queue and be delivered to the application at the next event poll.
   457 */
   458 extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter,
   459                                                 void *userdata);
   460 
   461 /*
   462   Return the current event filter - can be used to "chain" filters.
   463   If there is no event filter set, this function returns SDL_FALSE.
   464 */
   465 extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter * filter,
   466                                                     void **userdata);
   467 
   468 /*
   469   Run the filter function on the current event queue, removing any
   470   events for which the filter returns 0.
   471 */
   472 extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter,
   473                                               void *userdata);
   474 
   475 /*
   476   This function allows you to set the state of processing certain events.
   477   If 'state' is set to SDL_IGNORE, that event will be automatically dropped
   478   from the event queue and will not event be filtered.
   479   If 'state' is set to SDL_ENABLE, that event will be processed normally.
   480   If 'state' is set to SDL_QUERY, SDL_EventState() will return the 
   481   current processing state of the specified event.
   482 */
   483 #define SDL_QUERY	-1
   484 #define SDL_IGNORE	 0
   485 #define SDL_DISABLE	 0
   486 #define SDL_ENABLE	 1
   487 extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint8 type, int state);
   488 
   489 
   490 /* Ends C function definitions when using C++ */
   491 #ifdef __cplusplus
   492 /* *INDENT-OFF* */
   493 }
   494 /* *INDENT-ON* */
   495 #endif
   496 #include "close_code.h"
   497 
   498 #endif /* _SDL_events_h */
   499 
   500 /* vi: set ts=4 sw=4 expandtab: */