Updated SDL2

project/jni/sdl-2.0/include/SDL_mouse.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2013 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -25,8 +25,8 @@
  *  Include file for SDL mouse event handling.
  */
 
-#ifndef _SDL_mouse_h
-#define _SDL_mouse_h
+#ifndef SDL_mouse_h_
+#define SDL_mouse_h_
 
 #include "SDL_stdinc.h"
 #include "SDL_error.h"
@@ -38,10 +38,10 @@
 extern "C" {
 #endif
 
-typedef struct SDL_Cursor SDL_Cursor;   /* Implementation dependent */
+typedef struct SDL_Cursor SDL_Cursor;   /**< Implementation dependent */
 
 /**
- * \brief Cursor types for SDL_CreateSystemCursor.
+ * \brief Cursor types for SDL_CreateSystemCursor().
  */
 typedef enum
 {
@@ -60,6 +60,15 @@ typedef enum
     SDL_NUM_SYSTEM_CURSORS
 } SDL_SystemCursor;
 
+/**
+ * \brief Scroll direction types for the Scroll event
+ */
+typedef enum
+{
+    SDL_MOUSEWHEEL_NORMAL,    /**< The scroll direction is normal */
+    SDL_MOUSEWHEEL_FLIPPED    /**< The scroll direction is flipped / natural */
+} SDL_MouseWheelDirection;
+
 /* Function prototypes */
 
 /**
@@ -77,6 +86,31 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void);
  */
 extern DECLSPEC Uint32 SDLCALL SDL_GetMouseState(int *x, int *y);
 
+/**
+ *  \brief Get the current state of the mouse, in relation to the desktop
+ *
+ *  This works just like SDL_GetMouseState(), but the coordinates will be
+ *  reported relative to the top-left of the desktop. This can be useful if
+ *  you need to track the mouse outside of a specific window and
+ *  SDL_CaptureMouse() doesn't fit your needs. For example, it could be
+ *  useful if you need to track the mouse while dragging a window, where
+ *  coordinates relative to a window might not be in sync at all times.
+ *
+ *  \note SDL_GetMouseState() returns the mouse position as SDL understands
+ *        it from the last pump of the event queue. This function, however,
+ *        queries the OS for the current mouse position, and as such, might
+ *        be a slightly less efficient function. Unless you know what you're
+ *        doing and have a good reason to use this function, you probably want
+ *        SDL_GetMouseState() instead.
+ *
+ *  \param x Returns the current X coord, relative to the desktop. Can be NULL.
+ *  \param y Returns the current Y coord, relative to the desktop. Can be NULL.
+ *  \return The current button state as a bitmask, which can be tested using the SDL_BUTTON(X) macros.
+ *
+ *  \sa SDL_GetMouseState
+ */
+extern DECLSPEC Uint32 SDLCALL SDL_GetGlobalMouseState(int *x, int *y);
+
 /**
  *  \brief Retrieve the relative state of the mouse.
  *
@@ -98,6 +132,17 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetRelativeMouseState(int *x, int *y);
 extern DECLSPEC void SDLCALL SDL_WarpMouseInWindow(SDL_Window * window,
                                                    int x, int y);
 
+/**
+ *  \brief Moves the mouse to the given position in global screen space.
+ *
+ *  \param x The x coordinate
+ *  \param y The y coordinate
+ *  \return 0 on success, -1 on error (usually: unsupported by a platform).
+ *
+ *  \note This function generates a mouse motion event
+ */
+extern DECLSPEC int SDLCALL SDL_WarpMouseGlobal(int x, int y);
+
 /**
  *  \brief Set relative mouse mode.
  *
@@ -116,6 +161,37 @@ extern DECLSPEC void SDLCALL SDL_WarpMouseInWindow(SDL_Window * window,
  */
 extern DECLSPEC int SDLCALL SDL_SetRelativeMouseMode(SDL_bool enabled);
 
+/**
+ *  \brief Capture the mouse, to track input outside an SDL window.
+ *
+ *  \param enabled Whether or not to enable capturing
+ *
+ *  Capturing enables your app to obtain mouse events globally, instead of
+ *  just within your window. Not all video targets support this function.
+ *  When capturing is enabled, the current window will get all mouse events,
+ *  but unlike relative mode, no change is made to the cursor and it is
+ *  not restrained to your window.
+ *
+ *  This function may also deny mouse input to other windows--both those in
+ *  your application and others on the system--so you should use this
+ *  function sparingly, and in small bursts. For example, you might want to
+ *  track the mouse while the user is dragging something, until the user
+ *  releases a mouse button. It is not recommended that you capture the mouse
+ *  for long periods of time, such as the entire time your app is running.
+ *
+ *  While captured, mouse events still report coordinates relative to the
+ *  current (foreground) window, but those coordinates may be outside the
+ *  bounds of the window (including negative values). Capturing is only
+ *  allowed for the foreground window. If the window loses focus while
+ *  capturing, the capture will be disabled automatically.
+ *
+ *  While capturing is enabled, the current window will have the
+ *  SDL_WINDOW_MOUSE_CAPTURE flag set.
+ *
+ *  \return 0 on success, or -1 if not supported.
+ */
+extern DECLSPEC int SDLCALL SDL_CaptureMouse(SDL_bool enabled);
+
 /**
  *  \brief Query whether relative mouse mode is enabled.
  *
@@ -178,9 +254,11 @@ extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetCursor(void);
 extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetDefaultCursor(void);
 
 /**
- *  \brief Frees a cursor created with SDL_CreateCursor().
+ *  \brief Frees a cursor created with SDL_CreateCursor() or similar functions.
  *
  *  \sa SDL_CreateCursor()
+ *  \sa SDL_CreateColorCursor()
+ *  \sa SDL_CreateSystemCursor()
  */
 extern DECLSPEC void SDLCALL SDL_FreeCursor(SDL_Cursor * cursor);
 
@@ -219,6 +297,6 @@ extern DECLSPEC int SDLCALL SDL_ShowCursor(int toggle);
 #endif
 #include "close_code.h"
 
-#endif /* _SDL_mouse_h */
+#endif /* SDL_mouse_h_ */
 
 /* vi: set ts=4 sw=4 expandtab: */