include/SDL_mouse.h
author David Ludwig <dludwig@pobox.com>
Sat, 29 Nov 2014 10:09:30 -0500
changeset 9247 eddb899239fe
parent 8953 dc80dc0bd22e
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_mouse.h
slouken@7191
    24
 *
slouken@3407
    25
 *  Include file for SDL mouse event handling.
slouken@1895
    26
 */
slouken@0
    27
slouken@0
    28
#ifndef _SDL_mouse_h
slouken@0
    29
#define _SDL_mouse_h
slouken@0
    30
slouken@1356
    31
#include "SDL_stdinc.h"
slouken@1358
    32
#include "SDL_error.h"
slouken@0
    33
#include "SDL_video.h"
slouken@0
    34
slouken@0
    35
#include "begin_code.h"
slouken@0
    36
/* Set up for C function definitions, even when using C++ */
slouken@0
    37
#ifdef __cplusplus
slouken@0
    38
extern "C" {
slouken@0
    39
#endif
slouken@0
    40
slouken@1895
    41
typedef struct SDL_Cursor SDL_Cursor;   /* Implementation dependent */
slouken@0
    42
mikesart@6675
    43
/**
mikesart@6675
    44
 * \brief Cursor types for SDL_CreateSystemCursor.
mikesart@6675
    45
 */
mikesart@6675
    46
typedef enum
mikesart@6675
    47
{
icculus@7067
    48
    SDL_SYSTEM_CURSOR_ARROW,     /**< Arrow */
icculus@7067
    49
    SDL_SYSTEM_CURSOR_IBEAM,     /**< I-beam */
icculus@7067
    50
    SDL_SYSTEM_CURSOR_WAIT,      /**< Wait */
icculus@7067
    51
    SDL_SYSTEM_CURSOR_CROSSHAIR, /**< Crosshair */
icculus@7067
    52
    SDL_SYSTEM_CURSOR_WAITARROW, /**< Small wait cursor (or Wait if not available) */
icculus@7067
    53
    SDL_SYSTEM_CURSOR_SIZENWSE,  /**< Double arrow pointing northwest and southeast */
icculus@7067
    54
    SDL_SYSTEM_CURSOR_SIZENESW,  /**< Double arrow pointing northeast and southwest */
icculus@7067
    55
    SDL_SYSTEM_CURSOR_SIZEWE,    /**< Double arrow pointing west and east */
icculus@7067
    56
    SDL_SYSTEM_CURSOR_SIZENS,    /**< Double arrow pointing north and south */
icculus@7067
    57
    SDL_SYSTEM_CURSOR_SIZEALL,   /**< Four pointed arrow pointing north, south, east, and west */
icculus@7067
    58
    SDL_SYSTEM_CURSOR_NO,        /**< Slashed circle or crossbones */
icculus@7067
    59
    SDL_SYSTEM_CURSOR_HAND,      /**< Hand */
slouken@6677
    60
    SDL_NUM_SYSTEM_CURSORS
mikesart@6675
    61
} SDL_SystemCursor;
slouken@4465
    62
slouken@0
    63
/* Function prototypes */
slouken@1895
    64
slouken@1895
    65
/**
slouken@4465
    66
 *  \brief Get the window which currently has mouse focus.
slouken@1895
    67
 */
slouken@4465
    68
extern DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void);
slouken@1895
    69
slouken@1895
    70
/**
slouken@4465
    71
 *  \brief Retrieve the current state of the mouse.
slouken@7191
    72
 *
slouken@4465
    73
 *  The current button state is returned as a button bitmask, which can
slouken@4465
    74
 *  be tested using the SDL_BUTTON(X) macros, and x and y are set to the
slouken@4465
    75
 *  mouse cursor position relative to the focus window for the currently
slouken@4465
    76
 *  selected mouse.  You can pass NULL for either x or y.
kazeuser@2718
    77
 */
slouken@6673
    78
extern DECLSPEC Uint32 SDLCALL SDL_GetMouseState(int *x, int *y);
kazeuser@2718
    79
kazeuser@2718
    80
/**
icculus@8945
    81
 *  \brief Get the current state of the mouse, in relation to the desktop
icculus@8945
    82
 *
icculus@8945
    83
 *  This works just like SDL_GetMouseState(), but the coordinates will be
icculus@8945
    84
 *  reported relative to the top-left of the desktop. This can be useful if
icculus@8945
    85
 *  you need to track the mouse outside of a specific window and
icculus@8945
    86
 *  SDL_CaptureMouse() doesn't fit your needs. For example, it could be
icculus@8945
    87
 *  useful if you need to track the mouse while dragging a window, where
icculus@8945
    88
 *  coordinates relative to a window might not be in sync at all times.
icculus@8945
    89
 *
icculus@8945
    90
 *  \note SDL_GetMouseState() returns the mouse position as SDL understands
icculus@8945
    91
 *        it from the last pump of the event queue. This function, however,
icculus@8945
    92
 *        queries the OS for the current mouse position, and as such, might
icculus@8945
    93
 *        be a slightly less efficient function. Unless you know what you're
icculus@8945
    94
 *        doing and have a good reason to use this function, you probably want
icculus@8945
    95
 *        SDL_GetMouseState() instead.
icculus@8945
    96
 *
icculus@8945
    97
 *  \param x Returns the current X coord, relative to the desktop. Can be NULL.
icculus@8945
    98
 *  \param y Returns the current Y coord, relative to the desktop. Can be NULL.
icculus@8945
    99
 *  \return The current button state as a bitmask, which can be tested using the SDL_BUTTON(X) macros.
icculus@8945
   100
 *
icculus@8945
   101
 *  \sa SDL_GetMouseState
icculus@8945
   102
 */
icculus@8952
   103
extern DECLSPEC Uint32 SDLCALL SDL_GetGlobalMouseState(int *x, int *y);
icculus@8945
   104
icculus@8945
   105
/**
slouken@4465
   106
 *  \brief Retrieve the relative state of the mouse.
slouken@4465
   107
 *
slouken@4465
   108
 *  The current button state is returned as a button bitmask, which can
slouken@4465
   109
 *  be tested using the SDL_BUTTON(X) macros, and x and y are set to the
slouken@4465
   110
 *  mouse deltas since the last call to SDL_GetRelativeMouseState().
slouken@1895
   111
 */
slouken@6673
   112
extern DECLSPEC Uint32 SDLCALL SDL_GetRelativeMouseState(int *x, int *y);
slouken@1895
   113
slouken@1895
   114
/**
slouken@4465
   115
 *  \brief Moves the mouse to the given position within the window.
slouken@7191
   116
 *
slouken@4465
   117
 *  \param window The window to move the mouse into, or NULL for the current mouse focus
slouken@4465
   118
 *  \param x The x coordinate within the window
slouken@4465
   119
 *  \param y The y coordinate within the window
slouken@7191
   120
 *
slouken@4465
   121
 *  \note This function generates a mouse motion event
slouken@1895
   122
 */
slouken@4465
   123
extern DECLSPEC void SDLCALL SDL_WarpMouseInWindow(SDL_Window * window,
slouken@4465
   124
                                                   int x, int y);
slouken@1895
   125
slouken@1895
   126
/**
slouken@8815
   127
 *  \brief Moves the mouse to the given position in global screen space.
slouken@8815
   128
 *
slouken@8815
   129
 *  \param x The x coordinate
slouken@8815
   130
 *  \param y The y coordinate
slouken@8815
   131
 *
slouken@8815
   132
 *  \note This function generates a mouse motion event
slouken@8815
   133
 */
slouken@8815
   134
extern DECLSPEC void SDLCALL SDL_WarpMouseGlobal(int x, int y);
slouken@8815
   135
slouken@8815
   136
/**
slouken@4465
   137
 *  \brief Set relative mouse mode.
slouken@7191
   138
 *
slouken@3407
   139
 *  \param enabled Whether or not to enable relative mode
slouken@4465
   140
 *
slouken@3407
   141
 *  \return 0 on success, or -1 if relative mode is not supported.
slouken@7191
   142
 *
slouken@3407
   143
 *  While the mouse is in relative mode, the cursor is hidden, and the
slouken@3407
   144
 *  driver will try to report continuous motion in the current window.
slouken@3407
   145
 *  Only relative motion events will be delivered, the mouse position
slouken@3407
   146
 *  will not change.
slouken@7191
   147
 *
slouken@3407
   148
 *  \note This function will flush any pending mouse motion.
slouken@7191
   149
 *
slouken@3407
   150
 *  \sa SDL_GetRelativeMouseMode()
slouken@1895
   151
 */
slouken@4465
   152
extern DECLSPEC int SDLCALL SDL_SetRelativeMouseMode(SDL_bool enabled);
slouken@1895
   153
slouken@1895
   154
/**
icculus@8927
   155
 *  \brief Capture the mouse, to track input outside an SDL window.
icculus@8927
   156
 *
icculus@8927
   157
 *  \param enabled Whether or not to enable capturing
icculus@8927
   158
 *
icculus@8927
   159
 *  Capturing enables your app to obtain mouse events globally, instead of
icculus@8927
   160
 *  just within your window. Not all video targets support this function.
icculus@8927
   161
 *  When capturing is enabled, the current window will get all mouse events,
icculus@8927
   162
 *  but unlike relative mode, no change is made to the cursor and it is
icculus@8927
   163
 *  not restrained to your window.
icculus@8927
   164
 *
icculus@8927
   165
 *  This function may also deny mouse input to other windows--both those in
icculus@8927
   166
 *  your application and others on the system--so you should use this
icculus@8927
   167
 *  function sparingly, and in small bursts. For example, you might want to
icculus@8927
   168
 *  track the mouse while the user is dragging something, until the user
icculus@8927
   169
 *  releases a mouse button. It is not recommended that you capture the mouse
icculus@8927
   170
 *  for long periods of time, such as the entire time your app is running.
icculus@8927
   171
 *
icculus@8927
   172
 *  While captured, mouse events still report coordinates relative to the
icculus@8927
   173
 *  current (foreground) window, but those coordinates may be outside the
icculus@8927
   174
 *  bounds of the window (including negative values). Capturing is only
icculus@8927
   175
 *  allowed for the foreground window. If the window loses focus while
icculus@8927
   176
 *  capturing, the capture will be disabled automatically.
icculus@8927
   177
 *
icculus@8927
   178
 *  While capturing is enabled, the current window will have the
icculus@8927
   179
 *  SDL_WINDOW_MOUSE_CAPTURE flag set.
icculus@8927
   180
 *
icculus@8927
   181
 *  \return 0 on success, or -1 if not supported.
icculus@8927
   182
 */
icculus@8927
   183
extern DECLSPEC int SDLCALL SDL_CaptureMouse(SDL_bool enabled);
icculus@8927
   184
icculus@8927
   185
/**
slouken@4465
   186
 *  \brief Query whether relative mouse mode is enabled.
slouken@7191
   187
 *
slouken@3407
   188
 *  \sa SDL_SetRelativeMouseMode()
slouken@1895
   189
 */
slouken@4465
   190
extern DECLSPEC SDL_bool SDLCALL SDL_GetRelativeMouseMode(void);
slouken@1895
   191
slouken@1895
   192
/**
slouken@4465
   193
 *  \brief Create a cursor, using the specified bitmap data and
slouken@4465
   194
 *         mask (in MSB format).
slouken@7191
   195
 *
slouken@3407
   196
 *  The cursor width must be a multiple of 8 bits.
slouken@7191
   197
 *
slouken@3407
   198
 *  The cursor is created in black and white according to the following:
slouken@3407
   199
 *  <table>
slouken@3407
   200
 *  <tr><td> data </td><td> mask </td><td> resulting pixel on screen </td></tr>
slouken@3407
   201
 *  <tr><td>  0   </td><td>  1   </td><td> White </td></tr>
slouken@3407
   202
 *  <tr><td>  1   </td><td>  1   </td><td> Black </td></tr>
slouken@3407
   203
 *  <tr><td>  0   </td><td>  0   </td><td> Transparent </td></tr>
slouken@7191
   204
 *  <tr><td>  1   </td><td>  0   </td><td> Inverted color if possible, black
slouken@4465
   205
 *                                         if not. </td></tr>
slouken@3407
   206
 *  </table>
slouken@7191
   207
 *
slouken@3407
   208
 *  \sa SDL_FreeCursor()
slouken@0
   209
 */
slouken@1895
   210
extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateCursor(const Uint8 * data,
slouken@1895
   211
                                                     const Uint8 * mask,
slouken@1895
   212
                                                     int w, int h, int hot_x,
slouken@1895
   213
                                                     int hot_y);
slouken@0
   214
slouken@1895
   215
/**
slouken@5473
   216
 *  \brief Create a color cursor.
slouken@7191
   217
 *
slouken@5473
   218
 *  \sa SDL_FreeCursor()
slouken@5473
   219
 */
slouken@5473
   220
extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateColorCursor(SDL_Surface *surface,
slouken@5473
   221
                                                          int hot_x,
slouken@5473
   222
                                                          int hot_y);
slouken@5473
   223
slouken@5473
   224
/**
mikesart@6675
   225
 *  \brief Create a system cursor.
mikesart@6675
   226
 *
mikesart@6675
   227
 *  \sa SDL_FreeCursor()
mikesart@6675
   228
 */
mikesart@6675
   229
extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateSystemCursor(SDL_SystemCursor id);
mikesart@6675
   230
mikesart@6675
   231
/**
slouken@4465
   232
 *  \brief Set the active cursor.
slouken@0
   233
 */
slouken@1895
   234
extern DECLSPEC void SDLCALL SDL_SetCursor(SDL_Cursor * cursor);
slouken@0
   235
slouken@1895
   236
/**
slouken@4465
   237
 *  \brief Return the active cursor.
slouken@0
   238
 */
slouken@1895
   239
extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetCursor(void);
slouken@0
   240
slouken@1895
   241
/**
jorgen@7104
   242
 *  \brief Return the default cursor.
jorgen@7104
   243
 */
jorgen@7104
   244
extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetDefaultCursor(void);
jorgen@7104
   245
jorgen@7104
   246
/**
slouken@3407
   247
 *  \brief Frees a cursor created with SDL_CreateCursor().
slouken@7191
   248
 *
slouken@3407
   249
 *  \sa SDL_CreateCursor()
slouken@0
   250
 */
slouken@1895
   251
extern DECLSPEC void SDLCALL SDL_FreeCursor(SDL_Cursor * cursor);
slouken@0
   252
slouken@1895
   253
/**
slouken@4465
   254
 *  \brief Toggle whether or not the cursor is shown.
slouken@7191
   255
 *
slouken@7191
   256
 *  \param toggle 1 to show the cursor, 0 to hide it, -1 to query the current
slouken@3407
   257
 *                state.
slouken@7191
   258
 *
slouken@3407
   259
 *  \return 1 if the cursor is shown, or 0 if the cursor is hidden.
slouken@0
   260
 */
slouken@337
   261
extern DECLSPEC int SDLCALL SDL_ShowCursor(int toggle);
slouken@0
   262
kazeuser@2718
   263
/**
slouken@3407
   264
 *  Used as a mask when testing buttons in buttonstate.
slouken@3407
   265
 *   - Button 1:  Left mouse button
slouken@3407
   266
 *   - Button 2:  Middle mouse button
slouken@3407
   267
 *   - Button 3:  Right mouse button
slouken@3407
   268
 */
slouken@7191
   269
#define SDL_BUTTON(X)       (1 << ((X)-1))
slouken@7191
   270
#define SDL_BUTTON_LEFT     1
slouken@7191
   271
#define SDL_BUTTON_MIDDLE   2
slouken@7191
   272
#define SDL_BUTTON_RIGHT    3
slouken@7191
   273
#define SDL_BUTTON_X1       4
slouken@7191
   274
#define SDL_BUTTON_X2       5
slouken@7191
   275
#define SDL_BUTTON_LMASK    SDL_BUTTON(SDL_BUTTON_LEFT)
slouken@7191
   276
#define SDL_BUTTON_MMASK    SDL_BUTTON(SDL_BUTTON_MIDDLE)
slouken@7191
   277
#define SDL_BUTTON_RMASK    SDL_BUTTON(SDL_BUTTON_RIGHT)
slouken@7191
   278
#define SDL_BUTTON_X1MASK   SDL_BUTTON(SDL_BUTTON_X1)
slouken@7191
   279
#define SDL_BUTTON_X2MASK   SDL_BUTTON(SDL_BUTTON_X2)
slouken@0
   280
slouken@0
   281
slouken@0
   282
/* Ends C function definitions when using C++ */
slouken@0
   283
#ifdef __cplusplus
slouken@0
   284
}
slouken@0
   285
#endif
slouken@0
   286
#include "close_code.h"
slouken@0
   287
slouken@0
   288
#endif /* _SDL_mouse_h */
slouken@1895
   289
slouken@1895
   290
/* vi: set ts=4 sw=4 expandtab: */