pyloid 0.13.1__py3-none-any.whl → 0.14.1__py3-none-any.whl

pyloid/monitor.py

@@ -1,8 +1,18 @@
 from PySide6.QtGui import QScreen
-from typing import Optional, Callable
+from typing import Optional, Callable, Any
 
 class Monitor():
     def __init__(self, index: int, screen: QScreen):
+        """
+        Constructor for the Monitor class.
+
+        Parameters
+        ----------
+        index : int
+            Index of the monitor.
+        screen : QScreen
+            QScreen object of the monitor.
+        """
         super().__init__()
         self.index = index
         self.screen = screen
@@ -10,9 +20,34 @@ class Monitor():
     def capture(self, save_path: str, x: Optional[int] = None, y: Optional[int] = None, width: Optional[int] = None, height: Optional[int] = None):
         """
         Captures the entire desktop screen.
-        
-        :param save_path: Path to save the captured image. If not specified, it will be saved in the current directory.
-        :return: Path of the saved image
+
+        Parameters
+        ----------
+        save_path : str
+            Path to save the captured image. If not specified, it will be saved in the current directory.
+        x : int, optional
+            x-coordinate of the area to capture. Default is None.
+        y : int, optional
+            y-coordinate of the area to capture. Default is None.
+        width : int, optional
+            Width of the area to capture. Default is None.
+        height : int, optional
+            Height of the area to capture. Default is None.
+
+        Returns
+        -------
+        str or None
+            Returns the path of the saved image. Returns None if an error occurs.
+
+        Examples
+        --------
+        ```python
+        app = Pyloid("Pyloid-App")
+
+        monitor = app.get_primary_monitor()
+        save_path = monitor.capture("screenshot.png")
+        print(f"Screenshot saved at: {save_path}")
+        ```
         """
         try:    
             screenshot = self.screen.grabWindow(0, x, y, width, height)
@@ -23,11 +58,95 @@ class Monitor():
             print(f"Error occurred while capturing the desktop: {e}")
             return None
 
-    def info(self):
+    def info(self) -> dict[str, Any]:
         """
-        Returns monitor information.
-        
-        :return: Dictionary containing monitor information
+        Returns information about the monitor.
+
+        Returns
+        -------
+        dict[str, Any]
+            A dictionary containing monitor information.
+
+        Examples
+        --------
+        ```python
+        app = Pyloid("Pyloid-App")
+
+        monitor = app.get_primary_monitor()
+        info = monitor.info()
+        print("Monitor Info:", info)
+        ```
+
+        Output Example
+        --------------
+        ```
+        {
+            "index": 0,
+            "name": "Primary Monitor",
+            "manufacturer": "Dell",
+            "model": "U2718Q",
+            "serial_number": "SN123456789",
+            "x": 0,
+            "y": 0,
+            "width": 2560,
+            "height": 1440,
+            "is_primary": True,
+            "geometry": {
+                "x": 0,
+                "y": 0,
+                "width": 2560,
+                "height": 1440,
+            },    
+            "size": {
+                "width": 2560,
+                "height": 1440,
+            },
+            "available_geometry": {
+                "x": 0,
+                "y": 0,
+                "width": 2560,
+                "height": 1400,
+            },
+            "available_size": {
+                "width": 2560,
+                "height": 1400,
+            },
+            "virtual_geometry":{
+                "x": 0,
+                "y": 0,
+                "width": 5120,
+                "height": 1440,
+            },
+            "virtual_size": {
+                "width": 5120,
+                "height": 1440,
+            },
+            "available_virtual_geometry": {
+                "x": 0,
+                "y": 0,
+                "width": 5120,
+                "height": 1400,
+            },
+            "available_virtual_size": {
+                "width": 5120,
+                "height": 1400,
+            },
+            "physical_size": {
+                "width": 600,
+                "height": 340,
+            },
+            "depth": 24,
+            "device_pixel_ratio": 1.0,
+            "logical_dots_per_inch": 96.0,
+            "logical_dots_per_inch_x": 96.0,
+            "logical_dots_per_inch_y": 96.0,
+            "orientation": "Landscape",
+            "physical_dots_per_inch": 109.0,
+            "physical_dots_per_inch_x": 109.0,
+            "physical_dots_per_inch_y": 109.0,
+            "refresh_rate": 60.0, 
+        }
+        ```
         """
         monitor = self.screen
 
@@ -102,17 +221,43 @@ class Monitor():
     
     def is_primary(self) -> bool:
         """
-        Checks if the given monitor is the primary monitor.
-        
-        :return: True if the primary monitor, False otherwise
+        Checks if the monitor is the primary monitor.
+
+        Returns
+        -------
+        bool
+            Returns True if the monitor is the primary monitor, otherwise False.
+
+        Examples
+        --------
+        ```python
+        app = Pyloid("Pyloid-App")
+
+        monitor = app.get_all_monitors()[1]
+        is_primary = monitor.is_primary()
+        print(f"Is primary monitor: {is_primary}") # False
+        ```
         """
         return self.index == 0
     
-    def size(self) -> dict:
+    def size(self) -> dict[str, int]:
         """
         Returns the size of the monitor.
-        
-        :return: Size of the monitor
+
+        Returns
+        -------
+        dict[str, int]
+            A dictionary containing the width and height of the monitor.
+
+        Examples
+        --------
+        ```python
+        app = Pyloid("Pyloid-App")
+
+        monitor = app.get_primary_monitor()
+        size = monitor.size()
+        print("Monitor Size:", size)
+        ```
         """
         monitor = self.screen
         return {
@@ -120,11 +265,24 @@ class Monitor():
                     "height": monitor.size().height(),
                 },
 
-    def geometry(self) -> dict:
+    def geometry(self) -> dict[str, int]:
         """
         Returns the geometry of the monitor.
-        
-        :return: Geometry of the monitor
+
+        Returns
+        -------
+        dict[str, int]
+            A dictionary containing the x and y coordinates, width, and height of the monitor.
+
+        Examples
+        --------
+        ```python
+        app = Pyloid("Pyloid-App")
+
+        monitor = app.get_primary_monitor()
+        geometry = monitor.geometry()
+        print("Monitor Geometry:", geometry)
+        ```
         """
         monitor = self.screen
         return {
@@ -134,11 +292,26 @@ class Monitor():
             "height": monitor.geometry().height(),
         }
     
-    def available_geometry(self) -> dict:
+    def available_geometry(self) -> dict[str, int]:
         """
         Returns the available geometry of the monitor.
-        
-        :return: Available geometry of the monitor
+
+        The available geometry refers to the portion of the monitor's geometry that is not occupied by system UI elements such as taskbars or docks.
+
+        Returns
+        -------
+        dict[str, int]
+            A dictionary containing the x and y coordinates, width, and height of the available geometry.
+
+        Examples
+        --------
+        ```python
+        app = Pyloid("Pyloid-App")
+
+        monitor = app.get_primary_monitor()
+        available_geometry = monitor.available_geometry()
+        print("Available Geometry:", available_geometry)
+        ```
         """
         monitor = self.screen
         return {
@@ -148,11 +321,26 @@ class Monitor():
             "height": monitor.availableGeometry().height(),
         }
     
-    def available_size(self) -> dict:
+    def available_size(self) -> dict[str, int]:
         """
         Returns the available size of the monitor.
-        
-        :return: Available size of the monitor
+
+        The available size refers to the portion of the monitor's size that is not occupied by system UI elements such as taskbars or docks.
+
+        Returns
+        -------
+        dict[str, int]
+            A dictionary containing the width and height of the available size.
+
+        Examples
+        --------
+        ```python
+        app = Pyloid("Pyloid-App")
+
+        monitor = app.get_primary_monitor()
+        available_size = monitor.available_size()
+        print("Available Size:", available_size)
+        ```
         """
         monitor = self.screen
         return {
@@ -160,11 +348,26 @@ class Monitor():
             "height": monitor.availableSize().height(),
         }
     
-    def virtual_geometry(self) -> dict:
+    def virtual_geometry(self) -> dict[str, int]:
         """
         Returns the virtual geometry of the monitor.
-        
-        :return: Virtual geometry of the monitor
+
+        The virtual geometry refers to the combined geometry of all monitors in a multi-monitor setup.
+
+        Returns
+        -------
+        dict[str, int]
+            A dictionary containing the x and y coordinates, width, and height of the virtual geometry.
+
+        Examples
+        --------
+        ```python
+        app = Pyloid("Pyloid-App")
+
+        monitor = app.get_primary_monitor()
+        virtual_geometry = monitor.virtual_geometry()
+        print("Virtual Geometry:", virtual_geometry)
+        ```
         """
         monitor = self.screen
         return {
@@ -174,11 +377,26 @@ class Monitor():
             "height": monitor.virtualGeometry().height(),
         }
     
-    def virtual_size(self) -> dict:
+    def virtual_size(self) -> dict[str, int]:
         """
         Returns the virtual size of the monitor.
-        
-        :return: Virtual size of the monitor
+
+        The virtual size refers to the combined size of all monitors in a multi-monitor setup.
+
+        Returns
+        -------
+        dict[str, int]
+            A dictionary containing the width and height of the virtual size.
+
+        Examples
+        --------
+        ```python
+        app = Pyloid("Pyloid-App")
+
+        monitor = app.get_primary_monitor()
+        virtual_size = monitor.virtual_size()
+        print("Virtual Size:", virtual_size)
+        ```
         """
         monitor = self.screen
         return {
@@ -186,11 +404,26 @@ class Monitor():
             "height": monitor.virtualSize().height(),
         }
     
-    def available_virtual_geometry(self) -> dict:
+    def available_virtual_geometry(self) -> dict[str, int]:
         """
         Returns the available virtual geometry of the monitor.
-        
-        :return: Available virtual geometry of the monitor
+
+        The available virtual geometry refers to the portion of the virtual geometry that is not occupied by system UI elements such as taskbars or docks.
+
+        Returns
+        -------
+        dict[str, int]
+            A dictionary containing the x and y coordinates, width, and height of the available virtual geometry.
+
+        Examples
+        --------
+        ```python
+        app = Pyloid("Pyloid-App")
+
+        monitor = app.get_primary_monitor()
+        available_virtual_geometry = monitor.available_virtual_geometry()
+        print("Available Virtual Geometry:", available_virtual_geometry)
+        ```
         """
         monitor = self.screen
         return {
@@ -200,11 +433,26 @@ class Monitor():
             "height": monitor.availableVirtualGeometry().height(),
         }
     
-    def available_virtual_size(self) -> dict:
+    def available_virtual_size(self) -> dict[str, int]:
         """
         Returns the available virtual size of the monitor.
-        
-        :return: Available virtual size of the monitor
+
+        The available virtual size refers to the portion of the virtual size that is not occupied by system UI elements such as taskbars or docks.
+
+        Returns
+        -------
+        dict[str, int]
+            A dictionary containing the width and height of the available virtual size.
+
+        Examples
+        --------
+        ```python
+        app = Pyloid("Pyloid-App")
+
+        monitor = app.get_primary_monitor()
+        available_virtual_size = monitor.available_virtual_size()
+        print("Available Virtual Size:", available_virtual_size)
+        ```
         """
         monitor = self.screen
         return {
@@ -212,11 +460,26 @@ class Monitor():
             "height": monitor.availableVirtualSize().height(),
         }
     
-    def physical_size(self) -> dict:
+    def physical_size(self) -> dict[str, float]:
         """
         Returns the physical size of the monitor.
-        
-        :return: Physical size of the monitor
+
+        The physical size refers to the actual physical dimensions of the monitor.
+
+        Returns
+        -------
+        dict[str, float]
+            A dictionary containing the width and height of the physical size.
+
+        Examples
+        --------
+        ```python
+        app = Pyloid("Pyloid-App")
+
+        monitor = app.get_primary_monitor()
+        physical_size = monitor.physical_size()
+        print("Physical Size:", physical_size)
+        ```
         """
         monitor = self.screen
         return {
@@ -227,8 +490,23 @@ class Monitor():
     def depth(self) -> int:
         """
         Returns the depth of the monitor.
-        
-        :return: Depth of the monitor
+
+        The depth refers to the color depth of the monitor, which is the number of bits used to represent the color of a single pixel.
+
+        Returns
+        -------
+        int
+            The color depth of the monitor.
+
+        Examples
+        --------
+        ```python
+        app = Pyloid("Pyloid-App")
+
+        monitor = app.get_primary_monitor()
+        depth = monitor.depth()
+        print("Color Depth:", depth)
+        ```
         """
         monitor = self.screen
         return monitor.depth()      
@@ -236,35 +514,95 @@ class Monitor():
     def device_pixel_ratio(self) -> float:
         """
         Returns the device pixel ratio of the monitor.
-        
-        :return: Device pixel ratio of the monitor
+
+        The device pixel ratio is the ratio between physical pixels and device-independent pixels (DIPs).
+
+        Returns
+        -------
+        float
+            The device pixel ratio of the monitor.
+
+        Examples
+        --------
+        ```python
+        app = Pyloid("Pyloid-App")
+
+        monitor = app.get_primary_monitor()
+        device_pixel_ratio = monitor.device_pixel_ratio()
+        print("Device Pixel Ratio:", device_pixel_ratio)
+        ```
         """
         monitor = self.screen
         return monitor.devicePixelRatio()
     
     def logical_dots_per_inch(self) -> float:
         """
-        Returns the logical dots per inch of the monitor.
-        
-        :return: Logical dots per inch of the monitor
+        Returns the logical dots per inch (DPI) of the monitor.
+
+        The logical DPI is the number of device-independent pixels (DIPs) per inch.
+
+        Returns
+        -------
+        float
+            The logical DPI of the monitor.
+
+        Examples
+        --------
+        ```python
+        app = Pyloid("Pyloid-App")
+
+        monitor = app.get_primary_monitor()
+        logical_dpi = monitor.logical_dots_per_inch()
+        print("Logical DPI:", logical_dpi)
+        ```
         """
         monitor = self.screen   
         return monitor.logicalDotsPerInch()
     
     def logical_dots_per_inch_x(self) -> float:
         """
-        Returns the logical dots per inch X of the monitor.
-        
-        :return: Logical dots per inch X of the monitor
-        """ 
+        Returns the logical dots per inch (DPI) along the X axis of the monitor.
+
+        The logical DPI along the X axis is the number of device-independent pixels (DIPs) per inch along the horizontal axis.
+
+        Returns
+        -------
+        float
+            The logical DPI along the X axis of the monitor.
+
+        Examples
+        --------
+        ```python
+        app = Pyloid("Pyloid-App")
+
+        monitor = app.get_primary_monitor()
+        logical_dpi_x = monitor.logical_dots_per_inch_x()
+        print("Logical DPI X:", logical_dpi_x)
+        ```
+        """
         monitor = self.screen
         return monitor.logicalDotsPerInchX()
     
     def logical_dots_per_inch_y(self) -> float:
         """
-        Returns the logical dots per inch Y of the monitor.
-        
-        :return: Logical dots per inch Y of the monitor
+        Returns the logical dots per inch (DPI) along the Y axis of the monitor.
+
+        The logical DPI along the Y axis is the number of device-independent pixels (DIPs) per inch along the vertical axis.
+
+        Returns
+        -------
+        float
+            The logical DPI along the Y axis of the monitor.
+
+        Examples
+        --------
+        ```python
+        app = Pyloid("Pyloid-App")
+
+        monitor = app.get_primary_monitor()
+        logical_dpi_y = monitor.logical_dots_per_inch_y()
+        print("Logical DPI Y:", logical_dpi_y)
+        ```
         """
         monitor = self.screen
         return monitor.logicalDotsPerInchY()
@@ -272,35 +610,95 @@ class Monitor():
     def orientation(self) -> str:
         """
         Returns the orientation of the monitor.
-        
-        :return: Orientation of the monitor
-        """ 
+
+        The orientation refers to the current orientation of the monitor, such as landscape or portrait.
+
+        Returns
+        -------
+        str
+            The orientation of the monitor.
+
+        Examples
+        --------
+        ```python
+        app = Pyloid("Pyloid-App")
+
+        monitor = app.get_primary_monitor()
+        orientation = monitor.orientation()
+        print("Orientation:", orientation)
+        ```
+        """
         monitor = self.screen
         return monitor.orientation().name
     
     def physical_dots_per_inch(self) -> float:
         """
-        Returns the physical dots per inch of the monitor.
-        
-        :return: Physical dots per inch of the monitor
+        Returns the physical dots per inch (DPI) of the monitor.
+
+        The physical DPI is the number of physical pixels per inch.
+
+        Returns
+        -------
+        float
+            The physical DPI of the monitor.
+
+        Examples
+        --------
+        ```python
+        app = Pyloid("Pyloid-App")
+
+        monitor = app.get_primary_monitor()
+        physical_dpi = monitor.physical_dots_per_inch()
+        print("Physical DPI:", physical_dpi)
+        ```
         """
         monitor = self.screen
         return monitor.physicalDotsPerInch()
     
     def physical_dots_per_inch_x(self) -> float:
         """
-        Returns the physical dots per inch X of the monitor.
-        
-        :return: Physical dots per inch X of the monitor
+        Returns the physical dots per inch (DPI) along the X axis of the monitor.
+
+        The physical DPI along the X axis is the number of physical pixels per inch along the horizontal axis.
+
+        Returns
+        -------
+        float
+            The physical DPI along the X axis of the monitor.
+
+        Examples
+        --------
+        ```python
+        app = Pyloid("Pyloid-App")
+
+        monitor = app.get_primary_monitor()
+        physical_dpi_x = monitor.physical_dots_per_inch_x()
+        print("Physical DPI X:", physical_dpi_x)
+        ```
         """
         monitor = self.screen
         return monitor.physicalDotsPerInchX()
     
     def physical_dots_per_inch_y(self) -> float:
         """
-        Returns the physical dots per inch Y of the monitor.
-        
-        :return: Physical dots per inch Y of the monitor
+        Returns the physical dots per inch (DPI) along the Y axis of the monitor.
+
+        The physical DPI along the Y axis is the number of physical pixels per inch along the vertical axis.
+
+        Returns
+        -------
+        float
+            The physical DPI along the Y axis of the monitor.
+
+        Examples
+        --------
+        ```python
+        app = Pyloid("Pyloid-App")
+
+        monitor = app.get_primary_monitor()
+        physical_dpi_y = monitor.physical_dots_per_inch_y()
+        print("Physical DPI Y:", physical_dpi_y)
+        ```
         """
         monitor = self.screen
         return monitor.physicalDotsPerInchY()
@@ -308,8 +706,23 @@ class Monitor():
     def refresh_rate(self) -> float:
         """
         Returns the refresh rate of the monitor.
-        
-        :return: Refresh rate of the monitor
+
+        The refresh rate is the number of times the monitor updates with new information per second, measured in Hertz (Hz).
+
+        Returns
+        -------
+        float
+            The refresh rate of the monitor.
+
+        Examples
+        --------
+        ```python
+        app = Pyloid("Pyloid-App")
+
+        monitor = app.get_primary_monitor()
+        refresh_rate = monitor.refresh_rate()
+        print("Refresh Rate:", refresh_rate)
+        ```
         """
         monitor = self.screen
         return monitor.refreshRate()
@@ -317,8 +730,23 @@ class Monitor():
     def manufacturer(self) -> str:
         """
         Returns the manufacturer of the monitor.
-        
-        :return: Manufacturer of the monitor
+
+        The manufacturer refers to the company that produced the monitor.
+
+        Returns
+        -------
+        str
+            The manufacturer of the monitor.
+
+        Examples
+        --------
+        ```python
+        app = Pyloid("Pyloid-App")
+
+        monitor = app.get_primary_monitor()
+        manufacturer = monitor.manufacturer()
+        print("Manufacturer:", manufacturer)
+        ```
         """
         monitor = self.screen
         return monitor.manufacturer()
@@ -326,8 +754,23 @@ class Monitor():
     def model(self) -> str:
         """
         Returns the model of the monitor.
-        
-        :return: Model of the monitor
+
+        The model refers to the specific model name or number assigned by the manufacturer.
+
+        Returns
+        -------
+        str
+            The model of the monitor.
+
+        Examples
+        --------
+        ```python
+        app = Pyloid("Pyloid-App")
+
+        monitor = app.get_primary_monitor()
+        model = monitor.model()
+        print("Model:", model)
+        ```
         """
         monitor = self.screen
         return monitor.model()
@@ -335,8 +778,23 @@ class Monitor():
     def name(self) -> str:
         """
         Returns the name of the monitor.
-        
-        :return: Name of the monitor
+
+        The name refers to the user-friendly name assigned to the monitor.
+
+        Returns
+        -------
+        str
+            The name of the monitor.
+
+        Examples
+        --------
+        ```python
+        app = Pyloid("Pyloid-App")
+
+        monitor = app.get_primary_monitor()
+        name = monitor.name()
+        print("Name:", name)
+        ```
         """
         monitor = self.screen
         return monitor.name()
@@ -344,29 +802,96 @@ class Monitor():
     def serial_number(self) -> str:
         """
         Returns the serial number of the monitor.
-        
-        :return: Serial number of the monitor
+
+        The serial number is a unique identifier assigned to the monitor by the manufacturer.
+
+        Returns
+        -------
+        str
+            The serial number of the monitor.
+
+        Examples
+        --------
+        ```python
+        app = Pyloid("Pyloid-App")
+
+        monitor = app.get_primary_monitor()
+        serial_number = monitor.serial_number()
+        print("Serial Number:", serial_number)
+        ```
         """
         monitor = self.screen
         return monitor.serialNumber()
     
     def geometry_changed(self, callback: Callable):
         """
-        Returns the event that occurs when the geometry of the monitor changes.
+        Registers a callback for the event that occurs when the geometry of the monitor changes.
+
+        Parameters
+        ----------
+        callback : Callable
+            The function to be called when the geometry changes.
+
+        Examples
+        --------
+        ```python
+        app = Pyloid("Pyloid-App")
+
+        def on_geometry_changed():
+            print("Geometry changed!")
+
+        monitor = app.get_primary_monitor()
+        monitor.geometry_changed(on_geometry_changed)
+        ```
         """
         monitor = self.screen
         monitor.geometryChanged.connect(callback)
 
     def orientation_changed(self, callback: Callable):
         """
-        Returns the event that occurs when the orientation of the monitor changes.
+        Registers a callback for the event that occurs when the orientation of the monitor changes.
+
+        Parameters
+        ----------
+        callback : Callable
+            The function to be called when the orientation changes.
+
+        Examples
+        --------
+        ```python
+        app = Pyloid("Pyloid-App")
+
+        def on_orientation_changed():
+            print("Orientation changed!")
+
+        monitor = app.get_primary_monitor()
+        monitor.orientation_changed(on_orientation_changed)
+        ```
         """
         monitor = self.screen
         monitor.orientationChanged.connect(callback)
 
     def refresh_rate_changed(self, callback: Callable):
         """
-        Returns the event that occurs when the refresh rate of the monitor changes.
+        Registers a callback for the event that occurs when the refresh rate of the monitor changes.
+
+        Parameters
+        ----------
+        callback : Callable
+            The function to be called when the refresh rate changes.
+
+        Examples
+        --------
+        ```python
+        app = Pyloid("Pyloid-App")
+
+        def on_refresh_rate_changed():
+            print("Refresh rate changed!")
+
+        monitor = app.get_primary_monitor()
+        monitor.refresh_rate_changed(on_refresh_rate_changed)
+        ```
         """
         monitor = self.screen
         monitor.refreshRateChanged.connect(callback)
+