Utility Window implementation.

Author: gresm

buildconfig/stubs/pygame/window.pyi

@@ -70,6 +70,8 @@ class Window:
     def position(self, value: Union[int, Point]) -> None: ...
     @property
     def opengl(self) -> bool: ...
+    @property
+    def utility(self) -> bool: ...
     @classmethod
     @deprecated("since 2.4.0. Use either the display module or the Window class with get_surface and flip. Try not to mix display and Window")
     def from_display_module(cls) -> Window: ...

docs/reST/ref/window.rst

@@ -43,6 +43,7 @@
                               (unrelated to INPUT_GRABBED).
    :param bool always_on_top: Create a window that is always presented above
                               others.
+   :param bool utility: Create a window that doesn't appear in the task-bar .
 
    Event behavior if one Window is created: When the close button is pressed,
    the ``QUIT`` event will be sent to the event queue.
@@ -289,6 +290,15 @@
 
       .. versionadded:: 2.5.0
 
+   .. attribute:: utility
+
+      | :sl:`Get if the windos is an utility window`
+      | :sg:`utility -> bool`
+
+      ``True`` if the window doesn't appear in the task bar, ``False`` otherwise
+
+      .. versionadded:: TBD
+
    .. classmethod:: from_display_module
 
       | :sl:`Create a Window object using window data from display module`

src_c/doc/window_doc.h

@@ -17,6 +17,7 @@
 #define DOC_WINDOW_POSITION "position -> (int, int) or WINDOWPOS_CENTERED or WINDOWPOS_UNDEFINED\nGet or set the window position in screen coordinates"
 #define DOC_WINDOW_OPACITY "opacity -> float\nGet or set the window opacity, between 0.0 (fully transparent) and 1.0 (fully opaque)"
 #define DOC_WINDOW_OPENGL "opengl -> bool\nGet if the window supports OpenGL"
+#define DOC_WINDOW_UTILITY "utility -> bool\nGet if the windos is an utility window"
 #define DOC_WINDOW_FROMDISPLAYMODULE "from_display_module() -> Window\nCreate a Window object using window data from display module"
 #define DOC_WINDOW_GETSURFACE "get_surface() -> Surface\nGet the window surface"
 #define DOC_WINDOW_FLIP "flip() -> None\nUpdate the display surface to the window."

src_c/window.c

@@ -779,6 +779,13 @@ window_get_opengl(pgWindowObject *self, void *v)
     return PyBool_FromLong(hasGL);
 }
 
+static PyObject *
+window_get_utility(pgWindowObject *self, void *v)
+{
+    return PyBool_FromLong(SDL_GetWindowFlags(self->_win) &
+                           SDL_WINDOW_UTILITY);
+}
+
 static void
 window_dealloc(pgWindowObject *self, PyObject *_null)
 {
@@ -944,6 +951,14 @@ window_init(pgWindowObject *self, PyObject *args, PyObject *kwargs)
                     if (_value_bool)
                         flags |= SDL_WINDOW_VULKAN;
                 }
+                else if (!strcmp(_key_str, "utility")) {
+                    if (_value_bool) {
+                        flags |= SDL_WINDOW_UTILITY;
+#if !SDL_VERSION_ATLEAST(3, 0, 0)
+                        flags |= SDL_WINDOW_SKIP_TASKBAR;
+#endif
+                    }
+                }
                 else {
                     PyErr_Format(PyExc_TypeError,
                                  "__init__ got an unexpected flag \'%s\'",
@@ -1195,6 +1210,7 @@ static PyGetSetDef _window_getset[] = {
      DOC_WINDOW_OPACITY, NULL},
     {"id", (getter)window_get_window_id, NULL, DOC_WINDOW_ID, NULL},
     {"opengl", (getter)window_get_opengl, NULL, DOC_WINDOW_OPENGL, NULL},
+    {"utility", (getter)window_get_utility, NULL, DOC_WINDOW_UTILITY, NULL},
     {NULL, 0, NULL, NULL, NULL} /* Sentinel */
 };
 

test/window_test.py

@@ -1,3 +1,5 @@
+from math import trunc
+from re import S
 import unittest
 import pygame
 import os
@@ -290,6 +292,11 @@ def test_init_flags(self):
         self.assertTrue(win.resizable)
         win.destroy()
 
+        # test utility
+        win = Window(utility=True)
+        self.assertTrue(win.utility)
+        win.destroy()
+
         # should raise a TypeError if keyword is random
         self.assertRaises(TypeError, lambda: Window(aaa=True))
         self.assertRaises(TypeError, lambda: Window(aaa=False))