include/SDL_events.h
author David Ludwig <dludwig@pobox.com>
Sat, 29 Nov 2014 10:09:30 -0500
changeset 9247 eddb899239fe
parent 9049 411e05b86ac3
child 9257 6f41196c2d6b
permissions -rw-r--r--
WinRT: bug and data-integrity fixes for SDL_GetPrefPath()

This change does a few things, all with regards to the WinRT implementation of
SDL_GetPrefPath():

1. it fixes a bug whereby SDL_GetPrefPath() did not create the directory it
returned. On other SDL platforms, SDL_GetPrefPath() will create separate
directories for its 'org' and 'app' folders. Without this, attempts to create
files in the pref-path would fail, unless those directories were first created
by the app, or by some other library the app used. This change makes sure
that these directories get created, before SDL_GetPrefPath() returns to its
caller(s).


2. it defaults to having SDL_GetPrefPath() return a WinRT 'Local' folder
on all platforms. Previously, for Windows Store apps, it would have used a
different, 'Roaming' folder. Files in Roaming folders can be automatically,
and synchronized across multiple devices by Windows. This synchronization can
happen while the app runs, with new files being copied into a running app's
pref-path. Unless an app is specifically designed to handle this scenario,
there is a chance that save-data could be overwritten in unwanted or
unexpected ways.

The default is now to use a Local folder, which does not get synchronized, and
which is arguably a bit safer to use. Apps that wish to use Roaming folders
can do so by setting SDL_HINT_WINRT_PREF_PATH_ROOT to "roaming", however it
is recommended that one first read Microsoft's documentation for Roaming
files, a link to which is provided in README-winrt.md.

To preserve older pref-path selection behavior (found in SDL 2.0.3, as well as
many pre-2.0.4 versions of SDL from hg.libsdl.org), which uses a Roaming path
in Windows Store apps, and a Local path in Windows Phone, set
SDL_HINT_WINRT_PREF_PATH_ROOT to "old".

Please note that Roaming paths are not supported on Windows Phone 8.0, due to
limitations in the OS itself. Attempts to use this will fail.
(Windows Phone 8.1 does not have this limitation, however.)


3. It makes SDL_GetPrefPath(), when on Windows Phone 8.0, and when
SDL_HINT_WINRT_PREF_PATH_ROOT is set to "roaming", return NULL, rather than
silently defaulting to a Local path (then switching to a Roaming path if and
when the user upgraded to Windows Phone 8.1).
slouken@0
     1
/*
slouken@5535
     2
  Simple DirectMedia Layer
slouken@8149
     3
  Copyright (C) 1997-2014 Sam Lantinga <slouken@libsdl.org>
slouken@0
     4
slouken@5535
     5
  This software is provided 'as-is', without any express or implied
slouken@5535
     6
  warranty.  In no event will the authors be held liable for any damages
slouken@5535
     7
  arising from the use of this software.
slouken@0
     8
slouken@5535
     9
  Permission is granted to anyone to use this software for any purpose,
slouken@5535
    10
  including commercial applications, and to alter it and redistribute it
slouken@5535
    11
  freely, subject to the following restrictions:
slouken@0
    12
slouken@5535
    13
  1. The origin of this software must not be misrepresented; you must not
slouken@5535
    14
     claim that you wrote the original software. If you use this software
slouken@5535
    15
     in a product, an acknowledgment in the product documentation would be
slouken@5535
    16
     appreciated but is not required.
slouken@5535
    17
  2. Altered source versions must be plainly marked as such, and must not be
slouken@5535
    18
     misrepresented as being the original software.
slouken@5535
    19
  3. This notice may not be removed or altered from any source distribution.
slouken@0
    20
*/
slouken@0
    21
slouken@1895
    22
/**
slouken@3407
    23
 *  \file SDL_events.h
slouken@7191
    24
 *
slouken@3407
    25
 *  Include file for SDL event handling.
slouken@1895
    26
 */
slouken@0
    27
slouken@0
    28
#ifndef _SDL_events_h
slouken@0
    29
#define _SDL_events_h
slouken@0
    30
slouken@1356
    31
#include "SDL_stdinc.h"
slouken@1358
    32
#include "SDL_error.h"
slouken@1895
    33
#include "SDL_video.h"
slouken@0
    34
#include "SDL_keyboard.h"
slouken@0
    35
#include "SDL_mouse.h"
slouken@0
    36
#include "SDL_joystick.h"
slouken@6690
    37
#include "SDL_gamecontroller.h"
slouken@0
    38
#include "SDL_quit.h"
jim@4659
    39
#include "SDL_gesture.h"
jim@4659
    40
#include "SDL_touch.h"
slouken@0
    41
slouken@0
    42
#include "begin_code.h"
slouken@0
    43
/* Set up for C function definitions, even when using C++ */
slouken@0
    44
#ifdef __cplusplus
slouken@0
    45
extern "C" {
slouken@0
    46
#endif
slouken@0
    47
slouken@1330
    48
/* General keyboard/mouse state definitions */
slouken@7191
    49
#define SDL_RELEASED    0
slouken@7191
    50
#define SDL_PRESSED 1
slouken@1330
    51
slouken@1895
    52
/**
slouken@3407
    53
 * \brief The types of events that can be delivered.
slouken@1895
    54
 */
slouken@1895
    55
typedef enum
slouken@1895
    56
{
slouken@4429
    57
    SDL_FIRSTEVENT     = 0,     /**< Unused (do not remove) */
slouken@4429
    58
slouken@4429
    59
    /* Application events */
slouken@4429
    60
    SDL_QUIT           = 0x100, /**< User-requested quit */
slouken@4429
    61
philipp@9049
    62
    /* These application events have special meaning on iOS, see README-ios.md for details */
slouken@7191
    63
    SDL_APP_TERMINATING,        /**< The application is being terminated by the OS
slouken@7190
    64
                                     Called on iOS in applicationWillTerminate()
slouken@7190
    65
                                     Called on Android in onDestroy()
slouken@7190
    66
                                */
slouken@7191
    67
    SDL_APP_LOWMEMORY,          /**< The application is low on memory, free memory if possible.
slouken@7190
    68
                                     Called on iOS in applicationDidReceiveMemoryWarning()
slouken@7190
    69
                                     Called on Android in onLowMemory()
slouken@7190
    70
                                */
slouken@7191
    71
    SDL_APP_WILLENTERBACKGROUND, /**< The application is about to enter the background
slouken@7190
    72
                                     Called on iOS in applicationWillResignActive()
slouken@7190
    73
                                     Called on Android in onPause()
slouken@7190
    74
                                */
slouken@7191
    75
    SDL_APP_DIDENTERBACKGROUND, /**< The application did enter the background and may not get CPU for some time
slouken@7190
    76
                                     Called on iOS in applicationDidEnterBackground()
slouken@7190
    77
                                     Called on Android in onPause()
slouken@7190
    78
                                */
slouken@7191
    79
    SDL_APP_WILLENTERFOREGROUND, /**< The application is about to enter the foreground
slouken@7190
    80
                                     Called on iOS in applicationWillEnterForeground()
slouken@7190
    81
                                     Called on Android in onResume()
slouken@7190
    82
                                */
slouken@7191
    83
    SDL_APP_DIDENTERFOREGROUND, /**< The application is now interactive
slouken@7190
    84
                                     Called on iOS in applicationDidBecomeActive()
slouken@7190
    85
                                     Called on Android in onResume()
slouken@7190
    86
                                */
slouken@7190
    87
slouken@4429
    88
    /* Window events */
slouken@4429
    89
    SDL_WINDOWEVENT    = 0x200, /**< Window state change */
slouken@4429
    90
    SDL_SYSWMEVENT,             /**< System specific event */
slouken@4429
    91
slouken@4429
    92
    /* Keyboard events */
slouken@4971
    93
    SDL_KEYDOWN        = 0x300, /**< Key pressed */
slouken@4971
    94
    SDL_KEYUP,                  /**< Key released */
slouken@3280
    95
    SDL_TEXTEDITING,            /**< Keyboard text editing (composition) */
slouken@1957
    96
    SDL_TEXTINPUT,              /**< Keyboard text input */
slouken@4429
    97
slouken@4429
    98
    /* Mouse events */
slouken@4429
    99
    SDL_MOUSEMOTION    = 0x400, /**< Mouse moved */
slouken@1895
   100
    SDL_MOUSEBUTTONDOWN,        /**< Mouse button pressed */
slouken@1895
   101
    SDL_MOUSEBUTTONUP,          /**< Mouse button released */
slouken@1957
   102
    SDL_MOUSEWHEEL,             /**< Mouse wheel motion */
slouken@4429
   103
slouken@4429
   104
    /* Joystick events */
slouken@4429
   105
    SDL_JOYAXISMOTION  = 0x600, /**< Joystick axis motion */
slouken@1895
   106
    SDL_JOYBALLMOTION,          /**< Joystick trackball motion */
slouken@1895
   107
    SDL_JOYHATMOTION,           /**< Joystick hat position change */
slouken@1895
   108
    SDL_JOYBUTTONDOWN,          /**< Joystick button pressed */
slouken@1895
   109
    SDL_JOYBUTTONUP,            /**< Joystick button released */
slouken@6690
   110
    SDL_JOYDEVICEADDED,         /**< A new joystick has been inserted into the system */
slouken@6690
   111
    SDL_JOYDEVICEREMOVED,       /**< An opened joystick has been removed */
slouken@6690
   112
slouken@7191
   113
    /* Game controller events */
slouken@7191
   114
    SDL_CONTROLLERAXISMOTION  = 0x650, /**< Game controller axis motion */
slouken@7191
   115
    SDL_CONTROLLERBUTTONDOWN,          /**< Game controller button pressed */
slouken@7191
   116
    SDL_CONTROLLERBUTTONUP,            /**< Game controller button released */
slouken@7191
   117
    SDL_CONTROLLERDEVICEADDED,         /**< A new Game controller has been inserted into the system */
slouken@7191
   118
    SDL_CONTROLLERDEVICEREMOVED,       /**< An opened Game controller has been removed */
slouken@7191
   119
    SDL_CONTROLLERDEVICEREMAPPED,      /**< The controller mapping was updated */
slouken@4429
   120
slouken@4661
   121
    /* Touch events */
slouken@4661
   122
    SDL_FINGERDOWN      = 0x700,
jim@4641
   123
    SDL_FINGERUP,
jim@4641
   124
    SDL_FINGERMOTION,
jim@4641
   125
slouken@4661
   126
    /* Gesture events */
slouken@4661
   127
    SDL_DOLLARGESTURE   = 0x800,
jim@4659
   128
    SDL_DOLLARRECORD,
jim@4657
   129
    SDL_MULTIGESTURE,
jim@4657
   130
slouken@4503
   131
    /* Clipboard events */
slouken@6091
   132
    SDL_CLIPBOARDUPDATE = 0x900, /**< The clipboard changed */
jim@4662
   133
slouken@6091
   134
    /* Drag and drop events */
slouken@6091
   135
    SDL_DROPFILE        = 0x1000, /**< The system requests a file open */
slouken@7191
   136
slouken@8207
   137
    /* Render events */
slouken@8674
   138
    SDL_RENDER_TARGETS_RESET = 0x2000, /**< The render targets have been reset and their contents need to be updated */
slouken@8674
   139
    SDL_RENDER_DEVICE_RESET, /**< The device has been reset and all textures need to be recreated */
slouken@8207
   140
slouken@4429
   141
    /** Events ::SDL_USEREVENT through ::SDL_LASTEVENT are for your use,
slouken@4429
   142
     *  and should be allocated with SDL_RegisterEvents()
slouken@4429
   143
     */
slouken@4429
   144
    SDL_USEREVENT    = 0x8000,
slouken@4429
   145
slouken@3407
   146
    /**
slouken@3407
   147
     *  This last event is only for bounding internal arrays
slouken@1895
   148
     */
slouken@4429
   149
    SDL_LASTEVENT    = 0xFFFF
slouken@1294
   150
} SDL_EventType;
slouken@0
   151
slouken@1895
   152
/**
slouken@6949
   153
 *  \brief Fields shared by every event
slouken@6949
   154
 */
dludwig@7082
   155
typedef struct SDL_CommonEvent
slouken@6949
   156
{
slouken@6949
   157
    Uint32 type;
slouken@6949
   158
    Uint32 timestamp;
dludwig@7082
   159
} SDL_CommonEvent;
slouken@7191
   160
slouken@6949
   161
/**
slouken@3407
   162
 *  \brief Window state change event data (event.window.*)
slouken@1895
   163
 */
slouken@1895
   164
typedef struct SDL_WindowEvent
slouken@1895
   165
{
slouken@4429
   166
    Uint32 type;        /**< ::SDL_WINDOWEVENT */
slouken@6114
   167
    Uint32 timestamp;
slouken@4429
   168
    Uint32 windowID;    /**< The associated window */
slouken@4429
   169
    Uint8 event;        /**< ::SDL_WindowEventID */
slouken@4429
   170
    Uint8 padding1;
slouken@4429
   171
    Uint8 padding2;
slouken@4429
   172
    Uint8 padding3;
slouken@6950
   173
    Sint32 data1;       /**< event dependent data */
slouken@6950
   174
    Sint32 data2;       /**< event dependent data */
slouken@1895
   175
} SDL_WindowEvent;
slouken@0
   176
slouken@1895
   177
/**
slouken@3407
   178
 *  \brief Keyboard button event structure (event.key.*)
slouken@1895
   179
 */
slouken@1895
   180
typedef struct SDL_KeyboardEvent
slouken@1895
   181
{
slouken@4429
   182
    Uint32 type;        /**< ::SDL_KEYDOWN or ::SDL_KEYUP */
slouken@6114
   183
    Uint32 timestamp;
slouken@4429
   184
    Uint32 windowID;    /**< The window with keyboard focus, if any */
slouken@4429
   185
    Uint8 state;        /**< ::SDL_PRESSED or ::SDL_RELEASED */
slouken@4560
   186
    Uint8 repeat;       /**< Non-zero if this is a key repeat */
slouken@4429
   187
    Uint8 padding2;
slouken@4465
   188
    Uint8 padding3;
slouken@5218
   189
    SDL_Keysym keysym;  /**< The key that was pressed or released */
slouken@0
   190
} SDL_KeyboardEvent;
slouken@0
   191
slouken@3407
   192
#define SDL_TEXTEDITINGEVENT_TEXT_SIZE (32)
slouken@1895
   193
/**
slouken@3407
   194
 *  \brief Keyboard text editing event structure (event.edit.*)
slouken@3280
   195
 */
slouken@3280
   196
typedef struct SDL_TextEditingEvent
slouken@3280
   197
{
slouken@4429
   198
    Uint32 type;                                /**< ::SDL_TEXTEDITING */
slouken@6114
   199
    Uint32 timestamp;
slouken@4434
   200
    Uint32 windowID;                            /**< The window with keyboard focus, if any */
slouken@3280
   201
    char text[SDL_TEXTEDITINGEVENT_TEXT_SIZE];  /**< The editing text */
slouken@6950
   202
    Sint32 start;                               /**< The start cursor of selected editing text */
slouken@6950
   203
    Sint32 length;                              /**< The length of selected editing text */
slouken@3280
   204
} SDL_TextEditingEvent;
slouken@3280
   205
slouken@3407
   206
slouken@3407
   207
#define SDL_TEXTINPUTEVENT_TEXT_SIZE (32)
slouken@3280
   208
/**
slouken@3407
   209
 *  \brief Keyboard text input event structure (event.text.*)
slouken@1895
   210
 */
slouken@1895
   211
typedef struct SDL_TextInputEvent
slouken@1895
   212
{
slouken@4429
   213
    Uint32 type;                              /**< ::SDL_TEXTINPUT */
slouken@6114
   214
    Uint32 timestamp;
slouken@3685
   215
    Uint32 windowID;                          /**< The window with keyboard focus, if any */
bob@2300
   216
    char text[SDL_TEXTINPUTEVENT_TEXT_SIZE];  /**< The input text */
slouken@1895
   217
} SDL_TextInputEvent;
slouken@1895
   218
slouken@1895
   219
/**
slouken@3407
   220
 *  \brief Mouse motion event structure (event.motion.*)
slouken@1895
   221
 */
slouken@1895
   222
typedef struct SDL_MouseMotionEvent
slouken@1895
   223
{
slouken@4429
   224
    Uint32 type;        /**< ::SDL_MOUSEMOTION */
slouken@6114
   225
    Uint32 timestamp;
slouken@4429
   226
    Uint32 windowID;    /**< The window with mouse focus, if any */
slouken@6950
   227
    Uint32 which;       /**< The mouse instance id, or SDL_TOUCH_MOUSEID */
slouken@7203
   228
    Uint32 state;       /**< The current button state */
slouken@6950
   229
    Sint32 x;           /**< X coordinate, relative to window */
slouken@6950
   230
    Sint32 y;           /**< Y coordinate, relative to window */
slouken@6950
   231
    Sint32 xrel;        /**< The relative motion in the X direction */
slouken@6950
   232
    Sint32 yrel;        /**< The relative motion in the Y direction */
slouken@0
   233
} SDL_MouseMotionEvent;
slouken@0
   234
slouken@1895
   235
/**
slouken@3407
   236
 *  \brief Mouse button event structure (event.button.*)
slouken@1895
   237
 */
slouken@1895
   238
typedef struct SDL_MouseButtonEvent
slouken@1895
   239
{
slouken@4429
   240
    Uint32 type;        /**< ::SDL_MOUSEBUTTONDOWN or ::SDL_MOUSEBUTTONUP */
slouken@6114
   241
    Uint32 timestamp;
slouken@4429
   242
    Uint32 windowID;    /**< The window with mouse focus, if any */
slouken@6950
   243
    Uint32 which;       /**< The mouse instance id, or SDL_TOUCH_MOUSEID */
slouken@4429
   244
    Uint8 button;       /**< The mouse button index */
slouken@4429
   245
    Uint8 state;        /**< ::SDL_PRESSED or ::SDL_RELEASED */
slouken@8066
   246
    Uint8 clicks;       /**< 1 for single-click, 2 for double-click, etc. */
slouken@4429
   247
    Uint8 padding1;
slouken@6950
   248
    Sint32 x;           /**< X coordinate, relative to window */
slouken@6950
   249
    Sint32 y;           /**< Y coordinate, relative to window */
slouken@0
   250
} SDL_MouseButtonEvent;
slouken@0
   251
slouken@1895
   252
/**
slouken@3407
   253
 *  \brief Mouse wheel event structure (event.wheel.*)
slouken@1895
   254
 */
slouken@1895
   255
typedef struct SDL_MouseWheelEvent
slouken@1895
   256
{
slouken@4429
   257
    Uint32 type;        /**< ::SDL_MOUSEWHEEL */
slouken@6114
   258
    Uint32 timestamp;
slouken@4429
   259
    Uint32 windowID;    /**< The window with mouse focus, if any */
slouken@6950
   260
    Uint32 which;       /**< The mouse instance id, or SDL_TOUCH_MOUSEID */
slouken@8232
   261
    Sint32 x;           /**< The amount scrolled horizontally, positive to the right and negative to the left */
slouken@8232
   262
    Sint32 y;           /**< The amount scrolled vertically, positive away from the user and negative toward the user */
slouken@1895
   263
} SDL_MouseWheelEvent;
slouken@1895
   264
slouken@1895
   265
/**
slouken@3407
   266
 *  \brief Joystick axis motion event structure (event.jaxis.*)
slouken@1895
   267
 */
slouken@1895
   268
typedef struct SDL_JoyAxisEvent
slouken@1895
   269
{
slouken@4429
   270
    Uint32 type;        /**< ::SDL_JOYAXISMOTION */
slouken@6114
   271
    Uint32 timestamp;
slouken@6974
   272
    SDL_JoystickID which; /**< The joystick instance id */
slouken@1895
   273
    Uint8 axis;         /**< The joystick axis index */
slouken@4429
   274
    Uint8 padding1;
slouken@4429
   275
    Uint8 padding2;
slouken@6949
   276
    Uint8 padding3;
slouken@6949
   277
    Sint16 value;       /**< The axis value (range: -32768 to 32767) */
slouken@6949
   278
    Uint16 padding4;
slouken@0
   279
} SDL_JoyAxisEvent;
slouken@0
   280
slouken@1895
   281
/**
slouken@3407
   282
 *  \brief Joystick trackball motion event structure (event.jball.*)
slouken@1895
   283
 */
slouken@1895
   284
typedef struct SDL_JoyBallEvent
slouken@1895
   285
{
slouken@4429
   286
    Uint32 type;        /**< ::SDL_JOYBALLMOTION */
slouken@7191
   287
    Uint32 timestamp;
slouken@6974
   288
    SDL_JoystickID which; /**< The joystick instance id */
slouken@1895
   289
    Uint8 ball;         /**< The joystick trackball index */
slouken@4429
   290
    Uint8 padding1;
slouken@4429
   291
    Uint8 padding2;
slouken@6949
   292
    Uint8 padding3;
slouken@6949
   293
    Sint16 xrel;        /**< The relative motion in the X direction */
slouken@6949
   294
    Sint16 yrel;        /**< The relative motion in the Y direction */
slouken@0
   295
} SDL_JoyBallEvent;
slouken@0
   296
slouken@1895
   297
/**
slouken@3407
   298
 *  \brief Joystick hat position change event structure (event.jhat.*)
slouken@1895
   299
 */
slouken@1895
   300
typedef struct SDL_JoyHatEvent
slouken@1895
   301
{
slouken@4429
   302
    Uint32 type;        /**< ::SDL_JOYHATMOTION */
slouken@7191
   303
    Uint32 timestamp;
slouken@6974
   304
    SDL_JoystickID which; /**< The joystick instance id */
slouken@1895
   305
    Uint8 hat;          /**< The joystick hat index */
slouken@3407
   306
    Uint8 value;        /**< The hat position value.
slouken@3407
   307
                         *   \sa ::SDL_HAT_LEFTUP ::SDL_HAT_UP ::SDL_HAT_RIGHTUP
slouken@3407
   308
                         *   \sa ::SDL_HAT_LEFT ::SDL_HAT_CENTERED ::SDL_HAT_RIGHT
slouken@3407
   309
                         *   \sa ::SDL_HAT_LEFTDOWN ::SDL_HAT_DOWN ::SDL_HAT_RIGHTDOWN
slouken@7191
   310
                         *
slouken@3407
   311
                         *   Note that zero means the POV is centered.
slouken@1895
   312
                         */
slouken@4429
   313
    Uint8 padding1;
slouken@6949
   314
    Uint8 padding2;
slouken@0
   315
} SDL_JoyHatEvent;
slouken@0
   316
slouken@1895
   317
/**
slouken@3407
   318
 *  \brief Joystick button event structure (event.jbutton.*)
slouken@1895
   319
 */
slouken@1895
   320
typedef struct SDL_JoyButtonEvent
slouken@1895
   321
{
slouken@4429
   322
    Uint32 type;        /**< ::SDL_JOYBUTTONDOWN or ::SDL_JOYBUTTONUP */
slouken@7191
   323
    Uint32 timestamp;
slouken@6974
   324
    SDL_JoystickID which; /**< The joystick instance id */
slouken@1895
   325
    Uint8 button;       /**< The joystick button index */
slouken@3407
   326
    Uint8 state;        /**< ::SDL_PRESSED or ::SDL_RELEASED */
slouken@4429
   327
    Uint8 padding1;
slouken@6949
   328
    Uint8 padding2;
slouken@0
   329
} SDL_JoyButtonEvent;
slouken@0
   330
slouken@6690
   331
/**
slouken@6690
   332
 *  \brief Joystick device event structure (event.jdevice.*)
slouken@6690
   333
 */
slouken@6690
   334
typedef struct SDL_JoyDeviceEvent
slouken@6690
   335
{
slouken@7191
   336
    Uint32 type;        /**< ::SDL_JOYDEVICEADDED or ::SDL_JOYDEVICEREMOVED */
slouken@7191
   337
    Uint32 timestamp;
slouken@7191
   338
    Sint32 which;       /**< The joystick device index for the ADDED event, instance id for the REMOVED event */
slouken@6690
   339
} SDL_JoyDeviceEvent;
slouken@6690
   340
slouken@6690
   341
slouken@6690
   342
/**
slouken@6690
   343
 *  \brief Game controller axis motion event structure (event.caxis.*)
slouken@6690
   344
 */
slouken@6690
   345
typedef struct SDL_ControllerAxisEvent
slouken@6690
   346
{
slouken@6690
   347
    Uint32 type;        /**< ::SDL_CONTROLLERAXISMOTION */
slouken@7191
   348
    Uint32 timestamp;
slouken@6974
   349
    SDL_JoystickID which; /**< The joystick instance id */
slouken@6949
   350
    Uint8 axis;         /**< The controller axis (SDL_GameControllerAxis) */
slouken@6949
   351
    Uint8 padding1;
slouken@6949
   352
    Uint8 padding2;
slouken@6949
   353
    Uint8 padding3;
slouken@6949
   354
    Sint16 value;       /**< The axis value (range: -32768 to 32767) */
slouken@6949
   355
    Uint16 padding4;
slouken@6690
   356
} SDL_ControllerAxisEvent;
slouken@6690
   357
slouken@6690
   358
slouken@6690
   359
/**
slouken@6690
   360
 *  \brief Game controller button event structure (event.cbutton.*)
slouken@6690
   361
 */
slouken@6690
   362
typedef struct SDL_ControllerButtonEvent
slouken@6690
   363
{
slouken@6690
   364
    Uint32 type;        /**< ::SDL_CONTROLLERBUTTONDOWN or ::SDL_CONTROLLERBUTTONUP */
slouken@7191
   365
    Uint32 timestamp;
slouken@6974
   366
    SDL_JoystickID which; /**< The joystick instance id */
slouken@6949
   367
    Uint8 button;       /**< The controller button (SDL_GameControllerButton) */
slouken@6690
   368
    Uint8 state;        /**< ::SDL_PRESSED or ::SDL_RELEASED */
slouken@6949
   369
    Uint8 padding1;
slouken@6949
   370
    Uint8 padding2;
slouken@6690
   371
} SDL_ControllerButtonEvent;
slouken@6690
   372
slouken@6690
   373
slouken@6690
   374
/**
slouken@6690
   375
 *  \brief Controller device event structure (event.cdevice.*)
slouken@6690
   376
 */
slouken@6690
   377
typedef struct SDL_ControllerDeviceEvent
slouken@6690
   378
{
slouken@7191
   379
    Uint32 type;        /**< ::SDL_CONTROLLERDEVICEADDED, ::SDL_CONTROLLERDEVICEREMOVED, or ::SDL_CONTROLLERDEVICEREMAPPED */
slouken@7191
   380
    Uint32 timestamp;
slouken@7191
   381
    Sint32 which;       /**< The joystick device index for the ADDED event, instance id for the REMOVED or REMAPPED event */
slouken@6690
   382
} SDL_ControllerDeviceEvent;
slouken@6690
   383
jim@4641
   384
jim@4641
   385
/**
slouken@6951
   386
 *  \brief Touch finger event structure (event.tfinger.*)
jim@4641
   387
 */
jim@4641
   388
typedef struct SDL_TouchFingerEvent
jim@4641
   389
{
slouken@6949
   390
    Uint32 type;        /**< ::SDL_FINGERMOTION or ::SDL_FINGERDOWN or ::SDL_FINGERUP */
slouken@6114
   391
    Uint32 timestamp;
slouken@6949
   392
    SDL_TouchID touchId; /**< The touch device id */
jimtla@4678
   393
    SDL_FingerID fingerId;
slouken@6951
   394
    float x;            /**< Normalized in the range 0...1 */
slouken@6951
   395
    float y;            /**< Normalized in the range 0...1 */
slouken@6951
   396
    float dx;           /**< Normalized in the range 0...1 */
slouken@6951
   397
    float dy;           /**< Normalized in the range 0...1 */
slouken@6951
   398
    float pressure;     /**< Normalized in the range 0...1 */
jim@4641
   399
} SDL_TouchFingerEvent;
jim@4641
   400
jim@4641
   401
jim@4641
   402
/**
slouken@5009
   403
 *  \brief Multiple Finger Gesture Event (event.mgesture.*)
jim@4657
   404
 */
jim@4657
   405
typedef struct SDL_MultiGestureEvent
jim@4657
   406
{
jim@4657
   407
    Uint32 type;        /**< ::SDL_MULTIGESTURE */
slouken@6114
   408
    Uint32 timestamp;
slouken@6951
   409
    SDL_TouchID touchId; /**< The touch device index */
jim@4657
   410
    float dTheta;
jim@4657
   411
    float dDist;
slouken@6951
   412
    float x;
slouken@7191
   413
    float y;
jim@4683
   414
    Uint16 numFingers;
jim@4683
   415
    Uint16 padding;
jim@4657
   416
} SDL_MultiGestureEvent;
jim@4657
   417
slouken@6951
   418
philipp@7309
   419
/**
philipp@7309
   420
 * \brief Dollar Gesture Event (event.dgesture.*)
philipp@7309
   421
 */
slouken@5014
   422
typedef struct SDL_DollarGestureEvent
jim@4658
   423
{
jim@4658
   424
    Uint32 type;        /**< ::SDL_DOLLARGESTURE */
slouken@6114
   425
    Uint32 timestamp;
slouken@6951
   426
    SDL_TouchID touchId; /**< The touch device id */
jimtla@4678
   427
    SDL_GestureID gestureId;
jim@4689
   428
    Uint32 numFingers;
jim@4658
   429
    float error;
slouken@6951
   430
    float x;            /**< Normalized center of gesture */
slouken@6951
   431
    float y;            /**< Normalized center of gesture */
jim@4658
   432
} SDL_DollarGestureEvent;
jim@4658
   433
jim@4657
   434
slouken@1895
   435
/**
slouken@6091
   436
 *  \brief An event used to request a file open by the system (event.drop.*)
slouken@6091
   437
 *         This event is disabled by default, you can enable it with SDL_EventState()
slouken@6091
   438
 *  \note If you enable this event, you must free the filename in the event.
slouken@6091
   439
 */
slouken@6091
   440
typedef struct SDL_DropEvent
slouken@6091
   441
{
slouken@6091
   442
    Uint32 type;        /**< ::SDL_DROPFILE */
slouken@6114
   443
    Uint32 timestamp;
slouken@6091
   444
    char *file;         /**< The file name, which should be freed with SDL_free() */
slouken@6091
   445
} SDL_DropEvent;
slouken@6091
   446
slouken@6091
   447
slouken@6091
   448
/**
slouken@3407
   449
 *  \brief The "quit requested" event
slouken@0
   450
 */
slouken@1895
   451
typedef struct SDL_QuitEvent
slouken@1895
   452
{
slouken@4429
   453
    Uint32 type;        /**< ::SDL_QUIT */
slouken@6114
   454
    Uint32 timestamp;
slouken@1895
   455
} SDL_QuitEvent;
slouken@1895
   456
slouken@7190
   457
/**
slouken@7190
   458
 *  \brief OS Specific event
slouken@7190
   459
 */
slouken@7190
   460
typedef struct SDL_OSEvent
slouken@7190
   461
{
slouken@7190
   462
    Uint32 type;        /**< ::SDL_QUIT */
slouken@7190
   463
    Uint32 timestamp;
slouken@7190
   464
} SDL_OSEvent;
slouken@5009
   465
slouken@1895
   466
/**
slouken@3407
   467
 *  \brief A user-defined event type (event.user.*)
slouken@1895
   468
 */
slouken@1895
   469
typedef struct SDL_UserEvent
slouken@1895
   470
{
philipp@7278
   471
    Uint32 type;        /**< ::SDL_USEREVENT through ::SDL_LASTEVENT-1 */
slouken@6114
   472
    Uint32 timestamp;
slouken@4429
   473
    Uint32 windowID;    /**< The associated window if any */
slouken@6950
   474
    Sint32 code;        /**< User defined event code */
slouken@4429
   475
    void *data1;        /**< User defined data pointer */
slouken@4429
   476
    void *data2;        /**< User defined data pointer */
slouken@1895
   477
} SDL_UserEvent;
slouken@1895
   478
slouken@5009
   479
slouken@1895
   480
struct SDL_SysWMmsg;
slouken@1895
   481
typedef struct SDL_SysWMmsg SDL_SysWMmsg;
slouken@3407
   482
slouken@3407
   483
/**
slouken@3407
   484
 *  \brief A video driver dependent system event (event.syswm.*)
slouken@6091
   485
 *         This event is disabled by default, you can enable it with SDL_EventState()
slouken@6091
   486
 *
slouken@3407
   487
 *  \note If you want to use this event, you should include SDL_syswm.h.
slouken@3407
   488
 */
slouken@1895
   489
typedef struct SDL_SysWMEvent
slouken@1895
   490
{
slouken@4429
   491
    Uint32 type;        /**< ::SDL_SYSWMEVENT */
slouken@6114
   492
    Uint32 timestamp;
slouken@1895
   493
    SDL_SysWMmsg *msg;  /**< driver dependent data, defined in SDL_syswm.h */
slouken@1895
   494
} SDL_SysWMEvent;
slouken@1895
   495
slouken@1895
   496
/**
slouken@3407
   497
 *  \brief General event structure
slouken@1895
   498
 */
slouken@1895
   499
typedef union SDL_Event
slouken@1895
   500
{
slouken@4429
   501
    Uint32 type;                    /**< Event type, shared with all events */
dludwig@7082
   502
    SDL_CommonEvent common;         /**< Common event data */
slouken@1895
   503
    SDL_WindowEvent window;         /**< Window event data */
slouken@1895
   504
    SDL_KeyboardEvent key;          /**< Keyboard event data */
slouken@3280
   505
    SDL_TextEditingEvent edit;      /**< Text editing event data */
bob@2300
   506
    SDL_TextInputEvent text;        /**< Text input event data */
slouken@1895
   507
    SDL_MouseMotionEvent motion;    /**< Mouse motion event data */
slouken@1895
   508
    SDL_MouseButtonEvent button;    /**< Mouse button event data */
bob@2300
   509
    SDL_MouseWheelEvent wheel;      /**< Mouse wheel event data */
slouken@1895
   510
    SDL_JoyAxisEvent jaxis;         /**< Joystick axis event data */
slouken@1895
   511
    SDL_JoyBallEvent jball;         /**< Joystick ball event data */
slouken@1895
   512
    SDL_JoyHatEvent jhat;           /**< Joystick hat event data */
slouken@1895
   513
    SDL_JoyButtonEvent jbutton;     /**< Joystick button event data */
slouken@6690
   514
    SDL_JoyDeviceEvent jdevice;     /**< Joystick device change event data */
slouken@7191
   515
    SDL_ControllerAxisEvent caxis;      /**< Game Controller axis event data */
slouken@7191
   516
    SDL_ControllerButtonEvent cbutton;  /**< Game Controller button event data */
slouken@7191
   517
    SDL_ControllerDeviceEvent cdevice;  /**< Game Controller device event data */
slouken@1895
   518
    SDL_QuitEvent quit;             /**< Quit request event data */
slouken@1895
   519
    SDL_UserEvent user;             /**< Custom event data */
slouken@1895
   520
    SDL_SysWMEvent syswm;           /**< System dependent window event data */
jim@4641
   521
    SDL_TouchFingerEvent tfinger;   /**< Touch finger event data */
slouken@6951
   522
    SDL_MultiGestureEvent mgesture; /**< Gesture event data */
slouken@6951
   523
    SDL_DollarGestureEvent dgesture; /**< Gesture event data */
slouken@6091
   524
    SDL_DropEvent drop;             /**< Drag and drop event data */
slouken@6595
   525
slouken@6595
   526
    /* This is necessary for ABI compatibility between Visual C++ and GCC
slouken@6595
   527
       Visual C++ will respect the push pack pragma and use 52 bytes for
slouken@6595
   528
       this structure, and GCC will use the alignment of the largest datatype
slouken@6595
   529
       within the union, which is 8 bytes.
slouken@6595
   530
slouken@6595
   531
       So... we'll add padding to force the size to be 56 bytes for both.
slouken@6595
   532
    */
slouken@6595
   533
    Uint8 padding[56];
slouken@0
   534
} SDL_Event;
slouken@0
   535
slouken@0
   536
slouken@0
   537
/* Function prototypes */
slouken@0
   538
slouken@3407
   539
/**
slouken@3407
   540
 *  Pumps the event loop, gathering events from the input devices.
slouken@7191
   541
 *
slouken@3407
   542
 *  This function updates the event queue and internal input device state.
slouken@7191
   543
 *
slouken@3407
   544
 *  This should only be run in the thread that sets the video mode.
slouken@3407
   545
 */
slouken@337
   546
extern DECLSPEC void SDLCALL SDL_PumpEvents(void);
slouken@0
   547
gabomdq@7678
   548
/* @{ */
slouken@1895
   549
typedef enum
slouken@1895
   550
{
slouken@1895
   551
    SDL_ADDEVENT,
slouken@1895
   552
    SDL_PEEKEVENT,
slouken@1895
   553
    SDL_GETEVENT
slouken@0
   554
} SDL_eventaction;
slouken@3407
   555
slouken@3407
   556
/**
slouken@3407
   557
 *  Checks the event queue for messages and optionally returns them.
slouken@7191
   558
 *
slouken@3407
   559
 *  If \c action is ::SDL_ADDEVENT, up to \c numevents events will be added to
slouken@3407
   560
 *  the back of the event queue.
slouken@7191
   561
 *
slouken@3407
   562
 *  If \c action is ::SDL_PEEKEVENT, up to \c numevents events at the front
slouken@4635
   563
 *  of the event queue, within the specified minimum and maximum type,
slouken@4635
   564
 *  will be returned and will not be removed from the queue.
slouken@7191
   565
 *
slouken@7191
   566
 *  If \c action is ::SDL_GETEVENT, up to \c numevents events at the front
slouken@4635
   567
 *  of the event queue, within the specified minimum and maximum type,
slouken@4635
   568
 *  will be returned and will be removed from the queue.
slouken@7191
   569
 *
slouken@3407
   570
 *  \return The number of events actually stored, or -1 if there was an error.
slouken@7191
   571
 *
slouken@3407
   572
 *  This function is thread-safe.
slouken@3407
   573
 */
slouken@1895
   574
extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents,
slouken@1895
   575
                                           SDL_eventaction action,
slouken@4429
   576
                                           Uint32 minType, Uint32 maxType);
gabomdq@7678
   577
/* @} */
slouken@1895
   578
slouken@3407
   579
/**
slouken@3407
   580
 *  Checks to see if certain event types are in the event queue.
slouken@1895
   581
 */
slouken@4429
   582
extern DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type);
slouken@4429
   583
extern DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType);
slouken@4429
   584
slouken@4429
   585
/**
slouken@4429
   586
 *  This function clears events from the event queue
slouken@9002
   587
 *  This function only affects currently queued events. If you want to make
slouken@9002
   588
 *  sure that all pending OS events are flushed, you can call SDL_PumpEvents()
slouken@9002
   589
 *  on the main thread immediately before the flush call.
slouken@4429
   590
 */
slouken@4429
   591
extern DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type);
slouken@4429
   592
extern DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType);
slouken@0
   593
slouken@3407
   594
/**
slouken@3407
   595
 *  \brief Polls for currently pending events.
slouken@7191
   596
 *
slouken@3407
   597
 *  \return 1 if there are any pending events, or 0 if there are none available.
slouken@7191
   598
 *
slouken@7191
   599
 *  \param event If not NULL, the next event is removed from the queue and
slouken@3407
   600
 *               stored in that area.
slouken@0
   601
 */
slouken@1895
   602
extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
slouken@0
   603
slouken@3407
   604
/**
slouken@3407
   605
 *  \brief Waits indefinitely for the next available event.
slouken@7191
   606
 *
slouken@3407
   607
 *  \return 1, or 0 if there was an error while waiting for events.
slouken@7191
   608
 *
slouken@7191
   609
 *  \param event If not NULL, the next event is removed from the queue and
slouken@3407
   610
 *               stored in that area.
slouken@0
   611
 */
slouken@1895
   612
extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event * event);
slouken@0
   613
slouken@3407
   614
/**
slouken@7191
   615
 *  \brief Waits until the specified timeout (in milliseconds) for the next
slouken@3407
   616
 *         available event.
slouken@7191
   617
 *
slouken@3407
   618
 *  \return 1, or 0 if there was an error while waiting for events.
slouken@7191
   619
 *
slouken@7191
   620
 *  \param event If not NULL, the next event is removed from the queue and
slouken@3407
   621
 *               stored in that area.
philipp@7188
   622
 *  \param timeout The timeout (in milliseconds) to wait for next event.
slouken@3072
   623
 */
slouken@3072
   624
extern DECLSPEC int SDLCALL SDL_WaitEventTimeout(SDL_Event * event,
slouken@3072
   625
                                                 int timeout);
slouken@3072
   626
slouken@3407
   627
/**
slouken@3407
   628
 *  \brief Add an event to the event queue.
slouken@7191
   629
 *
slouken@7191
   630
 *  \return 1 on success, 0 if the event was filtered, or -1 if the event queue
slouken@3407
   631
 *          was full or there was some other error.
slouken@0
   632
 */
slouken@1895
   633
extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event);
slouken@0
   634
slouken@3407
   635
typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event);
slouken@0
   636
slouken@3407
   637
/**
slouken@3407
   638
 *  Sets up a filter to process all events before they change internal state and
slouken@3407
   639
 *  are posted to the internal event queue.
slouken@7191
   640
 *
philipp@7125
   641
 *  The filter is prototyped as:
slouken@3407
   642
 *  \code
slouken@3407
   643
 *      int SDL_EventFilter(void *userdata, SDL_Event * event);
slouken@3407
   644
 *  \endcode
slouken@3407
   645
 *
slouken@3407
   646
 *  If the filter returns 1, then the event will be added to the internal queue.
slouken@7191
   647
 *  If it returns 0, then the event will be dropped from the queue, but the
slouken@3407
   648
 *  internal state will still be updated.  This allows selective filtering of
slouken@3407
   649
 *  dynamically arriving events.
slouken@7191
   650
 *
slouken@7191
   651
 *  \warning  Be very careful of what you do in the event filter function, as
slouken@3407
   652
 *            it may run in a different thread!
slouken@7191
   653
 *
philipp@7278
   654
 *  There is one caveat when dealing with the ::SDL_QuitEvent event type.  The
slouken@3407
   655
 *  event filter is only called when the window manager desires to close the
slouken@3407
   656
 *  application window.  If the event filter returns 1, then the window will
slouken@3407
   657
 *  be closed, otherwise the window will remain open if possible.
slouken@3407
   658
 *
slouken@3407
   659
 *  If the quit event is generated by an interrupt signal, it will bypass the
slouken@3407
   660
 *  internal queue and be delivered to the application at the next event poll.
slouken@3407
   661
 */
slouken@1895
   662
extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter,
slouken@1895
   663
                                                void *userdata);
slouken@0
   664
slouken@3407
   665
/**
slouken@3407
   666
 *  Return the current event filter - can be used to "chain" filters.
slouken@3407
   667
 *  If there is no event filter set, this function returns SDL_FALSE.
slouken@3407
   668
 */
slouken@1895
   669
extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter * filter,
slouken@1895
   670
                                                    void **userdata);
slouken@1895
   671
slouken@3407
   672
/**
slouken@5146
   673
 *  Add a function which is called when an event is added to the queue.
slouken@5146
   674
 */
slouken@5146
   675
extern DECLSPEC void SDLCALL SDL_AddEventWatch(SDL_EventFilter filter,
slouken@5146
   676
                                               void *userdata);
slouken@5146
   677
slouken@5146
   678
/**
slouken@5146
   679
 *  Remove an event watch function added with SDL_AddEventWatch()
slouken@5146
   680
 */
slouken@5146
   681
extern DECLSPEC void SDLCALL SDL_DelEventWatch(SDL_EventFilter filter,
slouken@5146
   682
                                               void *userdata);
slouken@5146
   683
slouken@5146
   684
/**
slouken@3407
   685
 *  Run the filter function on the current event queue, removing any
slouken@3407
   686
 *  events for which the filter returns 0.
slouken@3407
   687
 */
slouken@1895
   688
extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter,
slouken@1895
   689
                                              void *userdata);
slouken@0
   690
gabomdq@7678
   691
/* @{ */
slouken@7191
   692
#define SDL_QUERY   -1
slouken@7191
   693
#define SDL_IGNORE   0
slouken@7191
   694
#define SDL_DISABLE  0
slouken@7191
   695
#define SDL_ENABLE   1
slouken@3407
   696
slouken@3407
   697
/**
slouken@3407
   698
 *  This function allows you to set the state of processing certain events.
slouken@7191
   699
 *   - If \c state is set to ::SDL_IGNORE, that event will be automatically
slouken@3407
   700
 *     dropped from the event queue and will not event be filtered.
slouken@7191
   701
 *   - If \c state is set to ::SDL_ENABLE, that event will be processed
slouken@3407
   702
 *     normally.
slouken@7191
   703
 *   - If \c state is set to ::SDL_QUERY, SDL_EventState() will return the
slouken@3407
   704
 *     current processing state of the specified event.
slouken@3407
   705
 */
slouken@4429
   706
extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint32 type, int state);
gabomdq@7678
   707
/* @} */
slouken@4429
   708
#define SDL_GetEventState(type) SDL_EventState(type, SDL_QUERY)
slouken@4429
   709
slouken@4429
   710
/**
slouken@4429
   711
 *  This function allocates a set of user-defined events, and returns
slouken@4429
   712
 *  the beginning event number for that set of events.
slouken@4429
   713
 *
slouken@4429
   714
 *  If there aren't enough user-defined events left, this function
slouken@4429
   715
 *  returns (Uint32)-1
slouken@4429
   716
 */
slouken@4429
   717
extern DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents);
slouken@0
   718
slouken@0
   719
/* Ends C function definitions when using C++ */
slouken@0
   720
#ifdef __cplusplus
slouken@0
   721
}
slouken@0
   722
#endif
slouken@0
   723
#include "close_code.h"
slouken@0
   724
slouken@0
   725
#endif /* _SDL_events_h */
slouken@1895
   726
slouken@1895
   727
/* vi: set ts=4 sw=4 expandtab: */