include/SDL_events.h
author Jiang Jiang <gzjjgod@gmail.com>
Wed, 01 Jul 2009 07:33:58 +0000
branchgsoc2009_IME
changeset 3132 88861448961f
parent 3072 9da8f57ab92c
permissions -rw-r--r--
Add SDL_TEXTEDTING event to inform application about marked text.
     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_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_PROXIMITYIN,            /**< Proximity In event */
    76     SDL_PROXIMITYOUT,           /**< Proximity Out event */
    77     SDL_EVENT_RESERVED1,
    78     SDL_EVENT_RESERVED2,
    79     SDL_EVENT_RESERVED3,
    80     SDL_TEXTEDITING,            /**< Reserved for future use... */
    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_TEXTINPUTMASK = SDL_EVENTMASK(SDL_TEXTINPUT),
   102     SDL_MOUSEMOTIONMASK = SDL_EVENTMASK(SDL_MOUSEMOTION),
   103     SDL_MOUSEBUTTONDOWNMASK = SDL_EVENTMASK(SDL_MOUSEBUTTONDOWN),
   104     SDL_MOUSEBUTTONUPMASK = SDL_EVENTMASK(SDL_MOUSEBUTTONUP),
   105     SDL_MOUSEWHEELMASK = SDL_EVENTMASK(SDL_MOUSEWHEEL),
   106     SDL_MOUSEEVENTMASK = SDL_EVENTMASK(SDL_MOUSEMOTION) |
   107         SDL_EVENTMASK(SDL_MOUSEBUTTONDOWN) | SDL_EVENTMASK(SDL_MOUSEBUTTONUP),
   108     SDL_JOYAXISMOTIONMASK = SDL_EVENTMASK(SDL_JOYAXISMOTION),
   109     SDL_JOYBALLMOTIONMASK = SDL_EVENTMASK(SDL_JOYBALLMOTION),
   110     SDL_JOYHATMOTIONMASK = SDL_EVENTMASK(SDL_JOYHATMOTION),
   111     SDL_JOYBUTTONDOWNMASK = SDL_EVENTMASK(SDL_JOYBUTTONDOWN),
   112     SDL_JOYBUTTONUPMASK = SDL_EVENTMASK(SDL_JOYBUTTONUP),
   113     SDL_JOYEVENTMASK = SDL_EVENTMASK(SDL_JOYAXISMOTION) |
   114         SDL_EVENTMASK(SDL_JOYBALLMOTION) |
   115         SDL_EVENTMASK(SDL_JOYHATMOTION) |
   116         SDL_EVENTMASK(SDL_JOYBUTTONDOWN) | SDL_EVENTMASK(SDL_JOYBUTTONUP),
   117     SDL_QUITMASK = SDL_EVENTMASK(SDL_QUIT),
   118     SDL_SYSWMEVENTMASK = SDL_EVENTMASK(SDL_SYSWMEVENT),
   119     SDL_PROXIMITYINMASK = SDL_EVENTMASK(SDL_PROXIMITYIN),
   120     SDL_PROXIMITYOUTMASK = SDL_EVENTMASK(SDL_PROXIMITYOUT),
   121     SDL_TEXTEDITINGMASK = SDL_EVENTMASK(SDL_TEXTEDITING)
   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     Uint8 event;            /**< SDL_WindowEventID */
   134     int data1;              /**< event dependent data */
   135     int data2;              /**< event dependent data */
   136     SDL_WindowID windowID;  /**< The associated window */
   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     Uint8 which;            /**< The keyboard device index */
   148     Uint8 state;            /**< SDL_PRESSED or SDL_RELEASED */
   149     SDL_keysym keysym;      /**< The key that was pressed or released */
   150     SDL_WindowID windowID;  /**< The window with keyboard focus, if any */
   151 } SDL_KeyboardEvent;
   152 
   153 /**
   154  * \struct SDL_TextInputEvent
   155  *
   156  * \brief Keyboard text input event structure (event.text.*)
   157  */
   158 #define SDL_TEXTINPUTEVENT_TEXT_SIZE (32)
   159 typedef struct SDL_TextInputEvent
   160 {
   161     Uint8 type;                               /**< SDL_TEXTINPUT */
   162     Uint8 which;                              /**< The keyboard device index */
   163     char text[SDL_TEXTINPUTEVENT_TEXT_SIZE];  /**< The input text */
   164     SDL_WindowID windowID;                    /**< The window with keyboard focus, if any */
   165 } SDL_TextInputEvent;
   166 
   167 /**
   168  * \struct SDL_TextEditingEvent
   169  *
   170  * \brief Keyboard text editing event structure (event.edit.*)
   171  */
   172 #define SDL_TEXTEDITINGEVENT_TEXT_SIZE (32)
   173 typedef struct SDL_TextEditingEvent
   174 {
   175     Uint8 type;                                 /**< SDL_TEXTEDITING */
   176     char text[SDL_TEXTEDITINGEVENT_TEXT_SIZE];  /**< The editing text */
   177     int start;                                  /**< The start cursor of selected editing text */
   178     int length;                                 /**< The length of selected editing text */
   179 } SDL_TextEditingEvent;
   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     Uint8 which;            /**< The mouse device index */
   190     Uint8 state;            /**< The current button state */
   191     int x;                  /**< X coordinate, relative to window */
   192     int y;                  /**< Y coordinate, relative to window */
   193     int z;                  /**< Z coordinate, for future use */
   194     int pressure;           /**< Pressure reported by tablets */
   195     int pressure_max;       /**< Maximum value of the pressure reported by the device */
   196     int pressure_min;       /**< Minimum value of the pressure reported by the device */
   197     int rotation;           /**< For future use */
   198     int tilt;               /**< For future use */
   199     int cursor;             /**< The cursor being used in the event */
   200     int xrel;               /**< The relative motion in the X direction */
   201     int yrel;               /**< The relative motion in the Y direction */
   202     SDL_WindowID windowID;  /**< The window with mouse focus, if any */
   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     Uint8 which;            /**< The mouse device index */
   214     Uint8 button;           /**< The mouse button index */
   215     Uint8 state;            /**< SDL_PRESSED or SDL_RELEASED */
   216     int x;                  /**< X coordinate, relative to window */
   217     int y;                  /**< Y coordinate, relative to window */
   218     SDL_WindowID windowID;  /**< The window with mouse focus, if any */
   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     Uint8 which;            /**< The mouse device index */
   230     int x;                  /**< The amount scrolled horizontally */
   231     int y;                  /**< The amount scrolled vertically */
   232     SDL_WindowID windowID;  /**< The window with mouse focus, if any */
   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     int code;               /**< User defined event code */
   312     void *data1;            /**< User defined data pointer */
   313     void *data2;            /**< User defined data pointer */
   314     SDL_WindowID windowID;  /**< The associated window if any*/
   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 /* Typedefs for backwards compatibility */
   333 typedef struct SDL_ActiveEvent
   334 {
   335     Uint8 type;
   336     Uint8 gain;
   337     Uint8 state;
   338 } SDL_ActiveEvent;
   339 typedef struct SDL_ResizeEvent
   340 {
   341     Uint8 type;
   342     int w;
   343     int h;
   344 } SDL_ResizeEvent;
   345 
   346 typedef struct SDL_ProximityEvent
   347 {
   348     Uint8 type;
   349     Uint8 which;
   350     int cursor;
   351     int x;
   352     int y;
   353 } SDL_ProximityEvent;
   354 
   355 /**
   356  * \union SDL_Event
   357  *
   358  * \brief General event structure
   359  */
   360 typedef union SDL_Event
   361 {
   362     Uint8 type;                     /**< Event type, shared with all events */
   363     SDL_WindowEvent window;         /**< Window event data */
   364     SDL_KeyboardEvent key;          /**< Keyboard event data */
   365     SDL_TextInputEvent text;        /**< Text input event data */
   366     SDL_MouseMotionEvent motion;    /**< Mouse motion event data */
   367     SDL_MouseButtonEvent button;    /**< Mouse button event data */
   368     SDL_MouseWheelEvent wheel;      /**< Mouse wheel event data */
   369     SDL_JoyAxisEvent jaxis;         /**< Joystick axis event data */
   370     SDL_JoyBallEvent jball;         /**< Joystick ball event data */
   371     SDL_JoyHatEvent jhat;           /**< Joystick hat event data */
   372     SDL_JoyButtonEvent jbutton;     /**< Joystick button event data */
   373     SDL_QuitEvent quit;             /**< Quit request event data */
   374     SDL_UserEvent user;             /**< Custom event data */
   375     SDL_SysWMEvent syswm;           /**< System dependent window event data */
   376     SDL_ProximityEvent proximity;   /**< Proximity In or Out event */
   377     SDL_TextEditingEvent edit;      /**< Text editing event data */
   378 
   379     /* Temporarily here for backwards compatibility */
   380     SDL_ActiveEvent active;
   381     SDL_ResizeEvent resize;
   382 } SDL_Event;
   383 
   384 
   385 /* Function prototypes */
   386 
   387 /* Pumps the event loop, gathering events from the input devices.
   388    This function updates the event queue and internal input device state.
   389    This should only be run in the thread that sets the video mode.
   390 */
   391 extern DECLSPEC void SDLCALL SDL_PumpEvents(void);
   392 
   393 /* Checks the event queue for messages and optionally returns them.
   394    If 'action' is SDL_ADDEVENT, up to 'numevents' events will be added to
   395    the back of the event queue.
   396    If 'action' is SDL_PEEKEVENT, up to 'numevents' events at the front
   397    of the event queue, matching 'mask', will be returned and will not
   398    be removed from the queue.
   399    If 'action' is SDL_GETEVENT, up to 'numevents' events at the front 
   400    of the event queue, matching 'mask', will be returned and will be
   401    removed from the queue.
   402    This function returns the number of events actually stored, or -1
   403    if there was an error.  This function is thread-safe.
   404 */
   405 typedef enum
   406 {
   407     SDL_ADDEVENT,
   408     SDL_PEEKEVENT,
   409     SDL_GETEVENT
   410 } SDL_eventaction;
   411 /* */
   412 extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents,
   413                                            SDL_eventaction action,
   414                                            Uint32 mask);
   415 
   416 /* Checks to see if certain event types are in the event queue.
   417  */
   418 extern DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 mask);
   419 
   420 /* Polls for currently pending events, and returns 1 if there are any pending
   421    events, or 0 if there are none available.  If 'event' is not NULL, the next
   422    event is removed from the queue and stored in that area.
   423  */
   424 extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
   425 
   426 /* Waits indefinitely for the next available event, returning 1, or 0 if there
   427    was an error while waiting for events.  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_WaitEvent(SDL_Event * event);
   431 
   432 /* Waits until the specified timeout (in milliseconds) for the next available
   433    event, returning 1, or 0 if there was an error while waiting for events. If
   434    'event' is not NULL, the next event is removed from the queue and stored in
   435    that area.
   436  */
   437 extern DECLSPEC int SDLCALL SDL_WaitEventTimeout(SDL_Event * event,
   438                                                  int timeout);
   439 
   440 /* Add an event to the event queue.
   441    This function returns 1 on success, 0 if the event was filtered,
   442    or -1 if the event queue was full or there was some other error.
   443  */
   444 extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event);
   445 
   446 /*
   447   This function sets up a filter to process all events before they
   448   change internal state and are posted to the internal event queue.
   449 
   450   The filter is protypted as:
   451 */
   452 typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event);
   453 /*
   454   If the filter returns 1, then the event will be added to the internal queue.
   455   If it returns 0, then the event will be dropped from the queue, but the 
   456   internal state will still be updated.  This allows selective filtering of
   457   dynamically arriving events.
   458 
   459   WARNING:  Be very careful of what you do in the event filter function, as 
   460             it may run in a different thread!
   461 
   462   There is one caveat when dealing with the SDL_QUITEVENT event type.  The
   463   event filter is only called when the window manager desires to close the
   464   application window.  If the event filter returns 1, then the window will
   465   be closed, otherwise the window will remain open if possible.
   466   If the quit event is generated by an interrupt signal, it will bypass the
   467   internal queue and be delivered to the application at the next event poll.
   468 */
   469 extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter,
   470                                                 void *userdata);
   471 
   472 /*
   473   Return the current event filter - can be used to "chain" filters.
   474   If there is no event filter set, this function returns SDL_FALSE.
   475 */
   476 extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter * filter,
   477                                                     void **userdata);
   478 
   479 /*
   480   Run the filter function on the current event queue, removing any
   481   events for which the filter returns 0.
   482 */
   483 extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter,
   484                                               void *userdata);
   485 
   486 /*
   487   This function allows you to set the state of processing certain events.
   488   If 'state' is set to SDL_IGNORE, that event will be automatically dropped
   489   from the event queue and will not event be filtered.
   490   If 'state' is set to SDL_ENABLE, that event will be processed normally.
   491   If 'state' is set to SDL_QUERY, SDL_EventState() will return the 
   492   current processing state of the specified event.
   493 */
   494 #define SDL_QUERY	-1
   495 #define SDL_IGNORE	 0
   496 #define SDL_DISABLE	 0
   497 #define SDL_ENABLE	 1
   498 extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint8 type, int state);
   499 
   500 
   501 /* Ends C function definitions when using C++ */
   502 #ifdef __cplusplus
   503 /* *INDENT-OFF* */
   504 }
   505 /* *INDENT-ON* */
   506 #endif
   507 #include "close_code.h"
   508 
   509 #endif /* _SDL_events_h */
   510 
   511 /* vi: set ts=4 sw=4 expandtab: */