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