mouse.get/set_relative_mode() instead of `_sdl2.Window.relative_mou…

…se` (#2076)

* add get_relative_mode and set_relative_mode

* remove Window.relative_mouse


---------

Co-authored-by: Dan Lawrence <[email protected]>

buildconfig/stubs/pygame/mouse.pyi

@@ -33,3 +33,5 @@ def set_cursor(
 def set_cursor(hotspot: IntCoordinate, surface: Surface) -> None: ...
 def get_cursor() -> Cursor: ...
 def set_system_cursor(cursor: int) -> None: ...
+def get_relative_mode() -> bool: ...
+def set_relative_mode(enable: bool) -> None: ...

docs/reST/ref/mouse.rst

@@ -216,4 +216,31 @@ scroll, such as ``which`` (it will tell you what exact mouse device trigger the
 
    .. ## pygame.mouse.get_cursor ##
 
+.. function:: get_relative_mode
+
+   | :sl:`query whether relative mouse mode is enabled`
+   | :sg:`get_relative_mode() -> bool`
+
+   Query whether relative mouse mode is enabled.
+
+   .. ## pygame.mouse.get_relative_mode ##
+
+.. function:: set_relative_mode
+
+   | :sl:`set relative mouse mode`
+   | :sg:`set_relative_mode(enable) -> None`
+
+   Sets the relative mouse mode state.
+   While the mouse is in relative mode, the cursor is hidden,
+   the mouse position is constrained to the window, and pygame
+   will report continuous relative mouse motion even if the 
+   mouse is at the edge of the window.
+
+   *This function will flush any pending mouse motion."*
+
+   Calling :func:`pygame.mouse.set_visible` with argument
+   ``True`` will exit relative mouse mode.
+
+   .. ## pygame.mouse.set_relative_mode ##
+
 .. ## pygame.mouse ##

docs/reST/ref/sdl2_video.rst

@@ -179,22 +179,6 @@
 
       .. versionadded:: 2.4.0
 
-   .. attribute:: relative_mouse
-
-      | :sl:`Get or set the window's relative mouse mode state`
-      | :sg:`relative_mouse -> bool`
-
-      Gets or sets the window's relative mouse mode state.
-      SDL2 docs: *"While the mouse is in relative mode, the cursor is hidden,
-      the mouse position is constrained to the window, and SDL will report
-      continuous relative mouse motion even if the mouse is at the edge of the
-      window.*
-
-      *This function will flush any pending mouse motion."*
-
-      Calling :func:`pygame.mouse.set_visible` with argument
-      ``True`` will exit relative mouse mode.
-
    .. attribute:: title
 
       | :sl:`Get or set the window title`

src_c/doc/mouse_doc.h

@@ -9,3 +9,5 @@
 #define DOC_MOUSE_GETFOCUSED "get_focused() -> bool\ncheck if the display is receiving mouse input"
 #define DOC_MOUSE_SETCURSOR "set_cursor(pygame.cursors.Cursor) -> None\nset_cursor(size, hotspot, xormasks, andmasks) -> None\nset_cursor(hotspot, surface) -> None\nset_cursor(constant) -> None\nset the mouse cursor to a new cursor"
 #define DOC_MOUSE_GETCURSOR "get_cursor() -> pygame.cursors.Cursor\nget the current mouse cursor"
+#define DOC_MOUSE_GETRELATIVEMODE "get_relative_mode() -> bool\nquery whether relative mouse mode is enabled"
+#define DOC_MOUSE_SETRELATIVEMODE "set_relative_mode(enable) -> None\nset relative mouse mode"

src_c/doc/sdl2_video_doc.h

@@ -9,7 +9,6 @@
 #define DOC_SDL2_VIDEO_WINDOW_GRABKEYBOARD "grab_keyboard -> bool\nGet or set the window's keyboard grab mode"
 #define DOC_SDL2_VIDEO_WINDOW_MOUSEGRABBED "mouse_grabbed -> bool\nGet if the mouse cursor is confined to the window (**read-only**)"
 #define DOC_SDL2_VIDEO_WINDOW_KEYBOARDGRABBED "keyboard_grabbed -> bool\nGet if the keyboard shortcuts are captured by the window (**read-only**)"
-#define DOC_SDL2_VIDEO_WINDOW_RELATIVEMOUSE "relative_mouse -> bool\nGet or set the window's relative mouse mode state"
 #define DOC_SDL2_VIDEO_WINDOW_TITLE "title -> str\nGet or set the window title"
 #define DOC_SDL2_VIDEO_WINDOW_RESIZABLE "resizable -> bool\nGet or set whether the window is resizable"
 #define DOC_SDL2_VIDEO_WINDOW_BORDERLESS "borderless -> bool\nGet or set whether the window is borderless"

src_c/mouse.c

@@ -215,7 +215,7 @@ mouse_get_visible(PyObject *self, PyObject *_null)
 
     VIDEO_INIT_CHECK();
 
-    result = PG_CursorVisible();
+    result = (PG_CursorVisible() && !SDL_GetRelativeMouseMode());
 
     if (0 > result) {
         return RAISE(pgExc_SDLError, SDL_GetError());
@@ -472,6 +472,25 @@ mouse_get_cursor(PyObject *self, PyObject *_null)
     return RAISE(pgExc_SDLError, "Cursor not found");
 }
 
+static PyObject *
+mouse_get_relative_mode(PyObject *self)
+{
+    return PyBool_FromLong(SDL_GetRelativeMouseMode());
+}
+
+static PyObject *
+mouse_set_relative_mode(PyObject *self, PyObject *arg)
+{
+    int mode = PyObject_IsTrue(arg);
+    if (mode == -1) {
+        return NULL;
+    }
+    if (SDL_SetRelativeMouseMode((SDL_bool)mode)) {
+        return RAISE(pgExc_SDLError, SDL_GetError());
+    }
+    Py_RETURN_NONE;
+}
+
 static PyMethodDef _mouse_methods[] = {
     {"set_pos", mouse_set_pos, METH_VARARGS, DOC_MOUSE_SETPOS},
     {"get_pos", (PyCFunction)mouse_get_pos, METH_NOARGS, DOC_MOUSE_GETPOS},
@@ -485,6 +504,10 @@ static PyMethodDef _mouse_methods[] = {
     {"set_system_cursor", mouse_set_system_cursor, METH_VARARGS,
      "set_system_cursor(constant) -> None\nset the mouse cursor to a system "
      "variant"},
+    {"get_relative_mode", (PyCFunction)mouse_get_relative_mode, METH_NOARGS,
+     DOC_MOUSE_GETRELATIVEMODE},
+    {"set_relative_mode", (PyCFunction)mouse_set_relative_mode, METH_O,
+     DOC_MOUSE_SETRELATIVEMODE},
     {"_set_cursor", (PyCFunction)mouse_set_cursor,
      METH_VARARGS | METH_KEYWORDS, "Internal API for mouse.set_cursor"},
     {"_get_cursor", (PyCFunction)mouse_get_cursor, METH_NOARGS,

src_c/window.c

@@ -711,26 +711,6 @@ window_get_display_index(pgWindowObject *self, PyObject *_null)
     return PyLong_FromLong(index);
 }
 
-static PyObject *
-mouse_get_relative_mode(pgWindowObject *self, void *v)
-{
-    return PyBool_FromLong(SDL_GetRelativeMouseMode());
-}
-
-static int
-mouse_set_relative_mode(pgWindowObject *self, PyObject *arg, void *v)
-{
-    SDL_bool mode = SDL_FALSE;
-    if (PyObject_IsTrue(arg)) {
-        mode = SDL_TRUE;
-    }
-    if (SDL_SetRelativeMouseMode(mode)) {
-        PyErr_SetString(pgExc_SDLError, SDL_GetError());
-        return -1;
-    }
-    return 0;
-}
-
 static void
 window_dealloc(pgWindowObject *self, PyObject *_null)
 {
@@ -1081,9 +1061,6 @@ static PyGetSetDef _window_getset[] = {
     {"always_on_top", (getter)window_get_always_on_top,
      (setter)window_set_always_on_top, DOC_SDL2_VIDEO_WINDOW_ALWAYSONTOP,
      NULL},
-    {"relative_mouse", (getter)mouse_get_relative_mode,
-     (setter)mouse_set_relative_mode, DOC_SDL2_VIDEO_WINDOW_RELATIVEMOUSE,
-     NULL},
     {"mouse_rect", (getter)window_get_mouse_rect,
      (setter)window_set_mouse_rect, DOC_SDL2_VIDEO_WINDOW_MOUSERECT, NULL},
     {"size", (getter)window_get_size, (setter)window_set_size,

test/mouse_test.py

@@ -341,6 +341,31 @@ def test_set_visible__invalid_value(self):
             with self.assertRaises(TypeError):
                 prev_visible = pygame.mouse.set_visible(invalid_value)
 
+    @unittest.skipIf(
+        os.environ.get("SDL_VIDEODRIVER", "") == "dummy",
+        "mouse.set_relative_mode requires non-null video driver",
+    )
+    def test_set_relative_mode(self):
+        """Tests that set_relative_mode hides the cursor."""
+        pygame.mouse.set_visible(True)
+        pygame.mouse.set_relative_mode(True)  # sets the mouse invisible
+        visible = pygame.mouse.get_visible()
+        self.assertEqual(visible, False)
+        pygame.mouse.set_relative_mode(False)  # sets the mouse visible
+        visible = pygame.mouse.get_visible()
+        self.assertEqual(visible, True)
+
+    @unittest.skipIf(
+        os.environ.get("SDL_VIDEODRIVER", "") == "dummy",
+        "mouse.set_relative_mode requires non-null video driver",
+    )
+    def test_get_relative_mode(self):
+        """Tests that get_relative_mode correctly reports the relative mode"""
+        pygame.mouse.set_relative_mode(True)
+        self.assertEqual(pygame.mouse.get_relative_mode(), True)
+        pygame.mouse.set_relative_mode(False)
+        self.assertEqual(pygame.mouse.get_relative_mode(), False)
+
 
 ################################################################################