Merge pull request #2307 from yunline/window-always-on-top

Add `always_on_top` attribute for video.Window

Author: Starbuck5

buildconfig/stubs/pygame/_sdl2/video.pyi

@@ -66,6 +66,7 @@ class Window:
     def minimize(self) -> None: ...
     resizable: bool
     borderless: bool
+    always_on_top: bool
     def set_icon(self, surface: Surface) -> None: ...
     id: int
     size: Iterable[int]

buildconfig/stubs/pygame/_window.pyi

@@ -28,6 +28,7 @@ class Window:
     title: str
     resizable: bool
     borderless: bool
+    always_on_top: bool
     relative_mouse: bool
     id: int
     size: Iterable[int]

docs/reST/ref/sdl2_video.rst

@@ -146,6 +146,18 @@
       Gets or sets whether the window is borderless.
 
       .. note:: You can't change the border state of a fullscreen window.
+   
+   .. attribute:: always_on_top
+
+      | :sl:`Get or set whether the window is always on top`
+      | :sg:`always_on_top -> bool`
+
+      Get or set whether the window is always on top.
+
+      Setting the always-on-top mode requires SDL 2.0.16+.
+
+      .. versionadded:: 2.3.1
+
    .. attribute:: id
 
       | :sl:`Get the unique window ID (**read-only**)`

src_c/doc/sdl2_video_doc.h

@@ -10,6 +10,7 @@
 #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"
+#define DOC_SDL2_VIDEO_WINDOW_ALWAYSONTOP "always_on_top -> bool\nGet or set whether the window is always on top"
 #define DOC_SDL2_VIDEO_WINDOW_ID "id -> int\nGet the unique window ID (**read-only**)"
 #define DOC_SDL2_VIDEO_WINDOW_SIZE "size -> (int, int)\nGet or set the window size in pixels"
 #define DOC_SDL2_VIDEO_WINDOW_POSITION "position -> (int, int) or WINDOWPOS_CENTERED or WINDOWPOS_UNDEFINED\nGet or set the window position in screen coordinates"

src_c/window.c

@@ -308,6 +308,32 @@ window_get_borderless(pgWindowObject *self, void *v)
                            SDL_WINDOW_BORDERLESS);
 }
 
+static int
+window_set_always_on_top(pgWindowObject *self, PyObject *arg, void *v)
+{
+#if SDL_VERSION_ATLEAST(2, 0, 16)
+    int enable = PyObject_IsTrue(arg);
+    if (enable == -1)
+        return -1;
+
+    SDL_SetWindowAlwaysOnTop(self->_win, enable);
+#else
+    if (PyErr_WarnEx(PyExc_Warning,
+                     "Setting 'always_on_top' requires SDL 2.0.16+",
+                     1) == -1) {
+        return -1;
+    }
+#endif  // SDL_VERSION_ATLEAST(2, 0, 16)
+    return 0;
+}
+
+static PyObject *
+window_get_always_on_top(pgWindowObject *self, void *v)
+{
+    return PyBool_FromLong(SDL_GetWindowFlags(self->_win) &
+                           SDL_WINDOW_ALWAYS_ON_TOP);
+}
+
 static PyObject *
 window_get_window_id(pgWindowObject *self, PyObject *_null)
 {
@@ -711,6 +737,9 @@ static PyGetSetDef _window_getset[] = {
      DOC_SDL2_VIDEO_WINDOW_RESIZABLE, NULL},
     {"borderless", (getter)window_get_borderless,
      (setter)window_set_borderless, DOC_SDL2_VIDEO_WINDOW_BORDERLESS, NULL},
+    {"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},