Enhance Monitor dict, adding primary monitor and name attributes

CHANGELOG.md

@@ -3,13 +3,16 @@
 See Git commit messages for full history.
 
 ## 10.2.0.dev0 (2026-xx-xx)
+- Add `Monitor` class to replace `dict[str, int]` with `is_primary` and `name` attributes (#153)
+- Add `primary_monitor` property to MSS base class for easy access to the primary monitor (#153)
+- Windows: add primary monitor detection using `GetMonitorInfoW` API (#153)
+- Windows: add monitor device name extraction using `EnumDisplayDevicesW` API (#153)
 - Windows: switch from `GetDIBits` to more memory efficient `CreateDIBSection` for `MSS.grab` implementation (#449)
 - Windows: fix gdi32.GetDIBits() failed after a couple of minutes of recording (#268)
 - Linux: check the server for Xrandr support version (#417)
 - Linux: improve typing and error messages for X libraries (#418)
 - Linux: introduce an XCB-powered backend stack with a factory in ``mss.linux`` while keeping the Xlib code as a fallback (#425)
 - Linux: add the XShmGetImage backend with automatic XGetImage fallback and explicit status reporting (#431)
-- Windows: improve error checking and messages for Win32 API calls (#448)
 - Mac: fix memory leak (#450, #453)
 - improve multithreading: allow multiple threads to use the same MSS object, allow multiple MSS objects to concurrently take screenshots, and document multithreading guarantees (#446, #452)
 - Add full demos for different ways to use MSS (#444, #456, #465)

src/mss/base.py

@@ -167,7 +167,7 @@ def close(self) -> None:
             self._close_impl()
             self._closed = True
 
-    def grab(self, monitor: Monitor | tuple[int, int, int, int], /) -> ScreenShot:
+    def grab(self, monitor: Monitor | dict[str, int] | tuple[int, int, int, int], /) -> ScreenShot:
         """Retrieve screen pixels for a given monitor.
 
         Note: ``monitor`` can be a tuple like the one
@@ -177,14 +177,23 @@ def grab(self, monitor: Monitor | tuple[int, int, int, int], /) -> ScreenShot:
                         See :meth:`monitors <monitors>` for object details.
         :returns: Screenshot of the requested region.
         """
-        # Convert PIL bbox style
+        from mss.models import Monitor as MonitorCls  # noqa: PLC0415
+
+        # Convert PIL bbox style or dict to Monitor
         if isinstance(monitor, tuple):
-            monitor = {
-                "left": monitor[0],
-                "top": monitor[1],
-                "width": monitor[2] - monitor[0],
-                "height": monitor[3] - monitor[1],
-            }
+            monitor = MonitorCls(
+                monitor[0],
+                monitor[1],
+                monitor[2] - monitor[0],
+                monitor[3] - monitor[1],
+            )
+        elif isinstance(monitor, dict):
+            monitor = MonitorCls(
+                monitor["left"],
+                monitor["top"],
+                monitor["width"],
+                monitor["height"],
+            )
 
         if monitor["width"] <= 0 or monitor["height"] <= 0:
             msg = f"Region has zero or negative size: {monitor!r}"
@@ -220,6 +229,26 @@ def monitors(self) -> Monitors:
                 self._monitors_impl()
             return self._monitors
 
+    @property
+    def primary_monitor(self) -> Monitor | None:
+        """Get the primary monitor.
+
+        Returns the monitor marked as primary. If no monitor is marked as primary
+        (or the platform doesn't support primary monitor detection), returns the
+        first monitor (at index 1). Returns None if no monitors are available.
+
+        .. versionadded:: 10.2.0
+        """
+        monitors = self.monitors
+        if len(monitors) <= 1:  # Only the "all monitors" entry or empty
+            return None
+
+        for monitor in monitors[1:]:  # Skip the "all monitors" entry at index 0
+            if monitor.is_primary:
+                return monitor
+        # Fallback to the first monitor if no primary is found
+        return monitors[1]
+
     def save(
         self,
         /,

src/mss/darwin.py

@@ -26,10 +26,11 @@
 
 from mss.base import MSSBase
 from mss.exception import ScreenShotError
+from mss.models import Monitor
 from mss.screenshot import ScreenShot, Size
 
 if TYPE_CHECKING:  # pragma: nocover
-    from mss.models import CFunctions, Monitor
+    from mss.models import CFunctions
 
 __all__ = ("IMAGE_OPTIONS", "MSS")
 
@@ -158,7 +159,7 @@ def _monitors_impl(self) -> None:
         # We need to update the value with every single monitor found
         # using CGRectUnion.  Else we will end with infinite values.
         all_monitors = CGRect()
-        self._monitors.append({})
+        self._monitors.append(Monitor(0, 0, 0, 0))  # Placeholder, updated later
 
         # Each monitor
         display_count = c_uint32(0)
@@ -177,24 +178,24 @@ def _monitors_impl(self) -> None:
                 width, height = height, width
 
             self._monitors.append(
-                {
-                    "left": int_(rect.origin.x),
-                    "top": int_(rect.origin.y),
-                    "width": int_(width),
-                    "height": int_(height),
-                },
+                Monitor(
+                    int_(rect.origin.x),
+                    int_(rect.origin.y),
+                    int_(width),
+                    int_(height),
+                ),
             )
 
             # Update AiO monitor's values
             all_monitors = core.CGRectUnion(all_monitors, rect)
 
         # Set the AiO monitor's values
-        self._monitors[0] = {
-            "left": int_(all_monitors.origin.x),
-            "top": int_(all_monitors.origin.y),
-            "width": int_(all_monitors.size.width),
-            "height": int_(all_monitors.size.height),
-        }
+        self._monitors[0] = Monitor(
+            int_(all_monitors.origin.x),
+            int_(all_monitors.origin.y),
+            int_(all_monitors.size.width),
+            int_(all_monitors.size.height),
+        )
 
     def _grab_impl(self, monitor: Monitor, /) -> ScreenShot:
         """Retrieve all pixels from a monitor. Pixels have to be RGB."""

src/mss/linux/base.py

@@ -4,12 +4,12 @@
 
 from mss.base import MSSBase
 from mss.exception import ScreenShotError
+from mss.models import Monitor
 
 from . import xcb
 from .xcb import LIB
 
 if TYPE_CHECKING:
-    from mss.models import Monitor
     from mss.screenshot import ScreenShot
 
 SUPPORTED_DEPTHS = {24, 32}
@@ -144,12 +144,12 @@ def _monitors_impl(self) -> None:
         # monitors.
         root_geom = xcb.get_geometry(self.conn, self.root)
         self._monitors.append(
-            {
-                "left": root_geom.x,
-                "top": root_geom.y,
-                "width": root_geom.width,
-                "height": root_geom.height,
-            }
+            Monitor(
+                root_geom.x,
+                root_geom.y,
+                root_geom.width,
+                root_geom.height,
+            )
         )
 
         # After that, we have one for each monitor on that X11 screen.  For decades, that's been handled by
@@ -186,9 +186,7 @@ def _monitors_impl(self) -> None:
             crtc_info = xcb.randr_get_crtc_info(self.conn, crtc, screen_resources.config_timestamp)
             if crtc_info.num_outputs == 0:
                 continue
-            self._monitors.append(
-                {"left": crtc_info.x, "top": crtc_info.y, "width": crtc_info.width, "height": crtc_info.height}
-            )
+            self._monitors.append(Monitor(crtc_info.x, crtc_info.y, crtc_info.width, crtc_info.height))
 
         # Extra credit would be to enumerate the virtual desktops; see
         # https://specifications.freedesktop.org/wm/latest/ar01s03.html.  But I don't know how widely-used that
@@ -232,12 +230,12 @@ def _cursor_impl(self) -> ScreenShot:
             raise ScreenShotError(msg)
 
         cursor_img = xcb.xfixes_get_cursor_image(self.conn)
-        region = {
-            "left": cursor_img.x - cursor_img.xhot,
-            "top": cursor_img.y - cursor_img.yhot,
-            "width": cursor_img.width,
-            "height": cursor_img.height,
-        }
+        region = Monitor(
+            cursor_img.x - cursor_img.xhot,
+            cursor_img.y - cursor_img.yhot,
+            cursor_img.width,
+            cursor_img.height,
+        )
 
         data_arr = xcb.xfixes_get_cursor_image_cursor_image(cursor_img)
         data = bytearray(data_arr)

src/mss/linux/xlib.py

@@ -37,9 +37,10 @@
 
 from mss.base import MSSBase
 from mss.exception import ScreenShotError
+from mss.models import Monitor
 
 if TYPE_CHECKING:  # pragma: nocover
-    from mss.models import CFunctions, Monitor
+    from mss.models import CFunctions
     from mss.screenshot import ScreenShot
 
 __all__ = ("MSS",)
@@ -542,7 +543,7 @@ def _monitors_impl(self) -> None:
             gwa = XWindowAttributes()
             self.xlib.XGetWindowAttributes(display, self._handles.root, byref(gwa))
             self._monitors.append(
-                {"left": int_(gwa.x), "top": int_(gwa.y), "width": int_(gwa.width), "height": int_(gwa.height)},
+                Monitor(int_(gwa.x), int_(gwa.y), int_(gwa.width), int_(gwa.height)),
             )
 
             # Each monitor
@@ -565,12 +566,12 @@ def _monitors_impl(self) -> None:
                     continue
 
                 self._monitors.append(
-                    {
-                        "left": int_(crtc.x),
-                        "top": int_(crtc.y),
-                        "width": int_(crtc.width),
-                        "height": int_(crtc.height),
-                    },
+                    Monitor(
+                        int_(crtc.x),
+                        int_(crtc.y),
+                        int_(crtc.width),
+                        int_(crtc.height),
+                    ),
                 )
                 xrandr.XRRFreeCrtcInfo(crtc)
             xrandr.XRRFreeScreenResources(mon)
@@ -618,17 +619,17 @@ def _cursor_impl(self) -> ScreenShot:
             raise ScreenShotError(msg)
 
         cursor_img: XFixesCursorImage = ximage.contents
-        region = {
-            "left": cursor_img.x - cursor_img.xhot,
-            "top": cursor_img.y - cursor_img.yhot,
-            "width": cursor_img.width,
-            "height": cursor_img.height,
-        }
-
-        raw_data = cast(cursor_img.pixels, POINTER(c_ulong * region["height"] * region["width"]))
+        region = Monitor(
+            cursor_img.x - cursor_img.xhot,
+            cursor_img.y - cursor_img.yhot,
+            cursor_img.width,
+            cursor_img.height,
+        )
+
+        raw_data = cast(cursor_img.pixels, POINTER(c_ulong * region.height * region.width))
         raw = bytearray(raw_data.contents)
 
-        data = bytearray(region["height"] * region["width"] * 4)
+        data = bytearray(region.height * region.width * 4)
         data[3::4] = raw[3::8]
         data[2::4] = raw[2::8]
         data[1::4] = raw[1::8]

src/mss/models.py

@@ -1,14 +1,73 @@
 # This is part of the MSS Python's module.
 # Source: https://github.com/BoboTiG/python-mss.
+from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any, Callable, NamedTuple
 
-Monitor = dict[str, int]
-Monitors = list[Monitor]
-
 Pixel = tuple[int, int, int]
 Pixels = list[tuple[Pixel, ...]]
 
+
+class Monitor:
+    """Represents a display monitor with its position and dimensions.
+
+    :param left: The x-coordinate of the upper-left corner.
+    :param top: The y-coordinate of the upper-left corner.
+    :param width: The width of the monitor.
+    :param height: The height of the monitor.
+    :param is_primary: Whether this is the primary monitor.
+    :param name: The device name of the monitor (platform-specific).
+    """
+
+    __slots__ = ("height", "is_primary", "left", "name", "top", "width")
+
+    def __init__(  # noqa: PLR0913
+        self,
+        left: int,
+        top: int,
+        width: int,
+        height: int,
+        *,
+        is_primary: bool = False,
+        name: str = "",
+    ) -> None:
+        self.left = left
+        self.top = top
+        self.width = width
+        self.height = height
+        self.is_primary = is_primary
+        self.name = name
+
+    def __repr__(self) -> str:
+        return (
+            f"Monitor(left={self.left}, top={self.top}, width={self.width}, "
+            f"height={self.height}, is_primary={self.is_primary}, name={self.name!r})"
+        )
+
+    def __getitem__(self, key: str) -> int | bool:
+        """Provide dict-like access for backward compatibility."""
+        try:
+            return getattr(self, key)
+        except AttributeError as exc:
+            raise KeyError(key) from exc
+
+    def __setitem__(self, key: str, value: int | bool) -> None:
+        """Provide dict-like setitem for backward compatibility."""
+        if not hasattr(self, key):
+            raise KeyError(key)
+        setattr(self, key, value)
+
+    def keys(self) -> list[str]:
+        """Provide dict-like keys() for backward compatibility."""
+        return list(self.__slots__)
+
+    def __contains__(self, key: str) -> bool:
+        """Provide dict-like 'in' operator for backward compatibility."""
+        return hasattr(self, key) and key in self.__slots__
+
+
+Monitors = list[Monitor]
+
 if TYPE_CHECKING:
     CFunctions = dict[str, tuple[str, list[Any], Any]]
     CFunctionsErrChecked = dict[str, tuple[str, list[Any], Any, Callable | None]]

src/mss/screenshot.py

@@ -68,7 +68,9 @@ def __array_interface__(self) -> dict[str, Any]:
     @classmethod
     def from_size(cls: type[ScreenShot], data: bytearray, width: int, height: int, /) -> ScreenShot:
         """Instantiate a new class given only screenshot's data and size."""
-        monitor = {"left": 0, "top": 0, "width": width, "height": height}
+        from mss.models import Monitor  # noqa: PLC0415
+
+        monitor = Monitor(0, 0, width, height)
         return cls(data, monitor)
 
     @property