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