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