include/SDL_events.h
author Paul Hunkin <paul@bieh.net>
Mon, 17 May 2010 15:14:34 +1200
changeset 4695 b7918263da92
parent 4435 e953700da4ca
child 4465 3e69e077cb95
child 4641 49a97daea6ec
permissions -rw-r--r--
Initial commit, adding __ANDROID__ to the platform list
     1 /*
     2     SDL - Simple DirectMedia Layer
     3     Copyright (C) 1997-2010 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  * \brief The types of events that can be delivered.
    54  */
    55 typedef enum
    56 {
    57     SDL_FIRSTEVENT     = 0,     /**< Unused (do not remove) */
    58 
    59     /* Application events */
    60     SDL_QUIT           = 0x100, /**< User-requested quit */
    61 
    62     /* Window events */
    63     SDL_WINDOWEVENT    = 0x200, /**< Window state change */
    64     SDL_SYSWMEVENT,             /**< System specific event */
    65 
    66     /* Keyboard events */
    67     SDL_KEYDOWN        = 0x300, /**< Keys pressed */
    68     SDL_KEYUP,                  /**< Keys released */
    69     SDL_TEXTEDITING,            /**< Keyboard text editing (composition) */
    70     SDL_TEXTINPUT,              /**< Keyboard text input */
    71 
    72     /* Mouse events */
    73     SDL_MOUSEMOTION    = 0x400, /**< Mouse moved */
    74     SDL_MOUSEBUTTONDOWN,        /**< Mouse button pressed */
    75     SDL_MOUSEBUTTONUP,          /**< Mouse button released */
    76     SDL_MOUSEWHEEL,             /**< Mouse wheel motion */
    77 
    78     /* Tablet events */
    79     SDL_PROXIMITYIN    = 0x500, /**< Proximity In event */
    80     SDL_PROXIMITYOUT,           /**< Proximity Out event */
    81 
    82     /* Joystick events */
    83     SDL_JOYAXISMOTION  = 0x600, /**< Joystick axis motion */
    84     SDL_JOYBALLMOTION,          /**< Joystick trackball motion */
    85     SDL_JOYHATMOTION,           /**< Joystick hat position change */
    86     SDL_JOYBUTTONDOWN,          /**< Joystick button pressed */
    87     SDL_JOYBUTTONUP,            /**< Joystick button released */
    88 
    89     /* Obsolete events */
    90     SDL_EVENT_COMPAT1 = 0x7000, /**< SDL 1.2 events for compatibility */
    91     SDL_EVENT_COMPAT2,
    92     SDL_EVENT_COMPAT3,
    93 
    94     /** Events ::SDL_USEREVENT through ::SDL_LASTEVENT are for your use,
    95      *  and should be allocated with SDL_RegisterEvents()
    96      */
    97     SDL_USEREVENT    = 0x8000,
    98 
    99     /**
   100      *  This last event is only for bounding internal arrays
   101      */
   102     SDL_LASTEVENT    = 0xFFFF
   103 } SDL_EventType;
   104 
   105 /**
   106  *  \brief Window state change event data (event.window.*)
   107  */
   108 typedef struct SDL_WindowEvent
   109 {
   110     Uint32 type;        /**< ::SDL_WINDOWEVENT */
   111     Uint32 windowID;    /**< The associated window */
   112     Uint8 event;        /**< ::SDL_WindowEventID */
   113     Uint8 padding1;
   114     Uint8 padding2;
   115     Uint8 padding3;
   116     int data1;          /**< event dependent data */
   117     int data2;          /**< event dependent data */
   118 } SDL_WindowEvent;
   119 
   120 /**
   121  *  \brief Keyboard button event structure (event.key.*)
   122  */
   123 typedef struct SDL_KeyboardEvent
   124 {
   125     Uint32 type;        /**< ::SDL_KEYDOWN or ::SDL_KEYUP */
   126     Uint32 windowID;    /**< The window with keyboard focus, if any */
   127     Uint8 which;        /**< The keyboard device index */
   128     Uint8 state;        /**< ::SDL_PRESSED or ::SDL_RELEASED */
   129     Uint8 padding1;
   130     Uint8 padding2;
   131     SDL_keysym keysym;  /**< The key that was pressed or released */
   132 } SDL_KeyboardEvent;
   133 
   134 #define SDL_TEXTEDITINGEVENT_TEXT_SIZE (32)
   135 /**
   136  *  \brief Keyboard text editing event structure (event.edit.*)
   137  */
   138 typedef struct SDL_TextEditingEvent
   139 {
   140     Uint32 type;                                /**< ::SDL_TEXTEDITING */
   141     Uint32 windowID;                            /**< The window with keyboard focus, if any */
   142     Uint8 which;                                /**< The keyboard device index */
   143     char text[SDL_TEXTEDITINGEVENT_TEXT_SIZE];  /**< The editing text */
   144     int start;                                  /**< The start cursor of selected editing text */
   145     int length;                                 /**< The length of selected editing text */
   146 } SDL_TextEditingEvent;
   147 
   148 
   149 #define SDL_TEXTINPUTEVENT_TEXT_SIZE (32)
   150 /**
   151  *  \brief Keyboard text input event structure (event.text.*)
   152  */
   153 typedef struct SDL_TextInputEvent
   154 {
   155     Uint32 type;                              /**< ::SDL_TEXTINPUT */
   156     Uint32 windowID;                          /**< The window with keyboard focus, if any */
   157     Uint8 which;                              /**< The keyboard device index */
   158     Uint8 padding1;
   159     Uint8 padding2;
   160     Uint8 padding3;
   161     char text[SDL_TEXTINPUTEVENT_TEXT_SIZE];  /**< The input text */
   162 } SDL_TextInputEvent;
   163 
   164 /**
   165  *  \brief Mouse motion event structure (event.motion.*)
   166  */
   167 typedef struct SDL_MouseMotionEvent
   168 {
   169     Uint32 type;        /**< ::SDL_MOUSEMOTION */
   170     Uint32 windowID;    /**< The window with mouse focus, if any */
   171     Uint8 which;        /**< The mouse device index */
   172     Uint8 state;        /**< The current button state */
   173     Uint8 padding1;
   174     Uint8 padding2;
   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 pressure_max;   /**< Maximum value of the pressure reported by the device */
   180     int pressure_min;   /**< Minimum value of the pressure reported by the device */
   181     int rotation;       /**< For future use */
   182     int tilt_x;         /**< For future use */
   183     int tilt_y;         /**< For future use */
   184     int cursor;         /**< The cursor being used in the event */
   185     int xrel;           /**< The relative motion in the X direction */
   186     int yrel;           /**< The relative motion in the Y direction */
   187 } SDL_MouseMotionEvent;
   188 
   189 /**
   190  *  \brief Mouse button event structure (event.button.*)
   191  */
   192 typedef struct SDL_MouseButtonEvent
   193 {
   194     Uint32 type;        /**< ::SDL_MOUSEBUTTONDOWN or ::SDL_MOUSEBUTTONUP */
   195     Uint32 windowID;    /**< The window with mouse focus, if any */
   196     Uint8 which;        /**< The mouse device index */
   197     Uint8 button;       /**< The mouse button index */
   198     Uint8 state;        /**< ::SDL_PRESSED or ::SDL_RELEASED */
   199     Uint8 padding1;
   200     int x;              /**< X coordinate, relative to window */
   201     int y;              /**< Y coordinate, relative to window */
   202 } SDL_MouseButtonEvent;
   203 
   204 /**
   205  *  \brief Mouse wheel event structure (event.wheel.*)
   206  */
   207 typedef struct SDL_MouseWheelEvent
   208 {
   209     Uint32 type;        /**< ::SDL_MOUSEWHEEL */
   210     Uint32 windowID;    /**< The window with mouse focus, if any */
   211     Uint8 which;        /**< The mouse device index */
   212     Uint8 padding1;
   213     Uint8 padding2;
   214     Uint8 padding3;
   215     int x;              /**< The amount scrolled horizontally */
   216     int y;              /**< The amount scrolled vertically */
   217 } SDL_MouseWheelEvent;
   218 
   219 /**
   220  * \brief Tablet pen proximity event
   221  */
   222 typedef struct SDL_ProximityEvent
   223 {
   224     Uint32 type;        /**< ::SDL_PROXIMITYIN or ::SDL_PROXIMITYOUT */
   225     Uint32 windowID;    /**< The associated window */
   226     Uint8 which;
   227     Uint8 padding1;
   228     Uint8 padding2;
   229     Uint8 padding3;
   230     int cursor;
   231     int x;
   232     int y;
   233 } SDL_ProximityEvent;
   234 
   235 /**
   236  *  \brief Joystick axis motion event structure (event.jaxis.*)
   237  */
   238 typedef struct SDL_JoyAxisEvent
   239 {
   240     Uint32 type;        /**< ::SDL_JOYAXISMOTION */
   241     Uint8 which;        /**< The joystick device index */
   242     Uint8 axis;         /**< The joystick axis index */
   243     Uint8 padding1;
   244     Uint8 padding2;
   245     int value;          /**< The axis value (range: -32768 to 32767) */
   246 } SDL_JoyAxisEvent;
   247 
   248 /**
   249  *  \brief Joystick trackball motion event structure (event.jball.*)
   250  */
   251 typedef struct SDL_JoyBallEvent
   252 {
   253     Uint32 type;        /**< ::SDL_JOYBALLMOTION */
   254     Uint8 which;        /**< The joystick device index */
   255     Uint8 ball;         /**< The joystick trackball index */
   256     Uint8 padding1;
   257     Uint8 padding2;
   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  *  \brief Joystick hat position change event structure (event.jhat.*)
   264  */
   265 typedef struct SDL_JoyHatEvent
   266 {
   267     Uint32 type;        /**< ::SDL_JOYHATMOTION */
   268     Uint8 which;        /**< The joystick device index */
   269     Uint8 hat;          /**< The joystick hat index */
   270     Uint8 value;        /**< The hat position value.
   271                          *   \sa ::SDL_HAT_LEFTUP ::SDL_HAT_UP ::SDL_HAT_RIGHTUP
   272                          *   \sa ::SDL_HAT_LEFT ::SDL_HAT_CENTERED ::SDL_HAT_RIGHT
   273                          *   \sa ::SDL_HAT_LEFTDOWN ::SDL_HAT_DOWN ::SDL_HAT_RIGHTDOWN
   274                          *   
   275                          *   Note that zero means the POV is centered.
   276                          */
   277     Uint8 padding1;
   278 } SDL_JoyHatEvent;
   279 
   280 /**
   281  *  \brief Joystick button event structure (event.jbutton.*)
   282  */
   283 typedef struct SDL_JoyButtonEvent
   284 {
   285     Uint32 type;        /**< ::SDL_JOYBUTTONDOWN or ::SDL_JOYBUTTONUP */
   286     Uint8 which;        /**< The joystick device index */
   287     Uint8 button;       /**< The joystick button index */
   288     Uint8 state;        /**< ::SDL_PRESSED or ::SDL_RELEASED */
   289     Uint8 padding1;
   290 } SDL_JoyButtonEvent;
   291 
   292 /**
   293  *  \brief The "quit requested" event
   294  */
   295 typedef struct SDL_QuitEvent
   296 {
   297     Uint32 type;        /**< ::SDL_QUIT */
   298 } SDL_QuitEvent;
   299 
   300 /**
   301  *  \brief A user-defined event type (event.user.*)
   302  */
   303 typedef struct SDL_UserEvent
   304 {
   305     Uint32 type;        /**< ::SDL_USEREVENT through ::SDL_NUMEVENTS-1 */
   306     Uint32 windowID;    /**< The associated window if any */
   307     int code;           /**< User defined event code */
   308     void *data1;        /**< User defined data pointer */
   309     void *data2;        /**< User defined data pointer */
   310 } SDL_UserEvent;
   311 
   312 struct SDL_SysWMmsg;
   313 typedef struct SDL_SysWMmsg SDL_SysWMmsg;
   314 
   315 /**
   316  *  \brief A video driver dependent system event (event.syswm.*)
   317  *  
   318  *  \note If you want to use this event, you should include SDL_syswm.h.
   319  */
   320 typedef struct SDL_SysWMEvent
   321 {
   322     Uint32 type;        /**< ::SDL_SYSWMEVENT */
   323     SDL_SysWMmsg *msg;  /**< driver dependent data, defined in SDL_syswm.h */
   324 } SDL_SysWMEvent;
   325 
   326 #ifndef SDL_NO_COMPAT
   327 /**
   328  *  \addtogroup Compatibility 
   329  */
   330 /*@{*/
   331 
   332 /**
   333  *  \name Typedefs for backwards compatibility
   334  */
   335 /*@{*/
   336 typedef struct SDL_ActiveEvent
   337 {
   338     Uint32 type;
   339     Uint8 gain;
   340     Uint8 state;
   341 } SDL_ActiveEvent;
   342 
   343 typedef struct SDL_ResizeEvent
   344 {
   345     Uint32 type;
   346     int w;
   347     int h;
   348 } SDL_ResizeEvent;
   349 /*@}*/
   350 
   351 /*@}*//*Compatibility*/
   352 #endif
   353 
   354 /**
   355  *  \brief General event structure
   356  */
   357 typedef union SDL_Event
   358 {
   359     Uint32 type;                    /**< Event type, shared with all events */
   360     SDL_WindowEvent window;         /**< Window event data */
   361     SDL_KeyboardEvent key;          /**< Keyboard event data */
   362     SDL_TextEditingEvent edit;      /**< Text editing event data */
   363     SDL_TextInputEvent text;        /**< Text input event data */
   364     SDL_MouseMotionEvent motion;    /**< Mouse motion event data */
   365     SDL_MouseButtonEvent button;    /**< Mouse button event data */
   366     SDL_MouseWheelEvent wheel;      /**< Mouse wheel event data */
   367     SDL_JoyAxisEvent jaxis;         /**< Joystick axis event data */
   368     SDL_JoyBallEvent jball;         /**< Joystick ball event data */
   369     SDL_JoyHatEvent jhat;           /**< Joystick hat event data */
   370     SDL_JoyButtonEvent jbutton;     /**< Joystick button event data */
   371     SDL_QuitEvent quit;             /**< Quit request event data */
   372     SDL_UserEvent user;             /**< Custom event data */
   373     SDL_SysWMEvent syswm;           /**< System dependent window event data */
   374     SDL_ProximityEvent proximity;   /**< Proximity In or Out event */
   375 
   376     /** Temporarily here for backwards compatibility */
   377     /*@{*/
   378 #ifndef SDL_NO_COMPAT
   379     SDL_ActiveEvent active;
   380     SDL_ResizeEvent resize;
   381 #endif
   382     /*@}*/
   383 } SDL_Event;
   384 
   385 
   386 /* Function prototypes */
   387 
   388 /**
   389  *  Pumps the event loop, gathering events from the input devices.
   390  *  
   391  *  This function updates the event queue and internal input device state.
   392  *  
   393  *  This should only be run in the thread that sets the video mode.
   394  */
   395 extern DECLSPEC void SDLCALL SDL_PumpEvents(void);
   396 
   397 /*@{*/
   398 typedef enum
   399 {
   400     SDL_ADDEVENT,
   401     SDL_PEEKEVENT,
   402     SDL_GETEVENT
   403 } SDL_eventaction;
   404 
   405 /**
   406  *  Checks the event queue for messages and optionally returns them.
   407  *  
   408  *  If \c action is ::SDL_ADDEVENT, up to \c numevents events will be added to
   409  *  the back of the event queue.
   410  *  
   411  *  If \c action is ::SDL_PEEKEVENT, up to \c numevents events at the front
   412  *  of the event queue, matching \c mask, will be returned and will not
   413  *  be removed from the queue.
   414  *  
   415  *  If \c action is ::SDL_GETEVENT, up to \c numevents events at the front 
   416  *  of the event queue, matching \c mask, will be returned and will be
   417  *  removed from the queue.
   418  *  
   419  *  \return The number of events actually stored, or -1 if there was an error.
   420  *  
   421  *  This function is thread-safe.
   422  */
   423 extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents,
   424                                            SDL_eventaction action,
   425                                            Uint32 minType, Uint32 maxType);
   426 /*@}*/
   427 
   428 /**
   429  *  Checks to see if certain event types are in the event queue.
   430  */
   431 extern DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type);
   432 extern DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType);
   433 
   434 /**
   435  *  This function clears events from the event queue
   436  */
   437 extern DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type);
   438 extern DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType);
   439 
   440 /**
   441  *  \brief Polls for currently pending events.
   442  *  
   443  *  \return 1 if there are any pending events, or 0 if there are none available.
   444  *  
   445  *  \param event If not NULL, the next event is removed from the queue and 
   446  *               stored in that area.
   447  */
   448 extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
   449 
   450 /**
   451  *  \brief Waits indefinitely for the next available event.
   452  *  
   453  *  \return 1, or 0 if there was an error while waiting for events.
   454  *   
   455  *  \param event If not NULL, the next event is removed from the queue and 
   456  *               stored in that area.
   457  */
   458 extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event * event);
   459 
   460 /**
   461  *  \brief Waits until the specified timeout (in milliseconds) for the next 
   462  *         available event.
   463  *  
   464  *  \return 1, or 0 if there was an error while waiting for events.
   465  *  
   466  *  \param event If not NULL, the next event is removed from the queue and 
   467  *               stored in that area.
   468  */
   469 extern DECLSPEC int SDLCALL SDL_WaitEventTimeout(SDL_Event * event,
   470                                                  int timeout);
   471 
   472 /**
   473  *  \brief Add an event to the event queue.
   474  *  
   475  *  \return 1 on success, 0 if the event was filtered, or -1 if the event queue 
   476  *          was full or there was some other error.
   477  */
   478 extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event);
   479 
   480 typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event);
   481 
   482 /**
   483  *  Sets up a filter to process all events before they change internal state and
   484  *  are posted to the internal event queue.
   485  *  
   486  *  The filter is protypted as:
   487  *  \code
   488  *      int SDL_EventFilter(void *userdata, SDL_Event * event);
   489  *  \endcode
   490  *
   491  *  If the filter returns 1, then the event will be added to the internal queue.
   492  *  If it returns 0, then the event will be dropped from the queue, but the 
   493  *  internal state will still be updated.  This allows selective filtering of
   494  *  dynamically arriving events.
   495  *  
   496  *  \warning  Be very careful of what you do in the event filter function, as 
   497  *            it may run in a different thread!
   498  *  
   499  *  There is one caveat when dealing with the ::SDL_QUITEVENT event type.  The
   500  *  event filter is only called when the window manager desires to close the
   501  *  application window.  If the event filter returns 1, then the window will
   502  *  be closed, otherwise the window will remain open if possible.
   503  *
   504  *  If the quit event is generated by an interrupt signal, it will bypass the
   505  *  internal queue and be delivered to the application at the next event poll.
   506  */
   507 extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter,
   508                                                 void *userdata);
   509 
   510 /**
   511  *  Return the current event filter - can be used to "chain" filters.
   512  *  If there is no event filter set, this function returns SDL_FALSE.
   513  */
   514 extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter * filter,
   515                                                     void **userdata);
   516 
   517 /**
   518  *  Run the filter function on the current event queue, removing any
   519  *  events for which the filter returns 0.
   520  */
   521 extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter,
   522                                               void *userdata);
   523 
   524 /*@{*/
   525 #define SDL_QUERY	-1
   526 #define SDL_IGNORE	 0
   527 #define SDL_DISABLE	 0
   528 #define SDL_ENABLE	 1
   529 
   530 /**
   531  *  This function allows you to set the state of processing certain events.
   532  *   - If \c state is set to ::SDL_IGNORE, that event will be automatically 
   533  *     dropped from the event queue and will not event be filtered.
   534  *   - If \c state is set to ::SDL_ENABLE, that event will be processed 
   535  *     normally.
   536  *   - If \c state is set to ::SDL_QUERY, SDL_EventState() will return the 
   537  *     current processing state of the specified event.
   538  */
   539 extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint32 type, int state);
   540 /*@}*/
   541 #define SDL_GetEventState(type) SDL_EventState(type, SDL_QUERY)
   542 
   543 /**
   544  *  This function allocates a set of user-defined events, and returns
   545  *  the beginning event number for that set of events.
   546  *
   547  *  If there aren't enough user-defined events left, this function
   548  *  returns (Uint32)-1
   549  */
   550 extern DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents);
   551 
   552 /* Ends C function definitions when using C++ */
   553 #ifdef __cplusplus
   554 /* *INDENT-OFF* */
   555 }
   556 /* *INDENT-ON* */
   557 #endif
   558 #include "close_code.h"
   559 
   560 #endif /* _SDL_events_h */
   561 
   562 /* vi: set ts=4 sw=4 expandtab: */