SDL Library
Embed:
(wiki syntax)
Show/hide line numbers
SDL_events.h
Go to the documentation of this file.
00001 /* 00002 Simple DirectMedia Layer 00003 Copyright (C) 1997-2014 Sam Lantinga <slouken@libsdl.org> 00004 00005 This software is provided 'as-is', without any express or implied 00006 warranty. In no event will the authors be held liable for any damages 00007 arising from the use of this software. 00008 00009 Permission is granted to anyone to use this software for any purpose, 00010 including commercial applications, and to alter it and redistribute it 00011 freely, subject to the following restrictions: 00012 00013 1. The origin of this software must not be misrepresented; you must not 00014 claim that you wrote the original software. If you use this software 00015 in a product, an acknowledgment in the product documentation would be 00016 appreciated but is not required. 00017 2. Altered source versions must be plainly marked as such, and must not be 00018 misrepresented as being the original software. 00019 3. This notice may not be removed or altered from any source distribution. 00020 */ 00021 00022 /** 00023 * \file SDL_events.h 00024 * 00025 * Include file for SDL event handling. 00026 */ 00027 00028 #ifndef _SDL_events_h 00029 #define _SDL_events_h 00030 00031 #include "SDL_stdinc.h" 00032 #include "SDL_error.h" 00033 #include "SDL_video.h" 00034 #include "SDL_keyboard.h" 00035 #include "SDL_mouse.h" 00036 #include "SDL_joystick.h" 00037 #include "SDL_gamecontroller.h" 00038 #include "SDL_quit.h" 00039 #include "SDL_gesture.h" 00040 #include "SDL_touch.h" 00041 00042 #include "begin_code.h" 00043 /* Set up for C function definitions, even when using C++ */ 00044 #ifdef __cplusplus 00045 extern "C" { 00046 #endif 00047 00048 /* General keyboard/mouse state definitions */ 00049 #define SDL_RELEASED 0 00050 #define SDL_PRESSED 1 00051 00052 /** 00053 * \brief The types of events that can be delivered. 00054 */ 00055 typedef enum 00056 { 00057 SDL_FIRSTEVENT = 0, /**< Unused (do not remove) */ 00058 00059 /* Application events */ 00060 SDL_QUIT = 0x100, /**< User-requested quit */ 00061 00062 /* These application events have special meaning on iOS, see README-ios.txt for details */ 00063 SDL_APP_TERMINATING, /**< The application is being terminated by the OS 00064 Called on iOS in applicationWillTerminate() 00065 Called on Android in onDestroy() 00066 */ 00067 SDL_APP_LOWMEMORY, /**< The application is low on memory, free memory if possible. 00068 Called on iOS in applicationDidReceiveMemoryWarning() 00069 Called on Android in onLowMemory() 00070 */ 00071 SDL_APP_WILLENTERBACKGROUND, /**< The application is about to enter the background 00072 Called on iOS in applicationWillResignActive() 00073 Called on Android in onPause() 00074 */ 00075 SDL_APP_DIDENTERBACKGROUND, /**< The application did enter the background and may not get CPU for some time 00076 Called on iOS in applicationDidEnterBackground() 00077 Called on Android in onPause() 00078 */ 00079 SDL_APP_WILLENTERFOREGROUND, /**< The application is about to enter the foreground 00080 Called on iOS in applicationWillEnterForeground() 00081 Called on Android in onResume() 00082 */ 00083 SDL_APP_DIDENTERFOREGROUND, /**< The application is now interactive 00084 Called on iOS in applicationDidBecomeActive() 00085 Called on Android in onResume() 00086 */ 00087 00088 /* Window events */ 00089 SDL_WINDOWEVENT = 0x200, /**< Window state change */ 00090 SDL_SYSWMEVENT, /**< System specific event */ 00091 00092 /* Keyboard events */ 00093 SDL_KEYDOWN = 0x300, /**< Key pressed */ 00094 SDL_KEYUP, /**< Key released */ 00095 SDL_TEXTEDITING, /**< Keyboard text editing (composition) */ 00096 SDL_TEXTINPUT, /**< Keyboard text input */ 00097 00098 /* Mouse events */ 00099 SDL_MOUSEMOTION = 0x400, /**< Mouse moved */ 00100 SDL_MOUSEBUTTONDOWN, /**< Mouse button pressed */ 00101 SDL_MOUSEBUTTONUP, /**< Mouse button released */ 00102 SDL_MOUSEWHEEL, /**< Mouse wheel motion */ 00103 00104 /* Joystick events */ 00105 SDL_JOYAXISMOTION = 0x600, /**< Joystick axis motion */ 00106 SDL_JOYBALLMOTION, /**< Joystick trackball motion */ 00107 SDL_JOYHATMOTION, /**< Joystick hat position change */ 00108 SDL_JOYBUTTONDOWN, /**< Joystick button pressed */ 00109 SDL_JOYBUTTONUP, /**< Joystick button released */ 00110 SDL_JOYDEVICEADDED, /**< A new joystick has been inserted into the system */ 00111 SDL_JOYDEVICEREMOVED, /**< An opened joystick has been removed */ 00112 00113 /* Game controller events */ 00114 SDL_CONTROLLERAXISMOTION = 0x650, /**< Game controller axis motion */ 00115 SDL_CONTROLLERBUTTONDOWN, /**< Game controller button pressed */ 00116 SDL_CONTROLLERBUTTONUP, /**< Game controller button released */ 00117 SDL_CONTROLLERDEVICEADDED, /**< A new Game controller has been inserted into the system */ 00118 SDL_CONTROLLERDEVICEREMOVED, /**< An opened Game controller has been removed */ 00119 SDL_CONTROLLERDEVICEREMAPPED, /**< The controller mapping was updated */ 00120 00121 /* Touch events */ 00122 SDL_FINGERDOWN = 0x700, 00123 SDL_FINGERUP, 00124 SDL_FINGERMOTION, 00125 00126 /* Gesture events */ 00127 SDL_DOLLARGESTURE = 0x800, 00128 SDL_DOLLARRECORD, 00129 SDL_MULTIGESTURE, 00130 00131 /* Clipboard events */ 00132 SDL_CLIPBOARDUPDATE = 0x900, /**< The clipboard changed */ 00133 00134 /* Drag and drop events */ 00135 SDL_DROPFILE = 0x1000, /**< The system requests a file open */ 00136 00137 /* Render events */ 00138 SDL_RENDER_TARGETS_RESET = 0x2000, /**< The render targets have been reset */ 00139 00140 /** Events ::SDL_USEREVENT through ::SDL_LASTEVENT are for your use, 00141 * and should be allocated with SDL_RegisterEvents() 00142 */ 00143 SDL_USEREVENT = 0x8000, 00144 00145 /** 00146 * This last event is only for bounding internal arrays 00147 */ 00148 SDL_LASTEVENT = 0xFFFF 00149 } SDL_EventType; 00150 00151 /** 00152 * \brief Fields shared by every event 00153 */ 00154 typedef struct SDL_CommonEvent 00155 { 00156 Uint32 type; 00157 Uint32 timestamp; 00158 } SDL_CommonEvent; 00159 00160 /** 00161 * \brief Window state change event data (event.window.*) 00162 */ 00163 typedef struct SDL_WindowEvent 00164 { 00165 Uint32 type; /**< ::SDL_WINDOWEVENT */ 00166 Uint32 timestamp; 00167 Uint32 windowID; /**< The associated window */ 00168 Uint8 event; /**< ::SDL_WindowEventID */ 00169 Uint8 padding1; 00170 Uint8 padding2; 00171 Uint8 padding3; 00172 Sint32 data1; /**< event dependent data */ 00173 Sint32 data2; /**< event dependent data */ 00174 } SDL_WindowEvent; 00175 00176 /** 00177 * \brief Keyboard button event structure (event.key.*) 00178 */ 00179 typedef struct SDL_KeyboardEvent 00180 { 00181 Uint32 type; /**< ::SDL_KEYDOWN or ::SDL_KEYUP */ 00182 Uint32 timestamp; 00183 Uint32 windowID; /**< The window with keyboard focus, if any */ 00184 Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */ 00185 Uint8 repeat; /**< Non-zero if this is a key repeat */ 00186 Uint8 padding2; 00187 Uint8 padding3; 00188 SDL_Keysym keysym; /**< The key that was pressed or released */ 00189 } SDL_KeyboardEvent; 00190 00191 #define SDL_TEXTEDITINGEVENT_TEXT_SIZE (32) 00192 /** 00193 * \brief Keyboard text editing event structure (event.edit.*) 00194 */ 00195 typedef struct SDL_TextEditingEvent 00196 { 00197 Uint32 type; /**< ::SDL_TEXTEDITING */ 00198 Uint32 timestamp; 00199 Uint32 windowID; /**< The window with keyboard focus, if any */ 00200 char text[SDL_TEXTEDITINGEVENT_TEXT_SIZE]; /**< The editing text */ 00201 Sint32 start; /**< The start cursor of selected editing text */ 00202 Sint32 length; /**< The length of selected editing text */ 00203 } SDL_TextEditingEvent; 00204 00205 00206 #define SDL_TEXTINPUTEVENT_TEXT_SIZE (32) 00207 /** 00208 * \brief Keyboard text input event structure (event.text.*) 00209 */ 00210 typedef struct SDL_TextInputEvent 00211 { 00212 Uint32 type; /**< ::SDL_TEXTINPUT */ 00213 Uint32 timestamp; 00214 Uint32 windowID; /**< The window with keyboard focus, if any */ 00215 char text[SDL_TEXTINPUTEVENT_TEXT_SIZE]; /**< The input text */ 00216 } SDL_TextInputEvent; 00217 00218 /** 00219 * \brief Mouse motion event structure (event.motion.*) 00220 */ 00221 typedef struct SDL_MouseMotionEvent 00222 { 00223 Uint32 type; /**< ::SDL_MOUSEMOTION */ 00224 Uint32 timestamp; 00225 Uint32 windowID; /**< The window with mouse focus, if any */ 00226 Uint32 which; /**< The mouse instance id, or SDL_TOUCH_MOUSEID */ 00227 Uint32 state; /**< The current button state */ 00228 Sint32 x; /**< X coordinate, relative to window */ 00229 Sint32 y; /**< Y coordinate, relative to window */ 00230 Sint32 xrel; /**< The relative motion in the X direction */ 00231 Sint32 yrel; /**< The relative motion in the Y direction */ 00232 } SDL_MouseMotionEvent; 00233 00234 /** 00235 * \brief Mouse button event structure (event.button.*) 00236 */ 00237 typedef struct SDL_MouseButtonEvent 00238 { 00239 Uint32 type; /**< ::SDL_MOUSEBUTTONDOWN or ::SDL_MOUSEBUTTONUP */ 00240 Uint32 timestamp; 00241 Uint32 windowID; /**< The window with mouse focus, if any */ 00242 Uint32 which; /**< The mouse instance id, or SDL_TOUCH_MOUSEID */ 00243 Uint8 button; /**< The mouse button index */ 00244 Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */ 00245 Uint8 clicks; /**< 1 for single-click, 2 for double-click, etc. */ 00246 Uint8 padding1; 00247 Sint32 x; /**< X coordinate, relative to window */ 00248 Sint32 y; /**< Y coordinate, relative to window */ 00249 } SDL_MouseButtonEvent; 00250 00251 /** 00252 * \brief Mouse wheel event structure (event.wheel.*) 00253 */ 00254 typedef struct SDL_MouseWheelEvent 00255 { 00256 Uint32 type; /**< ::SDL_MOUSEWHEEL */ 00257 Uint32 timestamp; 00258 Uint32 windowID; /**< The window with mouse focus, if any */ 00259 Uint32 which; /**< The mouse instance id, or SDL_TOUCH_MOUSEID */ 00260 Sint32 x; /**< The amount scrolled horizontally, positive to the right and negative to the left */ 00261 Sint32 y; /**< The amount scrolled vertically, positive away from the user and negative toward the user */ 00262 } SDL_MouseWheelEvent; 00263 00264 /** 00265 * \brief Joystick axis motion event structure (event.jaxis.*) 00266 */ 00267 typedef struct SDL_JoyAxisEvent 00268 { 00269 Uint32 type; /**< ::SDL_JOYAXISMOTION */ 00270 Uint32 timestamp; 00271 SDL_JoystickID which; /**< The joystick instance id */ 00272 Uint8 axis; /**< The joystick axis index */ 00273 Uint8 padding1; 00274 Uint8 padding2; 00275 Uint8 padding3; 00276 Sint16 value; /**< The axis value (range: -32768 to 32767) */ 00277 Uint16 padding4; 00278 } SDL_JoyAxisEvent; 00279 00280 /** 00281 * \brief Joystick trackball motion event structure (event.jball.*) 00282 */ 00283 typedef struct SDL_JoyBallEvent 00284 { 00285 Uint32 type; /**< ::SDL_JOYBALLMOTION */ 00286 Uint32 timestamp; 00287 SDL_JoystickID which; /**< The joystick instance id */ 00288 Uint8 ball; /**< The joystick trackball index */ 00289 Uint8 padding1; 00290 Uint8 padding2; 00291 Uint8 padding3; 00292 Sint16 xrel; /**< The relative motion in the X direction */ 00293 Sint16 yrel; /**< The relative motion in the Y direction */ 00294 } SDL_JoyBallEvent; 00295 00296 /** 00297 * \brief Joystick hat position change event structure (event.jhat.*) 00298 */ 00299 typedef struct SDL_JoyHatEvent 00300 { 00301 Uint32 type; /**< ::SDL_JOYHATMOTION */ 00302 Uint32 timestamp; 00303 SDL_JoystickID which; /**< The joystick instance id */ 00304 Uint8 hat; /**< The joystick hat index */ 00305 Uint8 value; /**< The hat position value. 00306 * \sa ::SDL_HAT_LEFTUP ::SDL_HAT_UP ::SDL_HAT_RIGHTUP 00307 * \sa ::SDL_HAT_LEFT ::SDL_HAT_CENTERED ::SDL_HAT_RIGHT 00308 * \sa ::SDL_HAT_LEFTDOWN ::SDL_HAT_DOWN ::SDL_HAT_RIGHTDOWN 00309 * 00310 * Note that zero means the POV is centered. 00311 */ 00312 Uint8 padding1; 00313 Uint8 padding2; 00314 } SDL_JoyHatEvent; 00315 00316 /** 00317 * \brief Joystick button event structure (event.jbutton.*) 00318 */ 00319 typedef struct SDL_JoyButtonEvent 00320 { 00321 Uint32 type; /**< ::SDL_JOYBUTTONDOWN or ::SDL_JOYBUTTONUP */ 00322 Uint32 timestamp; 00323 SDL_JoystickID which; /**< The joystick instance id */ 00324 Uint8 button; /**< The joystick button index */ 00325 Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */ 00326 Uint8 padding1; 00327 Uint8 padding2; 00328 } SDL_JoyButtonEvent; 00329 00330 /** 00331 * \brief Joystick device event structure (event.jdevice.*) 00332 */ 00333 typedef struct SDL_JoyDeviceEvent 00334 { 00335 Uint32 type; /**< ::SDL_JOYDEVICEADDED or ::SDL_JOYDEVICEREMOVED */ 00336 Uint32 timestamp; 00337 Sint32 which; /**< The joystick device index for the ADDED event, instance id for the REMOVED event */ 00338 } SDL_JoyDeviceEvent; 00339 00340 00341 /** 00342 * \brief Game controller axis motion event structure (event.caxis.*) 00343 */ 00344 typedef struct SDL_ControllerAxisEvent 00345 { 00346 Uint32 type; /**< ::SDL_CONTROLLERAXISMOTION */ 00347 Uint32 timestamp; 00348 SDL_JoystickID which; /**< The joystick instance id */ 00349 Uint8 axis; /**< The controller axis (SDL_GameControllerAxis) */ 00350 Uint8 padding1; 00351 Uint8 padding2; 00352 Uint8 padding3; 00353 Sint16 value; /**< The axis value (range: -32768 to 32767) */ 00354 Uint16 padding4; 00355 } SDL_ControllerAxisEvent; 00356 00357 00358 /** 00359 * \brief Game controller button event structure (event.cbutton.*) 00360 */ 00361 typedef struct SDL_ControllerButtonEvent 00362 { 00363 Uint32 type; /**< ::SDL_CONTROLLERBUTTONDOWN or ::SDL_CONTROLLERBUTTONUP */ 00364 Uint32 timestamp; 00365 SDL_JoystickID which; /**< The joystick instance id */ 00366 Uint8 button; /**< The controller button (SDL_GameControllerButton) */ 00367 Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */ 00368 Uint8 padding1; 00369 Uint8 padding2; 00370 } SDL_ControllerButtonEvent; 00371 00372 00373 /** 00374 * \brief Controller device event structure (event.cdevice.*) 00375 */ 00376 typedef struct SDL_ControllerDeviceEvent 00377 { 00378 Uint32 type; /**< ::SDL_CONTROLLERDEVICEADDED, ::SDL_CONTROLLERDEVICEREMOVED, or ::SDL_CONTROLLERDEVICEREMAPPED */ 00379 Uint32 timestamp; 00380 Sint32 which; /**< The joystick device index for the ADDED event, instance id for the REMOVED or REMAPPED event */ 00381 } SDL_ControllerDeviceEvent; 00382 00383 00384 /** 00385 * \brief Touch finger event structure (event.tfinger.*) 00386 */ 00387 typedef struct SDL_TouchFingerEvent 00388 { 00389 Uint32 type; /**< ::SDL_FINGERMOTION or ::SDL_FINGERDOWN or ::SDL_FINGERUP */ 00390 Uint32 timestamp; 00391 SDL_TouchID touchId; /**< The touch device id */ 00392 SDL_FingerID fingerId; 00393 float x; /**< Normalized in the range 0...1 */ 00394 float y; /**< Normalized in the range 0...1 */ 00395 float dx; /**< Normalized in the range 0...1 */ 00396 float dy; /**< Normalized in the range 0...1 */ 00397 float pressure; /**< Normalized in the range 0...1 */ 00398 } SDL_TouchFingerEvent; 00399 00400 00401 /** 00402 * \brief Multiple Finger Gesture Event (event.mgesture.*) 00403 */ 00404 typedef struct SDL_MultiGestureEvent 00405 { 00406 Uint32 type; /**< ::SDL_MULTIGESTURE */ 00407 Uint32 timestamp; 00408 SDL_TouchID touchId; /**< The touch device index */ 00409 float dTheta; 00410 float dDist; 00411 float x; 00412 float y; 00413 Uint16 numFingers; 00414 Uint16 padding; 00415 } SDL_MultiGestureEvent; 00416 00417 00418 /** 00419 * \brief Dollar Gesture Event (event.dgesture.*) 00420 */ 00421 typedef struct SDL_DollarGestureEvent 00422 { 00423 Uint32 type; /**< ::SDL_DOLLARGESTURE */ 00424 Uint32 timestamp; 00425 SDL_TouchID touchId; /**< The touch device id */ 00426 SDL_GestureID gestureId; 00427 Uint32 numFingers; 00428 float error; 00429 float x; /**< Normalized center of gesture */ 00430 float y; /**< Normalized center of gesture */ 00431 } SDL_DollarGestureEvent; 00432 00433 00434 /** 00435 * \brief An event used to request a file open by the system (event.drop.*) 00436 * This event is disabled by default, you can enable it with SDL_EventState() 00437 * \note If you enable this event, you must free the filename in the event. 00438 */ 00439 typedef struct SDL_DropEvent 00440 { 00441 Uint32 type; /**< ::SDL_DROPFILE */ 00442 Uint32 timestamp; 00443 char *file; /**< The file name, which should be freed with SDL_free() */ 00444 } SDL_DropEvent; 00445 00446 00447 /** 00448 * \brief The "quit requested" event 00449 */ 00450 typedef struct SDL_QuitEvent 00451 { 00452 Uint32 type; /**< ::SDL_QUIT */ 00453 Uint32 timestamp; 00454 } SDL_QuitEvent; 00455 00456 /** 00457 * \brief OS Specific event 00458 */ 00459 typedef struct SDL_OSEvent 00460 { 00461 Uint32 type; /**< ::SDL_QUIT */ 00462 Uint32 timestamp; 00463 } SDL_OSEvent; 00464 00465 /** 00466 * \brief A user-defined event type (event.user.*) 00467 */ 00468 typedef struct SDL_UserEvent 00469 { 00470 Uint32 type; /**< ::SDL_USEREVENT through ::SDL_LASTEVENT-1 */ 00471 Uint32 timestamp; 00472 Uint32 windowID; /**< The associated window if any */ 00473 Sint32 code; /**< User defined event code */ 00474 void *data1; /**< User defined data pointer */ 00475 void *data2; /**< User defined data pointer */ 00476 } SDL_UserEvent; 00477 00478 00479 struct SDL_SysWMmsg; 00480 typedef struct SDL_SysWMmsg SDL_SysWMmsg; 00481 00482 /** 00483 * \brief A video driver dependent system event (event.syswm.*) 00484 * This event is disabled by default, you can enable it with SDL_EventState() 00485 * 00486 * \note If you want to use this event, you should include SDL_syswm.h. 00487 */ 00488 typedef struct SDL_SysWMEvent 00489 { 00490 Uint32 type; /**< ::SDL_SYSWMEVENT */ 00491 Uint32 timestamp; 00492 SDL_SysWMmsg *msg; /**< driver dependent data, defined in SDL_syswm.h */ 00493 } SDL_SysWMEvent; 00494 00495 /** 00496 * \brief General event structure 00497 */ 00498 typedef union SDL_Event 00499 { 00500 Uint32 type; /**< Event type, shared with all events */ 00501 SDL_CommonEvent common; /**< Common event data */ 00502 SDL_WindowEvent window; /**< Window event data */ 00503 SDL_KeyboardEvent key; /**< Keyboard event data */ 00504 SDL_TextEditingEvent edit; /**< Text editing event data */ 00505 SDL_TextInputEvent text; /**< Text input event data */ 00506 SDL_MouseMotionEvent motion; /**< Mouse motion event data */ 00507 SDL_MouseButtonEvent button; /**< Mouse button event data */ 00508 SDL_MouseWheelEvent wheel; /**< Mouse wheel event data */ 00509 SDL_JoyAxisEvent jaxis; /**< Joystick axis event data */ 00510 SDL_JoyBallEvent jball; /**< Joystick ball event data */ 00511 SDL_JoyHatEvent jhat; /**< Joystick hat event data */ 00512 SDL_JoyButtonEvent jbutton; /**< Joystick button event data */ 00513 SDL_JoyDeviceEvent jdevice; /**< Joystick device change event data */ 00514 SDL_ControllerAxisEvent caxis; /**< Game Controller axis event data */ 00515 SDL_ControllerButtonEvent cbutton; /**< Game Controller button event data */ 00516 SDL_ControllerDeviceEvent cdevice; /**< Game Controller device event data */ 00517 SDL_QuitEvent quit; /**< Quit request event data */ 00518 SDL_UserEvent user; /**< Custom event data */ 00519 SDL_SysWMEvent syswm; /**< System dependent window event data */ 00520 SDL_TouchFingerEvent tfinger; /**< Touch finger event data */ 00521 SDL_MultiGestureEvent mgesture; /**< Gesture event data */ 00522 SDL_DollarGestureEvent dgesture; /**< Gesture event data */ 00523 SDL_DropEvent drop; /**< Drag and drop event data */ 00524 00525 /* This is necessary for ABI compatibility between Visual C++ and GCC 00526 Visual C++ will respect the push pack pragma and use 52 bytes for 00527 this structure, and GCC will use the alignment of the largest datatype 00528 within the union, which is 8 bytes. 00529 00530 So... we'll add padding to force the size to be 56 bytes for both. 00531 */ 00532 Uint8 padding[56]; 00533 } SDL_Event; 00534 00535 00536 /* Function prototypes */ 00537 00538 /** 00539 * Pumps the event loop, gathering events from the input devices. 00540 * 00541 * This function updates the event queue and internal input device state. 00542 * 00543 * This should only be run in the thread that sets the video mode. 00544 */ 00545 extern DECLSPEC void SDLCALL SDL_PumpEvents(void); 00546 00547 /* @{ */ 00548 typedef enum 00549 { 00550 SDL_ADDEVENT, 00551 SDL_PEEKEVENT, 00552 SDL_GETEVENT 00553 } SDL_eventaction; 00554 00555 /** 00556 * Checks the event queue for messages and optionally returns them. 00557 * 00558 * If \c action is ::SDL_ADDEVENT, up to \c numevents events will be added to 00559 * the back of the event queue. 00560 * 00561 * If \c action is ::SDL_PEEKEVENT, up to \c numevents events at the front 00562 * of the event queue, within the specified minimum and maximum type, 00563 * will be returned and will not be removed from the queue. 00564 * 00565 * If \c action is ::SDL_GETEVENT, up to \c numevents events at the front 00566 * of the event queue, within the specified minimum and maximum type, 00567 * will be returned and will be removed from the queue. 00568 * 00569 * \return The number of events actually stored, or -1 if there was an error. 00570 * 00571 * This function is thread-safe. 00572 */ 00573 extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents, 00574 SDL_eventaction action, 00575 Uint32 minType, Uint32 maxType); 00576 /* @} */ 00577 00578 /** 00579 * Checks to see if certain event types are in the event queue. 00580 */ 00581 extern DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type); 00582 extern DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType); 00583 00584 /** 00585 * This function clears events from the event queue 00586 */ 00587 extern DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type); 00588 extern DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType); 00589 00590 /** 00591 * \brief Polls for currently pending events. 00592 * 00593 * \return 1 if there are any pending events, or 0 if there are none available. 00594 * 00595 * \param event If not NULL, the next event is removed from the queue and 00596 * stored in that area. 00597 */ 00598 extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event); 00599 00600 /** 00601 * \brief Waits indefinitely for the next available event. 00602 * 00603 * \return 1, or 0 if there was an error while waiting for events. 00604 * 00605 * \param event If not NULL, the next event is removed from the queue and 00606 * stored in that area. 00607 */ 00608 extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event * event); 00609 00610 /** 00611 * \brief Waits until the specified timeout (in milliseconds) for the next 00612 * available event. 00613 * 00614 * \return 1, or 0 if there was an error while waiting for events. 00615 * 00616 * \param event If not NULL, the next event is removed from the queue and 00617 * stored in that area. 00618 * \param timeout The timeout (in milliseconds) to wait for next event. 00619 */ 00620 extern DECLSPEC int SDLCALL SDL_WaitEventTimeout(SDL_Event * event, 00621 int timeout); 00622 00623 /** 00624 * \brief Add an event to the event queue. 00625 * 00626 * \return 1 on success, 0 if the event was filtered, or -1 if the event queue 00627 * was full or there was some other error. 00628 */ 00629 extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event); 00630 00631 typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event); 00632 00633 /** 00634 * Sets up a filter to process all events before they change internal state and 00635 * are posted to the internal event queue. 00636 * 00637 * The filter is prototyped as: 00638 * \code 00639 * int SDL_EventFilter(void *userdata, SDL_Event * event); 00640 * \endcode 00641 * 00642 * If the filter returns 1, then the event will be added to the internal queue. 00643 * If it returns 0, then the event will be dropped from the queue, but the 00644 * internal state will still be updated. This allows selective filtering of 00645 * dynamically arriving events. 00646 * 00647 * \warning Be very careful of what you do in the event filter function, as 00648 * it may run in a different thread! 00649 * 00650 * There is one caveat when dealing with the ::SDL_QuitEvent event type. The 00651 * event filter is only called when the window manager desires to close the 00652 * application window. If the event filter returns 1, then the window will 00653 * be closed, otherwise the window will remain open if possible. 00654 * 00655 * If the quit event is generated by an interrupt signal, it will bypass the 00656 * internal queue and be delivered to the application at the next event poll. 00657 */ 00658 extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter, 00659 void *userdata); 00660 00661 /** 00662 * Return the current event filter - can be used to "chain" filters. 00663 * If there is no event filter set, this function returns SDL_FALSE. 00664 */ 00665 extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter * filter, 00666 void **userdata); 00667 00668 /** 00669 * Add a function which is called when an event is added to the queue. 00670 */ 00671 extern DECLSPEC void SDLCALL SDL_AddEventWatch(SDL_EventFilter filter, 00672 void *userdata); 00673 00674 /** 00675 * Remove an event watch function added with SDL_AddEventWatch() 00676 */ 00677 extern DECLSPEC void SDLCALL SDL_DelEventWatch(SDL_EventFilter filter, 00678 void *userdata); 00679 00680 /** 00681 * Run the filter function on the current event queue, removing any 00682 * events for which the filter returns 0. 00683 */ 00684 extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter, 00685 void *userdata); 00686 00687 /* @{ */ 00688 #define SDL_QUERY -1 00689 #define SDL_IGNORE 0 00690 #define SDL_DISABLE 0 00691 #define SDL_ENABLE 1 00692 00693 /** 00694 * This function allows you to set the state of processing certain events. 00695 * - If \c state is set to ::SDL_IGNORE, that event will be automatically 00696 * dropped from the event queue and will not event be filtered. 00697 * - If \c state is set to ::SDL_ENABLE, that event will be processed 00698 * normally. 00699 * - If \c state is set to ::SDL_QUERY, SDL_EventState() will return the 00700 * current processing state of the specified event. 00701 */ 00702 extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint32 type, int state); 00703 /* @} */ 00704 #define SDL_GetEventState(type) SDL_EventState(type, SDL_QUERY) 00705 00706 /** 00707 * This function allocates a set of user-defined events, and returns 00708 * the beginning event number for that set of events. 00709 * 00710 * If there aren't enough user-defined events left, this function 00711 * returns (Uint32)-1 00712 */ 00713 extern DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents); 00714 00715 /* Ends C function definitions when using C++ */ 00716 #ifdef __cplusplus 00717 } 00718 #endif 00719 #include "close_code.h" 00720 00721 #endif /* _SDL_events_h */ 00722 00723 /* vi: set ts=4 sw=4 expandtab: */
Generated on Tue Jul 12 2022 15:10:18 by 1.7.2