Add desktop argument to get_pos and get_pressed (#3105)

buildconfig/stubs/pygame/mouse.pyi

@@ -7,12 +7,16 @@ from pygame.surface import Surface
 from pygame.typing import Coordinate, SequenceLike, IntCoordinate
 
 @overload
-def get_pressed(num_buttons: Literal[3] = 3) -> Tuple[bool, bool, bool]: ...
+def get_pressed(
+    num_buttons: Literal[3] = 3,
+    desktop: bool = False) -> Tuple[bool, bool, bool]: ...
 @overload
-def get_pressed(num_buttons: Literal[5]) -> Tuple[bool, bool, bool, bool, bool]: ...
+def get_pressed(
+    num_buttons: Literal[5],
+    desktop: bool = False) -> Tuple[bool, bool, bool, bool, bool]: ...
 def get_just_pressed() -> Tuple[bool, bool, bool, bool, bool]: ...
 def get_just_released() -> Tuple[bool, bool, bool, bool, bool]: ...
-def get_pos() -> Tuple[int, int]: ...
+def get_pos(desktop: bool = False) -> Tuple[int, int]: ...
 def get_rel() -> Tuple[int, int]: ...
 @overload
 def set_pos(pos: Coordinate, /) -> None: ...

docs/reST/ref/mouse.rst

@@ -79,8 +79,8 @@ scroll, such as ``which`` (it will tell you what exact mouse device trigger the
 .. function:: get_pressed
 
    | :sl:`get the state of the mouse buttons`
-   | :sg:`get_pressed(num_buttons=3) -> (left_button, middle_button, right_button)`
-   | :sg:`get_pressed(num_buttons=5) -> (left_button, middle_button, right_button, x1_button, x2_button)`
+   | :sg:`get_pressed(num_buttons=3, desktop=False) -> (left_button, middle_button, right_button)`
+   | :sg:`get_pressed(num_buttons=5, desktop=False) -> (left_button, middle_button, right_button, x1_button, x2_button)`
 
    Returns a sequence of booleans representing the state of all the mouse
    buttons. A true value means the mouse is currently being pressed at the time
@@ -97,12 +97,21 @@ scroll, such as ``which`` (it will tell you what exact mouse device trigger the
    are added to the returned tuple. Only ``3`` and ``5`` are valid values
    for this parameter.
 
+   If the ``desktop`` argument is ``True`` the mouse state will be correct even
+   if the window has no focus. In addition since it queries the OS it does not depend
+   on the last event pump while being slightly slower.
+
    .. note:: On ``X11`` some X servers use middle button emulation. When you
       click both buttons ``1`` and ``3`` at the same time a ``2`` button event
       can be emitted.
 
+   .. warning:: Due to design constraints it is impossible to retrieve the desktop
+      mouse state on Wayland. The normal mouse state is returned instead.
+
    .. versionchangedold:: 2.0.0 ``num_buttons`` argument added
 
+   .. versionchanged:: 2.5.2 Added the ``desktop`` argument
+
    .. ## pygame.mouse.get_pressed ##
 
 .. function:: get_just_pressed
@@ -158,12 +167,20 @@ scroll, such as ``which`` (it will tell you what exact mouse device trigger the
 .. function:: get_pos
 
    | :sl:`get the mouse cursor position`
-   | :sg:`get_pos() -> (x, y)`
+   | :sg:`get_pos(desktop=False) -> (x, y)`
+
+   By default returns the ``x`` and ``y`` position of the mouse cursor. The position
+   is relative to the top-left corner of the display. The cursor position can be
+   located outside of the display window, but is always constrained to the screen.
+
+   If the ``desktop`` argument is ``True``, the position will be instead relative to the
+   top-left corner of the primary monitor. The position might be negative or exceed
+   the desktop bounds if multiple monitors are present.
+
+   .. warning:: Due to design constraints it is impossible to retrieve the desktop
+      mouse state on Wayland. The relative mouse position is returned instead.
 
-   Returns the ``x`` and ``y`` position of the mouse cursor. The position is
-   relative to the top-left corner of the display. The cursor position can be
-   located outside of the display window, but is always constrained to the
-   screen.
+   .. versionchanged:: 2.5.2 Added the ``desktop`` argument
 
    .. ## pygame.mouse.get_pos ##
 

src_c/doc/mouse_doc.h

@@ -1,9 +1,9 @@
 /* Auto generated file: with make_docs.py .  Docs go in docs/reST/ref/ . */
 #define DOC_MOUSE "pygame module to work with the mouse"
-#define DOC_MOUSE_GETPRESSED "get_pressed(num_buttons=3) -> (left_button, middle_button, right_button)\nget_pressed(num_buttons=5) -> (left_button, middle_button, right_button, x1_button, x2_button)\nget the state of the mouse buttons"
+#define DOC_MOUSE_GETPRESSED "get_pressed(num_buttons=3, desktop=False) -> (left_button, middle_button, right_button)\nget_pressed(num_buttons=5, desktop=False) -> (left_button, middle_button, right_button, x1_button, x2_button)\nget the state of the mouse buttons"
 #define DOC_MOUSE_GETJUSTPRESSED "get_just_pressed() -> (left_button, middle_button, right_button, x1_button, x2_button)\nget the most recently pressed buttons"
 #define DOC_MOUSE_GETJUSTRELEASED "get_just_released() -> (left_button, middle_button, right_button, x1_button, x2_button)\nget the most recently released buttons"
-#define DOC_MOUSE_GETPOS "get_pos() -> (x, y)\nget the mouse cursor position"
+#define DOC_MOUSE_GETPOS "get_pos(desktop=False) -> (x, y)\nget the mouse cursor position"
 #define DOC_MOUSE_GETREL "get_rel() -> (x, y)\nget the amount of mouse movement"
 #define DOC_MOUSE_SETPOS "set_pos([x, y], /) -> None\nset the mouse cursor position"
 #define DOC_MOUSE_SETVISIBLE "set_visible(bool, /) -> bool\nhide or show the mouse cursor"

src_c/mouse.c

@@ -63,37 +63,48 @@ mouse_set_pos(PyObject *self, PyObject *args)
 }
 
 static PyObject *
-mouse_get_pos(PyObject *self, PyObject *_null)
+mouse_get_pos(PyObject *self, PyObject *args, PyObject *kwargs)
 {
     int x, y;
+    int desktop = 0;
 
-    VIDEO_INIT_CHECK();
-    SDL_GetMouseState(&x, &y);
+    static char *kwids[] = {"desktop", NULL};
 
-    {
-        SDL_Window *sdlWindow = pg_GetDefaultWindow();
-        SDL_Renderer *sdlRenderer = SDL_GetRenderer(sdlWindow);
-        if (sdlRenderer != NULL) {
-            SDL_Rect vprect;
-            float scalex, scaley;
-
-            SDL_RenderGetScale(sdlRenderer, &scalex, &scaley);
-            SDL_RenderGetViewport(sdlRenderer, &vprect);
-
-            x = (int)(x / scalex);
-            y = (int)(y / scaley);
-
-            x -= vprect.x;
-            y -= vprect.y;
+    if (!PyArg_ParseTupleAndKeywords(args, kwargs, "|p", kwids, &desktop))
+        return NULL;
+    VIDEO_INIT_CHECK();
 
-            if (x < 0)
-                x = 0;
-            if (x >= vprect.w)
-                x = vprect.w - 1;
-            if (y < 0)
-                y = 0;
-            if (y >= vprect.h)
-                y = vprect.h - 1;
+    if (desktop == 1) {
+        SDL_GetGlobalMouseState(&x, &y);
+    }
+    else {
+        SDL_GetMouseState(&x, &y);
+
+        {
+            SDL_Window *sdlWindow = pg_GetDefaultWindow();
+            SDL_Renderer *sdlRenderer = SDL_GetRenderer(sdlWindow);
+            if (sdlRenderer != NULL) {
+                SDL_Rect vprect;
+                float scalex, scaley;
+
+                SDL_RenderGetScale(sdlRenderer, &scalex, &scaley);
+                SDL_RenderGetViewport(sdlRenderer, &vprect);
+
+                x = (int)(x / scalex);
+                y = (int)(y / scaley);
+
+                x -= vprect.x;
+                y -= vprect.y;
+
+                if (x < 0)
+                    x = 0;
+                if (x >= vprect.w)
+                    x = vprect.w - 1;
+                if (y < 0)
+                    y = 0;
+                if (y >= vprect.h)
+                    y = vprect.h - 1;
+            }
         }
     }
 
@@ -130,18 +141,22 @@ mouse_get_pressed(PyObject *self, PyObject *args, PyObject *kwargs)
     PyObject *tuple;
     int state;
     int num_buttons = 3;
+    int desktop = 0;
 
-    static char *kwids[] = {"num_buttons", NULL};
+    static char *kwids[] = {"num_buttons", "desktop", NULL};
 
-    if (!PyArg_ParseTupleAndKeywords(args, kwargs, "|i", kwids, &num_buttons))
+    if (!PyArg_ParseTupleAndKeywords(args, kwargs, "|ip", kwids, &num_buttons,
+                                     &desktop))
         return NULL;
     VIDEO_INIT_CHECK();
 
     if (num_buttons != 3 && num_buttons != 5)
         return RAISE(PyExc_ValueError,
                      "Number of buttons needs to be 3 or 5.");
 
-    state = SDL_GetMouseState(NULL, NULL);
+    state = desktop ? SDL_GetGlobalMouseState(NULL, NULL)
+                    : SDL_GetMouseState(NULL, NULL);
+
     if (!(tuple = PyTuple_New(num_buttons)))
         return NULL;
 
@@ -530,7 +545,8 @@ mouse_set_relative_mode(PyObject *self, PyObject *arg)
 
 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},
+    {"get_pos", (PyCFunction)mouse_get_pos, METH_VARARGS | METH_KEYWORDS,
+     DOC_MOUSE_GETPOS},
     {"get_rel", (PyCFunction)mouse_get_rel, METH_NOARGS, DOC_MOUSE_GETREL},
     {"get_pressed", (PyCFunction)mouse_get_pressed,
      METH_VARARGS | METH_KEYWORDS, DOC_MOUSE_GETPRESSED},

test/mouse_test.py

@@ -285,6 +285,17 @@ def test_get_pressed(self):
         for value in buttons_pressed:
             self.assertIsInstance(value, bool)
 
+        desktop_pressed1 = pygame.mouse.get_pressed(desktop=True)
+        desktop_pressed2 = pygame.mouse.get_pressed(5, desktop=True)
+        desktop_pressed3 = pygame.mouse.get_pressed(3, True)
+        self.assertEqual(len(desktop_pressed1), 3)
+        self.assertEqual(len(desktop_pressed2), 5)
+        self.assertEqual(len(desktop_pressed3), 3)
+        for desktop_pressed in [desktop_pressed1, desktop_pressed2, desktop_pressed3]:
+            self.assertIsInstance(desktop_pressed, tuple)
+            for value in desktop_pressed:
+                self.assertIsInstance(value, bool)
+
         with self.assertRaises(ValueError):
             pygame.mouse.get_pressed(4)
 
@@ -315,6 +326,16 @@ def test_get_pos(self):
         for value in pos:
             self.assertIsInstance(value, int)
 
+        desktop_pos1 = pygame.mouse.get_pos(True)
+        desktop_pos2 = pygame.mouse.get_pos(desktop=True)
+        self.assertEqual(desktop_pos1, desktop_pos2)
+
+        for desktop_pos in [desktop_pos1, desktop_pos2]:
+            self.assertIsInstance(desktop_pos, tuple)
+            self.assertEqual(len(desktop_pos), expected_length)
+            for value in desktop_pos:
+                self.assertIsInstance(value, int)
+
     def test_set_pos__invalid_pos(self):
         """Ensures set_pos handles invalid positions correctly."""
         for invalid_pos in ((1,), [1, 2, 3], 1, "1", (1, "1"), []):