include/SDL_events.h
author Szymon Wilczek <kazeuser@gmail.com>
Wed, 02 Jul 2008 20:29:29 +0000
branchgsoc2008_manymouse
changeset 3763 81ea7d9a6624
parent 3760 64f346a83ed3
child 3765 ed9b7fe8f902
permissions -rw-r--r--
Proximity events and evil-temporary makefile repair
     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_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     Uint8 event;            /**< SDL_WindowEventID */
   132     int data1;              /**< event dependent data */
   133     int data2;              /**< event dependent data */
   134     SDL_WindowID windowID;  /**< The associated window */
   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     Uint8 which;            /**< The keyboard device index */
   146     Uint8 state;            /**< SDL_PRESSED or SDL_RELEASED */
   147     SDL_keysym keysym;      /**< The key that was pressed or released */
   148     SDL_WindowID windowID;  /**< The window with keyboard focus, if any */
   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     Uint8 which;                              /**< The keyboard device index */
   161     char text[SDL_TEXTINPUTEVENT_TEXT_SIZE];  /**< The input text */
   162     SDL_WindowID windowID;                    /**< The window with keyboard focus, if any */
   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     Uint8 which;            /**< The mouse device index */
   174     Uint8 state;            /**< The current button state */
   175     int x;                  /**< X coordinate, relative to window */
   176     int y;                  /**< Y coordinate, relative to window */
   177     int z;
   178     int xrel;               /**< The relative motion in the X direction */
   179     int yrel;               /**< The relative motion in the Y direction */
   180     SDL_WindowID windowID;  /**< The window with mouse focus, if any */
   181 } SDL_MouseMotionEvent;
   182 
   183 /**
   184  * \struct SDL_MouseButtonEvent
   185  *
   186  * \brief Mouse button event structure (event.button.*)
   187  */
   188 typedef struct SDL_MouseButtonEvent
   189 {
   190     Uint8 type;             /**< SDL_MOUSEBUTTONDOWN or SDL_MOUSEBUTTONUP */
   191     Uint8 which;            /**< The mouse device index */
   192     Uint8 button;           /**< The mouse button index */
   193     Uint8 state;            /**< SDL_PRESSED or SDL_RELEASED */
   194     int x;                  /**< X coordinate, relative to window */
   195     int y;                  /**< Y coordinate, relative to window */
   196     SDL_WindowID windowID;  /**< The window with mouse focus, if any */
   197 } SDL_MouseButtonEvent;
   198 
   199 /**
   200  * \struct SDL_MouseWheelEvent
   201  *
   202  * \brief Mouse wheel event structure (event.wheel.*)
   203  */
   204 typedef struct SDL_MouseWheelEvent
   205 {
   206     Uint8 type;             /**< SDL_MOUSEWHEEL */
   207     Uint8 which;            /**< The mouse device index */
   208     int x;                  /**< The amount scrolled horizontally */
   209     int y;                  /**< The amount scrolled vertically */
   210     SDL_WindowID windowID;  /**< The window with mouse focus, if any */
   211 } SDL_MouseWheelEvent;
   212 
   213 /**
   214  * \struct SDL_JoyAxisEvent
   215  *
   216  * \brief Joystick axis motion event structure (event.jaxis.*)
   217  */
   218 typedef struct SDL_JoyAxisEvent
   219 {
   220     Uint8 type;         /**< SDL_JOYAXISMOTION */
   221     Uint8 which;        /**< The joystick device index */
   222     Uint8 axis;         /**< The joystick axis index */
   223     int value;          /**< The axis value (range: -32768 to 32767) */
   224 } SDL_JoyAxisEvent;
   225 
   226 /**
   227  * \struct SDL_JoyBallEvent
   228  *
   229  * \brief Joystick trackball motion event structure (event.jball.*)
   230  */
   231 typedef struct SDL_JoyBallEvent
   232 {
   233     Uint8 type;         /**< SDL_JOYBALLMOTION */
   234     Uint8 which;        /**< The joystick device index */
   235     Uint8 ball;         /**< The joystick trackball index */
   236     int xrel;           /**< The relative motion in the X direction */
   237     int yrel;           /**< The relative motion in the Y direction */
   238 } SDL_JoyBallEvent;
   239 
   240 /**
   241  * \struct SDL_JoyHatEvent
   242  *
   243  * \brief Joystick hat position change event structure (event.jhat.*)
   244  */
   245 typedef struct SDL_JoyHatEvent
   246 {
   247     Uint8 type;         /**< SDL_JOYHATMOTION */
   248     Uint8 which;        /**< The joystick device index */
   249     Uint8 hat;          /**< The joystick hat index */
   250     Uint8 value;        /**< The hat position value:
   251                              SDL_HAT_LEFTUP   SDL_HAT_UP       SDL_HAT_RIGHTUP
   252                              SDL_HAT_LEFT     SDL_HAT_CENTERED SDL_HAT_RIGHT
   253                              SDL_HAT_LEFTDOWN SDL_HAT_DOWN     SDL_HAT_RIGHTDOWN
   254                              Note that zero means the POV is centered.
   255                          */
   256 } SDL_JoyHatEvent;
   257 
   258 /**
   259  * \struct SDL_JoyButtonEvent
   260  *
   261  * \brief Joystick button event structure (event.jbutton.*)
   262  */
   263 typedef struct SDL_JoyButtonEvent
   264 {
   265     Uint8 type;         /**< SDL_JOYBUTTONDOWN or SDL_JOYBUTTONUP */
   266     Uint8 which;        /**< The joystick device index */
   267     Uint8 button;       /**< The joystick button index */
   268     Uint8 state;        /**< SDL_PRESSED or SDL_RELEASED */
   269 } SDL_JoyButtonEvent;
   270 
   271 /**
   272  * \struct SDL_QuitEvent
   273  *
   274  * \brief The "quit requested" event
   275  */
   276 typedef struct SDL_QuitEvent
   277 {
   278     Uint8 type;         /**< SDL_QUIT */
   279 } SDL_QuitEvent;
   280 
   281 /**
   282  * \struct SDL_UserEvent
   283  *
   284  * \brief A user-defined event type (event.user.*)
   285  */
   286 typedef struct SDL_UserEvent
   287 {
   288     Uint8 type;             /**< SDL_USEREVENT through SDL_NUMEVENTS-1 */
   289     int code;               /**< User defined event code */
   290     void *data1;            /**< User defined data pointer */
   291     void *data2;            /**< User defined data pointer */
   292     SDL_WindowID windowID;  /**< The associated window if any*/
   293 } SDL_UserEvent;
   294 
   295 /**
   296  * \struct SDL_SysWMEvent
   297  *
   298  * \brief A video driver dependent system event (event.syswm.*)
   299  *
   300  * \note If you want to use this event, you should include SDL_syswm.h
   301  */
   302 struct SDL_SysWMmsg;
   303 typedef struct SDL_SysWMmsg SDL_SysWMmsg;
   304 typedef struct SDL_SysWMEvent
   305 {
   306     Uint8 type;         /**< SDL_SYSWMEVENT */
   307     SDL_SysWMmsg *msg;  /**< driver dependent data, defined in SDL_syswm.h */
   308 } SDL_SysWMEvent;
   309 
   310 /* Typedefs for backwards compatibility */
   311 typedef struct SDL_ActiveEvent
   312 {
   313     Uint8 type;
   314     Uint8 gain;
   315     Uint8 state;
   316 } SDL_ActiveEvent;
   317 typedef struct SDL_ResizeEvent
   318 {
   319     Uint8 type;
   320     int w;
   321     int h;
   322 } SDL_ResizeEvent;
   323 
   324 typedef struct SDL_ProximityEvent
   325 {
   326     Uint8 which;
   327     Uint8 type;
   328     int x;
   329     int y;
   330 } SDL_ProximityEvent;
   331 
   332 /**
   333  * \union SDL_Event
   334  *
   335  * \brief General event structure
   336  */
   337 typedef union SDL_Event
   338 {
   339     Uint8 type;                     /**< Event type, shared with all events */
   340     SDL_WindowEvent window;         /**< Window event data */
   341     SDL_KeyboardEvent key;          /**< Keyboard event data */
   342     SDL_TextInputEvent text;        /**< Text input event data */
   343     SDL_MouseMotionEvent motion;    /**< Mouse motion event data */
   344     SDL_MouseButtonEvent button;    /**< Mouse button event data */
   345     SDL_MouseWheelEvent wheel;      /**< Mouse wheel event data */
   346     SDL_JoyAxisEvent jaxis;         /**< Joystick axis event data */
   347     SDL_JoyBallEvent jball;         /**< Joystick ball event data */
   348     SDL_JoyHatEvent jhat;           /**< Joystick hat event data */
   349     SDL_JoyButtonEvent jbutton;     /**< Joystick button event data */
   350     SDL_QuitEvent quit;             /**< Quit request event data */
   351     SDL_UserEvent user;             /**< Custom event data */
   352     SDL_SysWMEvent syswm;           /**< System dependent window event data */
   353     SDL_ProximityEvent proximity;    /**< Proximity In or Out event */
   354     /* Temporarily here for backwards compatibility */
   355     SDL_ActiveEvent active;
   356     SDL_ResizeEvent resize;
   357 } SDL_Event;
   358 
   359 
   360 /* Function prototypes */
   361 
   362 /* Pumps the event loop, gathering events from the input devices.
   363    This function updates the event queue and internal input device state.
   364    This should only be run in the thread that sets the video mode.
   365 */
   366 extern DECLSPEC void SDLCALL SDL_PumpEvents(void);
   367 
   368 /* Checks the event queue for messages and optionally returns them.
   369    If 'action' is SDL_ADDEVENT, up to 'numevents' events will be added to
   370    the back of the event queue.
   371    If 'action' is SDL_PEEKEVENT, up to 'numevents' events at the front
   372    of the event queue, matching 'mask', will be returned and will not
   373    be removed from the queue.
   374    If 'action' is SDL_GETEVENT, up to 'numevents' events at the front 
   375    of the event queue, matching 'mask', will be returned and will be
   376    removed from the queue.
   377    This function returns the number of events actually stored, or -1
   378    if there was an error.  This function is thread-safe.
   379 */
   380 typedef enum
   381 {
   382     SDL_ADDEVENT,
   383     SDL_PEEKEVENT,
   384     SDL_GETEVENT
   385 } SDL_eventaction;
   386 /* */
   387 extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents,
   388                                            SDL_eventaction action,
   389                                            Uint32 mask);
   390 
   391 /* Checks to see if certain event types are in the event queue.
   392  */
   393 extern DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 mask);
   394 
   395 /* Polls for currently pending events, and returns 1 if there are any pending
   396    events, or 0 if there are none available.  If 'event' is not NULL, the next
   397    event is removed from the queue and stored in that area.
   398  */
   399 extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
   400 
   401 /* Waits indefinitely for the next available event, returning 1, or 0 if there
   402    was an error while waiting for events.  If 'event' is not NULL, the next
   403    event is removed from the queue and stored in that area.
   404  */
   405 extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event * event);
   406 
   407 /* Add an event to the event queue.
   408    This function returns 1 on success, 0 if the event was filtered,
   409    or -1 if the event queue was full or there was some other error.
   410  */
   411 extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event);
   412 
   413 /*
   414   This function sets up a filter to process all events before they
   415   change internal state and are posted to the internal event queue.
   416 
   417   The filter is protypted as:
   418 */
   419 typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event);
   420 /*
   421   If the filter returns 1, then the event will be added to the internal queue.
   422   If it returns 0, then the event will be dropped from the queue, but the 
   423   internal state will still be updated.  This allows selective filtering of
   424   dynamically arriving events.
   425 
   426   WARNING:  Be very careful of what you do in the event filter function, as 
   427             it may run in a different thread!
   428 
   429   There is one caveat when dealing with the SDL_QUITEVENT event type.  The
   430   event filter is only called when the window manager desires to close the
   431   application window.  If the event filter returns 1, then the window will
   432   be closed, otherwise the window will remain open if possible.
   433   If the quit event is generated by an interrupt signal, it will bypass the
   434   internal queue and be delivered to the application at the next event poll.
   435 */
   436 extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter,
   437                                                 void *userdata);
   438 
   439 /*
   440   Return the current event filter - can be used to "chain" filters.
   441   If there is no event filter set, this function returns SDL_FALSE.
   442 */
   443 extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter * filter,
   444                                                     void **userdata);
   445 
   446 /*
   447   Run the filter function on the current event queue, removing any
   448   events for which the filter returns 0.
   449 */
   450 extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter,
   451                                               void *userdata);
   452 
   453 /*
   454   This function allows you to set the state of processing certain events.
   455   If 'state' is set to SDL_IGNORE, that event will be automatically dropped
   456   from the event queue and will not event be filtered.
   457   If 'state' is set to SDL_ENABLE, that event will be processed normally.
   458   If 'state' is set to SDL_QUERY, SDL_EventState() will return the 
   459   current processing state of the specified event.
   460 */
   461 #define SDL_QUERY	-1
   462 #define SDL_IGNORE	 0
   463 #define SDL_DISABLE	 0
   464 #define SDL_ENABLE	 1
   465 extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint8 type, int state);
   466 
   467 
   468 /* Ends C function definitions when using C++ */
   469 #ifdef __cplusplus
   470 /* *INDENT-OFF* */
   471 }
   472 /* *INDENT-ON* */
   473 #endif
   474 #include "close_code.h"
   475 
   476 #endif /* _SDL_events_h */
   477 
   478 /* vi: set ts=4 sw=4 expandtab: */