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