CLI: add --with-cursor argument

Author: BoboTiG

CHANGELOG

@@ -10,6 +10,7 @@ History:
       - Linux: added mouse support (related to #55)
       - Linux: refactored how internal handles are stored to fix issues with multiple X servers (fixes #210)
       - Linux: removed side effects when leaving the context manager, resources are all freed (fixes #210)
+      - CLI: added --with-cursor argument
       - tests: added PyPy 3.9, removed tox, and improved GNU/Linux coverage
 
 7.0.1   2022/10/27

docs/source/usage.rst

@@ -72,6 +72,25 @@ You can use ``mss`` via the CLI::
 
 Or via direct call from Python::
 
-    python -m mss --help
+    $ python -m mss --help
+    usage: __main__.py [-h] [-c COORDINATES] [-l {0,1,2,3,4,5,6,7,8,9}]
+                    [-m MONITOR] [-o OUTPUT] [-q] [-v] [--with-cursor]
+
+    options:
+    -h, --help            show this help message and exit
+    -c COORDINATES, --coordinates COORDINATES
+                          the part of the screen to capture: top, left, width, height
+    -l {0,1,2,3,4,5,6,7,8,9}, --level {0,1,2,3,4,5,6,7,8,9}
+                          the PNG compression level
+    -m MONITOR, --monitor MONITOR
+                          the monitor to screen shot
+    -o OUTPUT, --output OUTPUT
+                          the output file name
+    --with-cursor         include the cursor
+    -q, --quiet           do not print created files
+    -v, --version         show program's version number and exit
 
 .. versionadded:: 3.1.1
+
+.. versionadded:: 8.0.0
+    ``--with-cursor`` to include the cursor in screenshots.

mss/__main__.py

@@ -33,6 +33,7 @@ def main(args: List[str], /) -> int:
     )
     cli_args.add_argument("-m", "--monitor", default=0, type=int, help="the monitor to screen shot")
     cli_args.add_argument("-o", "--output", default="monitor-{mon}.png", help="the output file name")
+    cli_args.add_argument("--with-cursor", default=False, action="store_true", help="include the cursor")
     cli_args.add_argument(
         "-q",
         "--quiet",
@@ -61,7 +62,7 @@ def main(args: List[str], /) -> int:
             kwargs["output"] = "sct-{top}x{left}_{width}x{height}.png"
 
     try:
-        with mss() as sct:
+        with mss(with_cursor=options.with_cursor) as sct:
             if options.coordinates:
                 output = kwargs["output"].format(**kwargs["mon"])
                 sct_img = sct.grab(kwargs["mon"])

mss/linux.py

@@ -454,20 +454,20 @@ def _cursor_impl(self) -> ScreenShot:
             raise ScreenShotError("Cannot read XFixesGetCursorImage()")
 
         cursor_img: XFixesCursorImage = ximage.contents
-        monitor = {
+        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 * monitor["height"] * monitor["width"]))
+        raw_data = cast(cursor_img.pixels, POINTER(c_ulong * region["height"] * region["width"]))
         raw = bytearray(raw_data.contents)
 
-        data = bytearray(monitor["height"] * monitor["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]
         data[::4] = raw[::8]
 
-        return self.cls_image(data, monitor)
+        return self.cls_image(data, region)