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