diff options
Diffstat (limited to 'src/SDL12/include/SDL_events.h')
| -rw-r--r-- | src/SDL12/include/SDL_events.h | 333 |
1 files changed, 176 insertions, 157 deletions
diff --git a/src/SDL12/include/SDL_events.h b/src/SDL12/include/SDL_events.h index 9fe918c7..c94a30c9 100644 --- a/src/SDL12/include/SDL_events.h +++ b/src/SDL12/include/SDL_events.h @@ -1,6 +1,6 @@ /* SDL - Simple DirectMedia Layer - Copyright (C) 1997-2006 Sam Lantinga + Copyright (C) 1997-2009 Sam Lantinga This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public @@ -20,7 +20,10 @@ slouken@libsdl.org */ -/* Include file for SDL event handling */ +/** + * @file SDL_events.h + * Include file for SDL event handling + */ #ifndef _SDL_events_h #define _SDL_events_h @@ -39,45 +42,48 @@ extern "C" { #endif -/* General keyboard/mouse state definitions */ +/** @name General keyboard/mouse state definitions */ +/*@{*/ #define SDL_RELEASED 0 #define SDL_PRESSED 1 +/*@}*/ -/* Event enumerations */ +/** Event enumerations */ typedef enum { - SDL_NOEVENT = 0, /* Unused (do not remove) */ - SDL_ACTIVEEVENT, /* Application loses/gains visibility */ - SDL_KEYDOWN, /* Keys pressed */ - SDL_KEYUP, /* Keys released */ - SDL_MOUSEMOTION, /* Mouse moved */ - SDL_MOUSEBUTTONDOWN, /* Mouse button pressed */ - SDL_MOUSEBUTTONUP, /* Mouse button released */ - SDL_JOYAXISMOTION, /* Joystick axis motion */ - SDL_JOYBALLMOTION, /* Joystick trackball motion */ - SDL_JOYHATMOTION, /* Joystick hat position change */ - SDL_JOYBUTTONDOWN, /* Joystick button pressed */ - SDL_JOYBUTTONUP, /* Joystick button released */ - SDL_QUIT, /* User-requested quit */ - SDL_SYSWMEVENT, /* System specific event */ - SDL_EVENT_RESERVEDA, /* Reserved for future use.. */ - SDL_EVENT_RESERVEDB, /* Reserved for future use.. */ - SDL_VIDEORESIZE, /* User resized video mode */ - SDL_VIDEOEXPOSE, /* Screen needs to be redrawn */ - SDL_EVENT_RESERVED2, /* Reserved for future use.. */ - SDL_EVENT_RESERVED3, /* Reserved for future use.. */ - SDL_EVENT_RESERVED4, /* Reserved for future use.. */ - SDL_EVENT_RESERVED5, /* Reserved for future use.. */ - SDL_EVENT_RESERVED6, /* Reserved for future use.. */ - SDL_EVENT_RESERVED7, /* Reserved for future use.. */ - /* Events SDL_USEREVENT through SDL_MAXEVENTS-1 are for your use */ + SDL_NOEVENT = 0, /**< Unused (do not remove) */ + SDL_ACTIVEEVENT, /**< Application loses/gains visibility */ + SDL_KEYDOWN, /**< Keys pressed */ + SDL_KEYUP, /**< Keys released */ + SDL_MOUSEMOTION, /**< Mouse moved */ + SDL_MOUSEBUTTONDOWN, /**< Mouse button pressed */ + SDL_MOUSEBUTTONUP, /**< Mouse button released */ + SDL_JOYAXISMOTION, /**< Joystick axis motion */ + SDL_JOYBALLMOTION, /**< Joystick trackball motion */ + SDL_JOYHATMOTION, /**< Joystick hat position change */ + SDL_JOYBUTTONDOWN, /**< Joystick button pressed */ + SDL_JOYBUTTONUP, /**< Joystick button released */ + SDL_QUIT, /**< User-requested quit */ + SDL_SYSWMEVENT, /**< System specific event */ + SDL_EVENT_RESERVEDA, /**< Reserved for future use.. */ + SDL_EVENT_RESERVEDB, /**< Reserved for future use.. */ + SDL_VIDEORESIZE, /**< User resized video mode */ + SDL_VIDEOEXPOSE, /**< Screen needs to be redrawn */ + SDL_EVENT_RESERVED2, /**< Reserved for future use.. */ + SDL_EVENT_RESERVED3, /**< Reserved for future use.. */ + SDL_EVENT_RESERVED4, /**< Reserved for future use.. */ + SDL_EVENT_RESERVED5, /**< Reserved for future use.. */ + SDL_EVENT_RESERVED6, /**< Reserved for future use.. */ + SDL_EVENT_RESERVED7, /**< Reserved for future use.. */ + /** Events SDL_USEREVENT through SDL_MAXEVENTS-1 are for your use */ SDL_USEREVENT = 24, - /* This last event is only for bounding internal arrays - It is the number of bits in the event mask datatype -- Uint32 + /** This last event is only for bounding internal arrays + * It is the number of bits in the event mask datatype -- Uint32 */ SDL_NUMEVENTS = 32 } SDL_EventType; -/* Predefined event masks */ +/** @name Predefined event masks */ +/*@{*/ #define SDL_EVENTMASK(X) (1<<(X)) typedef enum { SDL_ACTIVEEVENTMASK = SDL_EVENTMASK(SDL_ACTIVEEVENT), @@ -107,108 +113,109 @@ typedef enum { SDL_SYSWMEVENTMASK = SDL_EVENTMASK(SDL_SYSWMEVENT) } SDL_EventMask ; #define SDL_ALLEVENTS 0xFFFFFFFF +/*@}*/ -/* Application visibility event structure */ +/** Application visibility event structure */ typedef struct SDL_ActiveEvent { - Uint8 type; /* SDL_ACTIVEEVENT */ - Uint8 gain; /* Whether given states were gained or lost (1/0) */ - Uint8 state; /* A mask of the focus states */ + Uint8 type; /**< SDL_ACTIVEEVENT */ + Uint8 gain; /**< Whether given states were gained or lost (1/0) */ + Uint8 state; /**< A mask of the focus states */ } SDL_ActiveEvent; -/* Keyboard event structure */ +/** Keyboard event structure */ typedef struct SDL_KeyboardEvent { - Uint8 type; /* SDL_KEYDOWN or SDL_KEYUP */ - Uint8 which; /* The keyboard device index */ - Uint8 state; /* SDL_PRESSED or SDL_RELEASED */ + Uint8 type; /**< SDL_KEYDOWN or SDL_KEYUP */ + Uint8 which; /**< The keyboard device index */ + Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ SDL_keysym keysym; } SDL_KeyboardEvent; -/* Mouse motion event structure */ +/** Mouse motion event structure */ typedef struct SDL_MouseMotionEvent { - Uint8 type; /* SDL_MOUSEMOTION */ - Uint8 which; /* The mouse device index */ - Uint8 state; /* The current button state */ - Uint16 x, y; /* The X/Y coordinates of the mouse */ - Sint16 xrel; /* The relative motion in the X direction */ - Sint16 yrel; /* The relative motion in the Y direction */ + Uint8 type; /**< SDL_MOUSEMOTION */ + Uint8 which; /**< The mouse device index */ + Uint8 state; /**< The current button state */ + Uint16 x, y; /**< The X/Y coordinates of the mouse */ + Sint16 xrel; /**< The relative motion in the X direction */ + Sint16 yrel; /**< The relative motion in the Y direction */ } SDL_MouseMotionEvent; -/* Mouse button event structure */ +/** Mouse button event structure */ typedef struct SDL_MouseButtonEvent { - Uint8 type; /* SDL_MOUSEBUTTONDOWN or SDL_MOUSEBUTTONUP */ - Uint8 which; /* The mouse device index */ - Uint8 button; /* The mouse button index */ - Uint8 state; /* SDL_PRESSED or SDL_RELEASED */ - Uint16 x, y; /* The X/Y coordinates of the mouse at press time */ + Uint8 type; /**< SDL_MOUSEBUTTONDOWN or SDL_MOUSEBUTTONUP */ + Uint8 which; /**< The mouse device index */ + Uint8 button; /**< The mouse button index */ + Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ + Uint16 x, y; /**< The X/Y coordinates of the mouse at press time */ } SDL_MouseButtonEvent; -/* Joystick axis motion event structure */ +/** Joystick axis motion event structure */ typedef struct SDL_JoyAxisEvent { - Uint8 type; /* SDL_JOYAXISMOTION */ - Uint8 which; /* The joystick device index */ - Uint8 axis; /* The joystick axis index */ - Sint16 value; /* The axis value (range: -32768 to 32767) */ + Uint8 type; /**< SDL_JOYAXISMOTION */ + Uint8 which; /**< The joystick device index */ + Uint8 axis; /**< The joystick axis index */ + Sint16 value; /**< The axis value (range: -32768 to 32767) */ } SDL_JoyAxisEvent; -/* Joystick trackball motion event structure */ +/** Joystick trackball motion event structure */ typedef struct SDL_JoyBallEvent { - Uint8 type; /* SDL_JOYBALLMOTION */ - Uint8 which; /* The joystick device index */ - Uint8 ball; /* The joystick trackball index */ - Sint16 xrel; /* The relative motion in the X direction */ - Sint16 yrel; /* The relative motion in the Y direction */ + Uint8 type; /**< SDL_JOYBALLMOTION */ + Uint8 which; /**< The joystick device index */ + Uint8 ball; /**< The joystick trackball index */ + Sint16 xrel; /**< The relative motion in the X direction */ + Sint16 yrel; /**< The relative motion in the Y direction */ } SDL_JoyBallEvent; -/* Joystick hat position change event structure */ +/** Joystick hat position change event structure */ typedef struct SDL_JoyHatEvent { - Uint8 type; /* SDL_JOYHATMOTION */ - Uint8 which; /* The joystick device index */ - Uint8 hat; /* The joystick hat index */ - Uint8 value; /* The hat position value: - SDL_HAT_LEFTUP SDL_HAT_UP SDL_HAT_RIGHTUP - SDL_HAT_LEFT SDL_HAT_CENTERED SDL_HAT_RIGHT - SDL_HAT_LEFTDOWN SDL_HAT_DOWN SDL_HAT_RIGHTDOWN - Note that zero means the POV is centered. - */ + Uint8 type; /**< SDL_JOYHATMOTION */ + Uint8 which; /**< The joystick device index */ + Uint8 hat; /**< The joystick hat index */ + Uint8 value; /**< The hat position value: + * SDL_HAT_LEFTUP SDL_HAT_UP SDL_HAT_RIGHTUP + * SDL_HAT_LEFT SDL_HAT_CENTERED SDL_HAT_RIGHT + * SDL_HAT_LEFTDOWN SDL_HAT_DOWN SDL_HAT_RIGHTDOWN + * Note that zero means the POV is centered. + */ } SDL_JoyHatEvent; -/* Joystick button event structure */ +/** Joystick button event structure */ typedef struct SDL_JoyButtonEvent { - Uint8 type; /* SDL_JOYBUTTONDOWN or SDL_JOYBUTTONUP */ - Uint8 which; /* The joystick device index */ - Uint8 button; /* The joystick button index */ - Uint8 state; /* SDL_PRESSED or SDL_RELEASED */ + Uint8 type; /**< SDL_JOYBUTTONDOWN or SDL_JOYBUTTONUP */ + Uint8 which; /**< The joystick device index */ + Uint8 button; /**< The joystick button index */ + Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ } SDL_JoyButtonEvent; -/* The "window resized" event - When you get this event, you are responsible for setting a new video - mode with the new width and height. +/** The "window resized" event + * When you get this event, you are responsible for setting a new video + * mode with the new width and height. */ typedef struct SDL_ResizeEvent { - Uint8 type; /* SDL_VIDEORESIZE */ - int w; /* New width */ - int h; /* New height */ + Uint8 type; /**< SDL_VIDEORESIZE */ + int w; /**< New width */ + int h; /**< New height */ } SDL_ResizeEvent; -/* The "screen redraw" event */ +/** The "screen redraw" event */ typedef struct SDL_ExposeEvent { - Uint8 type; /* SDL_VIDEOEXPOSE */ + Uint8 type; /**< SDL_VIDEOEXPOSE */ } SDL_ExposeEvent; -/* The "quit requested" event */ +/** The "quit requested" event */ typedef struct SDL_QuitEvent { - Uint8 type; /* SDL_QUIT */ + Uint8 type; /**< SDL_QUIT */ } SDL_QuitEvent; -/* A user-defined event type */ +/** A user-defined event type */ typedef struct SDL_UserEvent { - Uint8 type; /* SDL_USEREVENT through SDL_NUMEVENTS-1 */ - int code; /* User defined event code */ - void *data1; /* User defined data pointer */ - void *data2; /* User defined data pointer */ + Uint8 type; /**< SDL_USEREVENT through SDL_NUMEVENTS-1 */ + int code; /**< User defined event code */ + void *data1; /**< User defined data pointer */ + void *data2; /**< User defined data pointer */ } SDL_UserEvent; -/* If you want to use this event, you should include SDL_syswm.h */ +/** If you want to use this event, you should include SDL_syswm.h */ struct SDL_SysWMmsg; typedef struct SDL_SysWMmsg SDL_SysWMmsg; typedef struct SDL_SysWMEvent { @@ -216,7 +223,7 @@ typedef struct SDL_SysWMEvent { SDL_SysWMmsg *msg; } SDL_SysWMEvent; -/* General event structure */ +/** General event structure */ typedef union SDL_Event { Uint8 type; SDL_ActiveEvent active; @@ -237,97 +244,109 @@ typedef union SDL_Event { /* Function prototypes */ -/* Pumps the event loop, gathering events from the input devices. - This function updates the event queue and internal input device state. - This should only be run in the thread that sets the video mode. -*/ +/** Pumps the event loop, gathering events from the input devices. + * This function updates the event queue and internal input device state. + * This should only be run in the thread that sets the video mode. + */ extern DECLSPEC void SDLCALL SDL_PumpEvents(void); -/* Checks the event queue for messages and optionally returns them. - If 'action' is SDL_ADDEVENT, up to 'numevents' events will be added to - the back of the event queue. - If 'action' is SDL_PEEKEVENT, up to 'numevents' events at the front - of the event queue, matching 'mask', will be returned and will not - be removed from the queue. - If 'action' is SDL_GETEVENT, up to 'numevents' events at the front - of the event queue, matching 'mask', will be returned and will be - removed from the queue. - This function returns the number of events actually stored, or -1 - if there was an error. This function is thread-safe. -*/ typedef enum { SDL_ADDEVENT, SDL_PEEKEVENT, SDL_GETEVENT } SDL_eventaction; -/* */ + +/** + * Checks the event queue for messages and optionally returns them. + * + * If 'action' is SDL_ADDEVENT, up to 'numevents' events will be added to + * the back of the event queue. + * If 'action' is SDL_PEEKEVENT, up to 'numevents' events at the front + * of the event queue, matching 'mask', will be returned and will not + * be removed from the queue. + * If 'action' is SDL_GETEVENT, up to 'numevents' events at the front + * of the event queue, matching 'mask', will be returned and will be + * removed from the queue. + * + * @return + * This function returns the number of events actually stored, or -1 + * if there was an error. + * + * This function is thread-safe. + */ extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event *events, int numevents, SDL_eventaction action, Uint32 mask); -/* Polls for currently pending events, and returns 1 if there are any pending - events, or 0 if there are none available. If 'event' is not NULL, the next - event is removed from the queue and stored in that area. +/** Polls for currently pending events, and returns 1 if there are any pending + * events, or 0 if there are none available. If 'event' is not NULL, the next + * event is removed from the queue and stored in that area. */ extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event *event); -/* Waits indefinitely for the next available event, returning 1, or 0 if there - was an error while waiting for events. If 'event' is not NULL, the next - event is removed from the queue and stored in that area. +/** Waits indefinitely for the next available event, returning 1, or 0 if there + * was an error while waiting for events. If 'event' is not NULL, the next + * event is removed from the queue and stored in that area. */ extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event *event); -/* Add an event to the event queue. - This function returns 0 on success, or -1 if the event queue was full - or there was some other error. +/** Add an event to the event queue. + * This function returns 0 on success, or -1 if the event queue was full + * or there was some other error. */ extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event *event); -/* - This function sets up a filter to process all events before they - change internal state and are posted to the internal event queue. - - The filter is protypted as: -*/ +/** @name Event Filtering */ +/*@{*/ typedef int (SDLCALL *SDL_EventFilter)(const SDL_Event *event); -/* - If the filter returns 1, then the event will be added to the internal queue. - If it returns 0, then the event will be dropped from the queue, but the - internal state will still be updated. This allows selective filtering of - dynamically arriving events. - - WARNING: Be very careful of what you do in the event filter function, as - it may run in a different thread! - - There is one caveat when dealing with the SDL_QUITEVENT event type. The - event filter is only called when the window manager desires to close the - application window. If the event filter returns 1, then the window will - be closed, otherwise the window will remain open if possible. - If the quit event is generated by an interrupt signal, it will bypass the - internal queue and be delivered to the application at the next event poll. -*/ +/** + * This function sets up a filter to process all events before they + * change internal state and are posted to the internal event queue. + * + * The filter is protypted as: + * @code typedef int (SDLCALL *SDL_EventFilter)(const SDL_Event *event); @endcode + * + * If the filter returns 1, then the event will be added to the internal queue. + * If it returns 0, then the event will be dropped from the queue, but the + * internal state will still be updated. This allows selective filtering of + * dynamically arriving events. + * + * @warning Be very careful of what you do in the event filter function, as + * it may run in a different thread! + * + * There is one caveat when dealing with the SDL_QUITEVENT event type. The + * event filter is only called when the window manager desires to close the + * application window. If the event filter returns 1, then the window will + * be closed, otherwise the window will remain open if possible. + * If the quit event is generated by an interrupt signal, it will bypass the + * internal queue and be delivered to the application at the next event poll. + */ extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter); -/* - Return the current event filter - can be used to "chain" filters. - If there is no event filter set, this function returns NULL. -*/ +/** + * Return the current event filter - can be used to "chain" filters. + * If there is no event filter set, this function returns NULL. + */ extern DECLSPEC SDL_EventFilter SDLCALL SDL_GetEventFilter(void); +/*@}*/ -/* - This function allows you to set the state of processing certain events. - If 'state' is set to SDL_IGNORE, that event will be automatically dropped - from the event queue and will not event be filtered. - If 'state' is set to SDL_ENABLE, that event will be processed normally. - If 'state' is set to SDL_QUERY, SDL_EventState() will return the - current processing state of the specified event. -*/ +/** @name Event State */ +/*@{*/ #define SDL_QUERY -1 #define SDL_IGNORE 0 #define SDL_DISABLE 0 #define SDL_ENABLE 1 +/*@}*/ + +/** +* This function allows you to set the state of processing certain events. +* If 'state' is set to SDL_IGNORE, that event will be automatically dropped +* from the event queue and will not event be filtered. +* If 'state' is set to SDL_ENABLE, that event will be processed normally. +* If 'state' is set to SDL_QUERY, SDL_EventState() will return the +* current processing state of the specified event. +*/ extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint8 type, int state); - /* Ends C function definitions when using C++ */ #ifdef __cplusplus } |