include/SDL_mouse.h
author Steven M. Vascellaro <svascellaro@gmail.com>
Mon, 22 Oct 2018 10:55:18 -0400
changeset 12379 5dc13016cf34
parent 11811 5d94cb6b24d3
child 12503 806492103856
permissions -rw-r--r--
joystick: Add Linux mappings for "Xbox One Wireless Controller (Model 1708)"

Adds controller bindings to support the "Xbox One Wireless Controller
(Model 1708)" on Linux. The Model 1708 was released in 2016 alongside the
Xbox One S. It is the current model being sold by Microsoft as of writing.
(October 22, 2018)
slouken@0
     1
/*
slouken@5535
     2
  Simple DirectMedia Layer
slouken@11811
     3
  Copyright (C) 1997-2018 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@10638
    28
#ifndef SDL_mouse_h_
slouken@10638
    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
philipp@11065
    41
typedef struct SDL_Cursor SDL_Cursor;   /**< Implementation dependent */
slouken@0
    42
mikesart@6675
    43
/**
philipp@10213
    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
urkle@9257
    63
/**
urkle@9257
    64
 * \brief Scroll direction types for the Scroll event
urkle@9257
    65
 */
urkle@9257
    66
typedef enum
urkle@9257
    67
{
urkle@9257
    68
    SDL_MOUSEWHEEL_NORMAL,    /**< The scroll direction is normal */
urkle@9257
    69
    SDL_MOUSEWHEEL_FLIPPED    /**< The scroll direction is flipped / natural */
urkle@9257
    70
} SDL_MouseWheelDirection;
urkle@9257
    71
slouken@0
    72
/* Function prototypes */
slouken@1895
    73
slouken@1895
    74
/**
slouken@4465
    75
 *  \brief Get the window which currently has mouse focus.
slouken@1895
    76
 */
slouken@4465
    77
extern DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void);
slouken@1895
    78
slouken@1895
    79
/**
slouken@4465
    80
 *  \brief Retrieve the current state of the mouse.
slouken@7191
    81
 *
slouken@4465
    82
 *  The current button state is returned as a button bitmask, which can
slouken@4465
    83
 *  be tested using the SDL_BUTTON(X) macros, and x and y are set to the
slouken@4465
    84
 *  mouse cursor position relative to the focus window for the currently
slouken@4465
    85
 *  selected mouse.  You can pass NULL for either x or y.
kazeuser@2718
    86
 */
slouken@6673
    87
extern DECLSPEC Uint32 SDLCALL SDL_GetMouseState(int *x, int *y);
kazeuser@2718
    88
kazeuser@2718
    89
/**
icculus@8945
    90
 *  \brief Get the current state of the mouse, in relation to the desktop
icculus@8945
    91
 *
icculus@8945
    92
 *  This works just like SDL_GetMouseState(), but the coordinates will be
icculus@8945
    93
 *  reported relative to the top-left of the desktop. This can be useful if
icculus@8945
    94
 *  you need to track the mouse outside of a specific window and
icculus@8945
    95
 *  SDL_CaptureMouse() doesn't fit your needs. For example, it could be
icculus@8945
    96
 *  useful if you need to track the mouse while dragging a window, where
icculus@8945
    97
 *  coordinates relative to a window might not be in sync at all times.
icculus@8945
    98
 *
icculus@8945
    99
 *  \note SDL_GetMouseState() returns the mouse position as SDL understands
icculus@8945
   100
 *        it from the last pump of the event queue. This function, however,
icculus@8945
   101
 *        queries the OS for the current mouse position, and as such, might
icculus@8945
   102
 *        be a slightly less efficient function. Unless you know what you're
icculus@8945
   103
 *        doing and have a good reason to use this function, you probably want
icculus@8945
   104
 *        SDL_GetMouseState() instead.
icculus@8945
   105
 *
icculus@8945
   106
 *  \param x Returns the current X coord, relative to the desktop. Can be NULL.
icculus@8945
   107
 *  \param y Returns the current Y coord, relative to the desktop. Can be NULL.
icculus@8945
   108
 *  \return The current button state as a bitmask, which can be tested using the SDL_BUTTON(X) macros.
icculus@8945
   109
 *
icculus@8945
   110
 *  \sa SDL_GetMouseState
icculus@8945
   111
 */
icculus@8952
   112
extern DECLSPEC Uint32 SDLCALL SDL_GetGlobalMouseState(int *x, int *y);
icculus@8945
   113
icculus@8945
   114
/**
slouken@4465
   115
 *  \brief Retrieve the relative state of the mouse.
slouken@4465
   116
 *
slouken@4465
   117
 *  The current button state is returned as a button bitmask, which can
slouken@4465
   118
 *  be tested using the SDL_BUTTON(X) macros, and x and y are set to the
slouken@4465
   119
 *  mouse deltas since the last call to SDL_GetRelativeMouseState().
slouken@1895
   120
 */
slouken@6673
   121
extern DECLSPEC Uint32 SDLCALL SDL_GetRelativeMouseState(int *x, int *y);
slouken@1895
   122
slouken@1895
   123
/**
slouken@4465
   124
 *  \brief Moves the mouse to the given position within the window.
slouken@7191
   125
 *
slouken@4465
   126
 *  \param window The window to move the mouse into, or NULL for the current mouse focus
slouken@4465
   127
 *  \param x The x coordinate within the window
slouken@4465
   128
 *  \param y The y coordinate within the window
slouken@7191
   129
 *
slouken@4465
   130
 *  \note This function generates a mouse motion event
slouken@1895
   131
 */
slouken@4465
   132
extern DECLSPEC void SDLCALL SDL_WarpMouseInWindow(SDL_Window * window,
slouken@4465
   133
                                                   int x, int y);
slouken@1895
   134
slouken@1895
   135
/**
slouken@8815
   136
 *  \brief Moves the mouse to the given position in global screen space.
slouken@8815
   137
 *
slouken@8815
   138
 *  \param x The x coordinate
slouken@8815
   139
 *  \param y The y coordinate
icculus@9807
   140
 *  \return 0 on success, -1 on error (usually: unsupported by a platform).
slouken@8815
   141
 *
slouken@8815
   142
 *  \note This function generates a mouse motion event
slouken@8815
   143
 */
icculus@9807
   144
extern DECLSPEC int SDLCALL SDL_WarpMouseGlobal(int x, int y);
slouken@8815
   145
slouken@8815
   146
/**
slouken@4465
   147
 *  \brief Set relative mouse mode.
slouken@7191
   148
 *
slouken@3407
   149
 *  \param enabled Whether or not to enable relative mode
slouken@4465
   150
 *
slouken@3407
   151
 *  \return 0 on success, or -1 if relative mode is not supported.
slouken@7191
   152
 *
slouken@3407
   153
 *  While the mouse is in relative mode, the cursor is hidden, and the
slouken@3407
   154
 *  driver will try to report continuous motion in the current window.
slouken@3407
   155
 *  Only relative motion events will be delivered, the mouse position
slouken@3407
   156
 *  will not change.
slouken@7191
   157
 *
slouken@3407
   158
 *  \note This function will flush any pending mouse motion.
slouken@7191
   159
 *
slouken@3407
   160
 *  \sa SDL_GetRelativeMouseMode()
slouken@1895
   161
 */
slouken@4465
   162
extern DECLSPEC int SDLCALL SDL_SetRelativeMouseMode(SDL_bool enabled);
slouken@1895
   163
slouken@1895
   164
/**
icculus@8927
   165
 *  \brief Capture the mouse, to track input outside an SDL window.
icculus@8927
   166
 *
icculus@8927
   167
 *  \param enabled Whether or not to enable capturing
icculus@8927
   168
 *
icculus@8927
   169
 *  Capturing enables your app to obtain mouse events globally, instead of
icculus@8927
   170
 *  just within your window. Not all video targets support this function.
icculus@8927
   171
 *  When capturing is enabled, the current window will get all mouse events,
icculus@8927
   172
 *  but unlike relative mode, no change is made to the cursor and it is
icculus@8927
   173
 *  not restrained to your window.
icculus@8927
   174
 *
icculus@8927
   175
 *  This function may also deny mouse input to other windows--both those in
icculus@8927
   176
 *  your application and others on the system--so you should use this
icculus@8927
   177
 *  function sparingly, and in small bursts. For example, you might want to
icculus@8927
   178
 *  track the mouse while the user is dragging something, until the user
icculus@8927
   179
 *  releases a mouse button. It is not recommended that you capture the mouse
icculus@8927
   180
 *  for long periods of time, such as the entire time your app is running.
icculus@8927
   181
 *
icculus@8927
   182
 *  While captured, mouse events still report coordinates relative to the
icculus@8927
   183
 *  current (foreground) window, but those coordinates may be outside the
icculus@8927
   184
 *  bounds of the window (including negative values). Capturing is only
icculus@8927
   185
 *  allowed for the foreground window. If the window loses focus while
icculus@8927
   186
 *  capturing, the capture will be disabled automatically.
icculus@8927
   187
 *
icculus@8927
   188
 *  While capturing is enabled, the current window will have the
icculus@8927
   189
 *  SDL_WINDOW_MOUSE_CAPTURE flag set.
icculus@8927
   190
 *
icculus@8927
   191
 *  \return 0 on success, or -1 if not supported.
icculus@8927
   192
 */
icculus@8927
   193
extern DECLSPEC int SDLCALL SDL_CaptureMouse(SDL_bool enabled);
icculus@8927
   194
icculus@8927
   195
/**
slouken@4465
   196
 *  \brief Query whether relative mouse mode is enabled.
slouken@7191
   197
 *
slouken@3407
   198
 *  \sa SDL_SetRelativeMouseMode()
slouken@1895
   199
 */
slouken@4465
   200
extern DECLSPEC SDL_bool SDLCALL SDL_GetRelativeMouseMode(void);
slouken@1895
   201
slouken@1895
   202
/**
slouken@4465
   203
 *  \brief Create a cursor, using the specified bitmap data and
slouken@4465
   204
 *         mask (in MSB format).
slouken@7191
   205
 *
slouken@3407
   206
 *  The cursor width must be a multiple of 8 bits.
slouken@7191
   207
 *
slouken@3407
   208
 *  The cursor is created in black and white according to the following:
slouken@3407
   209
 *  <table>
slouken@3407
   210
 *  <tr><td> data </td><td> mask </td><td> resulting pixel on screen </td></tr>
slouken@3407
   211
 *  <tr><td>  0   </td><td>  1   </td><td> White </td></tr>
slouken@3407
   212
 *  <tr><td>  1   </td><td>  1   </td><td> Black </td></tr>
slouken@3407
   213
 *  <tr><td>  0   </td><td>  0   </td><td> Transparent </td></tr>
slouken@7191
   214
 *  <tr><td>  1   </td><td>  0   </td><td> Inverted color if possible, black
slouken@4465
   215
 *                                         if not. </td></tr>
slouken@3407
   216
 *  </table>
slouken@7191
   217
 *
slouken@3407
   218
 *  \sa SDL_FreeCursor()
slouken@0
   219
 */
slouken@1895
   220
extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateCursor(const Uint8 * data,
slouken@1895
   221
                                                     const Uint8 * mask,
slouken@1895
   222
                                                     int w, int h, int hot_x,
slouken@1895
   223
                                                     int hot_y);
slouken@0
   224
slouken@1895
   225
/**
slouken@5473
   226
 *  \brief Create a color cursor.
slouken@7191
   227
 *
slouken@5473
   228
 *  \sa SDL_FreeCursor()
slouken@5473
   229
 */
slouken@5473
   230
extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateColorCursor(SDL_Surface *surface,
slouken@5473
   231
                                                          int hot_x,
slouken@5473
   232
                                                          int hot_y);
slouken@5473
   233
slouken@5473
   234
/**
mikesart@6675
   235
 *  \brief Create a system cursor.
mikesart@6675
   236
 *
mikesart@6675
   237
 *  \sa SDL_FreeCursor()
mikesart@6675
   238
 */
mikesart@6675
   239
extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateSystemCursor(SDL_SystemCursor id);
mikesart@6675
   240
mikesart@6675
   241
/**
slouken@4465
   242
 *  \brief Set the active cursor.
slouken@0
   243
 */
slouken@1895
   244
extern DECLSPEC void SDLCALL SDL_SetCursor(SDL_Cursor * cursor);
slouken@0
   245
slouken@1895
   246
/**
slouken@4465
   247
 *  \brief Return the active cursor.
slouken@0
   248
 */
slouken@1895
   249
extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetCursor(void);
slouken@0
   250
slouken@1895
   251
/**
jorgen@7104
   252
 *  \brief Return the default cursor.
jorgen@7104
   253
 */
jorgen@7104
   254
extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetDefaultCursor(void);
jorgen@7104
   255
jorgen@7104
   256
/**
philipp@10160
   257
 *  \brief Frees a cursor created with SDL_CreateCursor() or similar functions.
slouken@7191
   258
 *
slouken@3407
   259
 *  \sa SDL_CreateCursor()
philipp@10160
   260
 *  \sa SDL_CreateColorCursor()
philipp@10160
   261
 *  \sa SDL_CreateSystemCursor()
slouken@0
   262
 */
slouken@1895
   263
extern DECLSPEC void SDLCALL SDL_FreeCursor(SDL_Cursor * cursor);
slouken@0
   264
slouken@1895
   265
/**
slouken@4465
   266
 *  \brief Toggle whether or not the cursor is shown.
slouken@7191
   267
 *
slouken@7191
   268
 *  \param toggle 1 to show the cursor, 0 to hide it, -1 to query the current
slouken@3407
   269
 *                state.
slouken@7191
   270
 *
slouken@3407
   271
 *  \return 1 if the cursor is shown, or 0 if the cursor is hidden.
slouken@0
   272
 */
slouken@337
   273
extern DECLSPEC int SDLCALL SDL_ShowCursor(int toggle);
slouken@0
   274
kazeuser@2718
   275
/**
slouken@3407
   276
 *  Used as a mask when testing buttons in buttonstate.
slouken@3407
   277
 *   - Button 1:  Left mouse button
slouken@3407
   278
 *   - Button 2:  Middle mouse button
slouken@3407
   279
 *   - Button 3:  Right mouse button
slouken@3407
   280
 */
slouken@7191
   281
#define SDL_BUTTON(X)       (1 << ((X)-1))
slouken@7191
   282
#define SDL_BUTTON_LEFT     1
slouken@7191
   283
#define SDL_BUTTON_MIDDLE   2
slouken@7191
   284
#define SDL_BUTTON_RIGHT    3
slouken@7191
   285
#define SDL_BUTTON_X1       4
slouken@7191
   286
#define SDL_BUTTON_X2       5
slouken@7191
   287
#define SDL_BUTTON_LMASK    SDL_BUTTON(SDL_BUTTON_LEFT)
slouken@7191
   288
#define SDL_BUTTON_MMASK    SDL_BUTTON(SDL_BUTTON_MIDDLE)
slouken@7191
   289
#define SDL_BUTTON_RMASK    SDL_BUTTON(SDL_BUTTON_RIGHT)
slouken@7191
   290
#define SDL_BUTTON_X1MASK   SDL_BUTTON(SDL_BUTTON_X1)
slouken@7191
   291
#define SDL_BUTTON_X2MASK   SDL_BUTTON(SDL_BUTTON_X2)
slouken@0
   292
slouken@0
   293
slouken@0
   294
/* Ends C function definitions when using C++ */
slouken@0
   295
#ifdef __cplusplus
slouken@0
   296
}
slouken@0
   297
#endif
slouken@0
   298
#include "close_code.h"
slouken@0
   299
slouken@10638
   300
#endif /* SDL_mouse_h_ */
slouken@1895
   301
slouken@1895
   302
/* vi: set ts=4 sw=4 expandtab: */