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