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