### Install PyMonCtl using pip

Source: https://github.com/kalmat/pymonctl/blob/master/README.md

Instructions for installing the PyMonCtl library using pip. This can be done globally or for a specific Python 3 environment. It also mentions the option to install from a downloaded wheel file.

```bash
pip install pymonctl
```

```bash
python3 -m pip install pymonctl
```

```bash
pip install PyMonCtl-x.x.xx-py3-none-any.whl
```

--------------------------------

### Install PyMonCtl Dependencies

Source: https://github.com/kalmat/pymonctl/blob/master/README.md

This command installs all necessary dependencies for the PyMonCtl project, as listed in the 'requirements.txt' file. It is typically run after cloning the repository.

```bash
python3 -m pip install -r requirements.txt
```

--------------------------------

### Restore Monitor Setup

Source: https://github.com/kalmat/pymonctl/blob/master/docs/source/docstrings.md

Restores a previously saved monitor setup. This function attempts to re-attach, turn on, or wake monitors if necessary. Use arrangeMonitors() for repositioning only.

```python
def restoreSetup(setup: List[Tuple[Monitor, ScreenValue]])
```

--------------------------------

### Save Monitor Setup

Source: https://github.com/kalmat/pymonctl/blob/master/docs/source/docstrings.md

Saves the current configuration of all monitors, including position, mode, orientation, and scale. This information can be used later to restore the setup. Returns a list of tuples containing monitor information.

```python
def saveSetup() -> List[Tuple[Monitor, ScreenValue]]
```

--------------------------------

### Save and Restore Monitor Setup

Source: https://context7.com/kalmat/pymonctl/llms.txt

Saves the current complete monitor configuration, including position, mode, orientation, and scale settings, to a variable. It can later restore the monitors to this saved configuration. This is useful for reverting changes or applying a known setup.

```python
import pymonctl as pmc

# Save current monitor setup
saved_setup = pmc.saveSetup()
print(f"Saved setup for {len(saved_setup)} monitors")

# Make some changes (e.g., change resolution, orientation)
primary = pmc.getPrimary()
if primary.allModes:
    # Change to a different mode temporarily
    original_mode = primary.mode
    print(f"Current mode: {original_mode}")

# Later, restore the original setup
pmc.restoreSetup(saved_setup)
print("Setup restored successfully")
```

--------------------------------

### saveSetup

Source: https://github.com/kalmat/pymonctl/blob/master/docs/source/docstrings.md

Saves the current monitor setup, including position, mode, orientation, and scale, for later restoration.

```APIDOC
## saveSetup

### Description
Save current monitors setup information to be restored afterward. If you just need monitors information in dictionary format, use getAllMonitorsDict() instead. If you need all monitors instances to access all methods, use getAllMonitors() instead.

### Method
GET

### Endpoint
/saveSetup

### Response
#### Success Response (200)
- **List[Tuple[Monitor, ScreenValue]]** (list) - A list of tuples containing all necessary information to restore the saved setup.

### Response Example
```json
[
  [
    {
      "id": 1,
      "name": "Display_1",
      "primary": true,
      "pos": {"x": 0, "y": 0},
      "size": {"width": 1920, "height": 1080},
      "workarea": {"x": 0, "y": 0, "right": 1920, "bottom": 1040}
    },
    {
      "mode": {"width": 1920, "height": 1080, "refresh_rate": 60},
      "orientation": "horizontal",
      "scale": 1.0
    }
  ]
]
```
```

--------------------------------

### restoreSetup

Source: https://github.com/kalmat/pymonctl/blob/master/docstrings.md

Restores a previously saved monitor setup. This function can also attempt to re-attach, turn on, or wake monitors if necessary.

```APIDOC
## POST /restoreSetup

### Description
Restores a given monitor setup, including position, mode, orientation, and scale. The function will also attempt to re-attach, turn on, or wake monitors if needed. Use `arrangeMonitors` if you only want to reposition monitors.

### Method
POST

### Endpoint
/restoreSetup

### Parameters
#### Request Body
- **setup** (list) - Required - A list of tuples containing the monitor information and screen values as returned by `saveSetup()`.

### Request Example
```json
[
    [
        {
            "name": "Display 1",
            "id": 1,
            "primary": true,
            "pos": {"x": 0, "y": 0},
            "size": {"width": 1920, "height": 1080},
            "workarea": {"x": 0, "y": 0, "right": 1920, "bottom": 1040}
        },
        {
            "mode": {"width": 1920, "height": 1080, "refresh_rate": 60},
            "scale": 1.0,
            "orientation": "horizontal"
        }
    ]
]
```

### Response
#### Success Response (200)
This endpoint typically returns no specific data on success, indicating the setup was applied.

#### Response Example
(No explicit response body on success)
```

--------------------------------

### saveSetup

Source: https://github.com/kalmat/pymonctl/blob/master/docstrings.md

Saves the current monitor setup, including position, mode, orientation, and scale, for later restoration.

```APIDOC
## POST /saveSetup

### Description
Saves the current monitors setup information, which can be restored later using the `restoreSetup` function. This is useful for backing up and reapplying monitor configurations.

### Method
POST

### Endpoint
/saveSetup

### Parameters
None

### Response
#### Success Response (200)
- **setup** (list) - A list of tuples, where each tuple contains monitor information and screen values necessary to restore the setup.

#### Response Example
```json
[
    [
        {
            "name": "Display 1",
            "id": 1,
            "primary": true,
            "pos": {"x": 0, "y": 0},
            "size": {"width": 1920, "height": 1080},
            "workarea": {"x": 0, "y": 0, "right": 1920, "bottom": 1040}
        },
        {
            "mode": {"width": 1920, "height": 1080, "refresh_rate": 60},
            "scale": 1.0,
            "orientation": "horizontal"
        }
    ]
]
```
```

--------------------------------

### Get and Set Monitor Brightness

Source: https://context7.com/kalmat/pymonctl/llms.txt

Enables getting and setting the monitor's brightness level as a percentage (0-100). This functionality requires VCP MCCS support on Windows.

```python
import pymonctl as pmc

monitor = pmc.getPrimary()

# Get current brightness
current_brightness = monitor.brightness
if current_brightness is not None:
    print(f"Current brightness: {current_brightness}%")

    # Set brightness to 75%
    monitor.setBrightness(75)
    print(f"New brightness: {monitor.brightness}%")
else:
    print("Brightness control not supported on this monitor")
```

--------------------------------

### restoreSetup

Source: https://github.com/kalmat/pymonctl/blob/master/docs/source/docstrings.md

Restores a previously saved monitor setup, including position, mode, orientation, and scale. It also attempts to re-attach, turn on, or wake monitors if necessary.

```APIDOC
## restoreSetup

### Description
Restore given monitors setup (position, mode, orientation, scale, etc.). The function will also try to re-attach / turn on / wake monitors if needed. In case you want to just reposition monitors without changing all other settings, use arrangeMonitors() instead.

### Method
POST

### Endpoint
/restoreSetup

### Parameters
#### Request Body
- **setup** (List[Tuple[Monitor, ScreenValue]]) - Required - Monitors info dictionary as returned by saveSetup()

### Request Example
```json
[
  [
    {
      "id": 1,
      "name": "Display_1",
      "primary": true,
      "pos": {"x": 0, "y": 0},
      "size": {"width": 1920, "height": 1080},
      "workarea": {"x": 0, "y": 0, "right": 1920, "bottom": 1040}
    },
    {
      "mode": {"width": 1920, "height": 1080, "refresh_rate": 60},
      "orientation": "horizontal",
      "scale": 1.0
    }
  ]
]
```

### Response
#### Success Response (200)
(No specific success response body is defined, typically indicates successful execution)
```

--------------------------------

### Set Monitor as Primary (Python)

Source: https://github.com/kalmat/pymonctl/blob/master/docs/source/docstrings.md

Sets the specified monitor as the primary display. Note that this action may alter monitor positions and the overall display setup. It is recommended to use `arrangeMonitors()` for more robust setup management. This is an abstract method.

```python
@abstractmethod
def setPrimary()

```

--------------------------------

### Contrast Control

Source: https://github.com/kalmat/pymonctl/blob/master/docstrings.md

Get and set the contrast of a monitor. Contrast is represented as a percentage (0-100).

```APIDOC
## GET /monitor/contrast

### Description
Retrieves the current contrast level of the monitor.

### Method
GET

### Endpoint
/monitor/contrast

### Parameters
None

### Response
#### Success Response (200)
- **contrast** (int) - The current contrast level, normalized to 0-100.

#### Response Example
```json
{
  "contrast": 60
}
```

## PUT /monitor/contrast

### Description
Sets the contrast level of the monitor.

### Method
PUT

### Endpoint
/monitor/contrast

### Parameters
#### Request Body
- **contrast** (int) - The desired contrast level, as a percentage (0-100).

### Request Example
```json
{
  "contrast": 70
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Contrast set to 70%"
}
```
```

--------------------------------

### Get All Monitors as Dictionary (Python)

Source: https://context7.com/kalmat/pymonctl/llms.txt

Returns a dictionary with detailed information for all connected monitors. Monitor names serve as keys, and values are dictionaries containing properties such as system name, ID, position, size, scale, DPI, orientation, and color depth.

```python
import pymonctl as pmc

# Get all monitors info as dictionary
monitors_info = pmc.getAllMonitorsDict()

for name, info in monitors_info.items():
    print(f"Monitor: {name}")
    print(f"  System Name: {info['system_name']}")
    print(f"  ID: {info['id']}")
    print(f"  Is Primary: {info['is_primary']}")
    print(f"  Position: {info['position']}")
    print(f"  Size: {info['size']}")
    print(f"  Workarea: {info['workarea']}")
    print(f"  Scale: {info['scale']}")
    print(f"  DPI: {info['dpi']}")
    print(f"  Orientation: {info['orientation']}")
    print(f"  Frequency: {info['frequency']} Hz")
    print(f"  Color Depth: {info['colordepth']} bits")
    print()

# Expected output:
# Monitor: DELL U2415
#   System Name: DELL U2415
#   ID: 65537
#   Is Primary: True
#   Position: Point(x=0, y=0)
#   Size: Size(width=1920, height=1200)
#   Workarea: Rect(left=0, top=0, right=1920, bottom=1160)
#   Scale: (100.0, 100.0)
#   DPI: (96, 96)
#   Orientation: 0
#   Frequency: 59.95 Hz
#   Color Depth: 32 bits
```

--------------------------------

### Get All Monitors (Python)

Source: https://github.com/kalmat/pymonctl/blob/master/docs/source/docstrings.md

Retrieves a list of all Monitor instances from connected displays. For frequent calls, enabling the update watchdog via enableUpdate() is recommended. Returns a list of Monitor instances.

```python
def getAllMonitors() -> list[Monitor]:
    # Implementation details...
    pass
```

--------------------------------

### Brightness Control

Source: https://github.com/kalmat/pymonctl/blob/master/docstrings.md

Get and set the brightness of a monitor. Brightness is represented as a percentage (0-100).

```APIDOC
## GET /monitor/brightness

### Description
Retrieves the current brightness level of the monitor.

### Method
GET

### Endpoint
/monitor/brightness

### Parameters
None

### Response
#### Success Response (200)
- **brightness** (int) - The current brightness level, normalized to 0-100.

#### Response Example
```json
{
  "brightness": 75
}
```

## PUT /monitor/brightness

### Description
Sets the brightness level of the monitor.

### Method
PUT

### Endpoint
/monitor/brightness

### Parameters
#### Request Body
- **brightness** (int) - The desired brightness level, as a percentage (0-100).

### Request Example
```json
{
  "brightness": 80
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Brightness set to 80%"
}
```
```

--------------------------------

### Define and Print Rect Object in Python

Source: https://context7.com/kalmat/pymonctl/llms.txt

Demonstrates how to define a Rect object with left, top, right, and bottom attributes and print its coordinates. This is a basic usage example for representing screen areas.

```python
from pymonctl import Rect

# Rect: left, top, right, bottom
rect = Rect(0, 0, 1920, 1080)
print(f"Rect: ({rect.left}, {rect.top}) to ({rect.right}, {rect.bottom})")
```

--------------------------------

### Get Primary Monitor (Python)

Source: https://github.com/kalmat/pymonctl/blob/master/docs/source/docstrings.md

Retrieves the primary monitor instance. This is equivalent to calling Monitor() with no arguments. Returns the primary Monitor instance or None if not found.

```python
def getPrimary() -> Monitor:
    # Implementation details...
    pass
```

--------------------------------

### Get All Allowed Monitor Modes (Python)

Source: https://github.com/kalmat/pymonctl/blob/master/docstrings.md

Retrieves a list of all display modes supported by the monitor. Each mode in the list is represented as a DisplayMode struct, containing width, height, and frequency.

```python
@property
@abstractmethod
def allModes() -> list[DisplayMode]:
    """Get all allowed modes for the monitor

    Returns:
        list of DisplayMode (width, height, frequency)
    """
    pass
```

--------------------------------

### Get and Set Monitor Contrast

Source: https://context7.com/kalmat/pymonctl/llms.txt

Provides functionality to retrieve and adjust the monitor's contrast level, expressed as a percentage (0-100). On Linux and macOS, this operation modifies gamma values.

```python
import pymonctl as pmc

monitor = pmc.getPrimary()

# Get current contrast
current_contrast = monitor.contrast
if current_contrast is not None:
    print(f"Current contrast: {current_contrast}%")

    # Set contrast to 60%
    monitor.setContrast(60)
    print(f"New contrast: {monitor.contrast}%")
else:
    print("Contrast control not supported on this monitor")
```

--------------------------------

### Get Monitor Contrast (Python)

Source: https://github.com/kalmat/pymonctl/blob/master/docstrings.md

Retrieves the current contrast of a monitor. The contrast is returned as an integer percentage (0-100). Note that on Linux and macOS, contrast is calculated from Gamma RGB values.

```python
@property
@abstractmethod
def contrast() -> Optional[int]:
    """Get the contrast of monitor. The return value is normalized to 0-100 (as a percentage)

    WARNING: In Linux and macOS contrast is calculated from Gamma RGB values.

    Returns:
        contrast as int (1-100)
    """
    pass
```

--------------------------------

### Get Monitor Contrast (Python)

Source: https://github.com/kalmat/pymonctl/blob/master/docs/source/docstrings.md

Retrieves the current contrast of a monitor, normalized to a percentage (0-100). On Linux and macOS, contrast is calculated from Gamma RGB values. This is an abstract property.

```python
@property
@abstractmethod
def contrast() -> Optional[int]

```

--------------------------------

### Manage Monitor Display Modes

Source: https://context7.com/kalmat/pymonctl/llms.txt

Handles monitor display modes, including resolution and refresh rate. It allows getting the current mode, the default/preferred mode, and listing all available modes. A specific mode can be set, or the monitor can be reset to its default mode.

```python
import pymonctl as pmc

monitor = pmc.getPrimary()

# Get current mode
current_mode = monitor.mode
print(f"Current mode: {current_mode.width}x{current_mode.height} @ {current_mode.frequency}Hz")

# Get default/preferred mode
default_mode = monitor.defaultMode
print(f"Default mode: {default_mode.width}x{default_mode.height} @ {default_mode.frequency}Hz")

# List all available modes
all_modes = monitor.allModes
print(f"\nAvailable modes ({len(all_modes)} total):")
for mode in all_modes[:5]:  # Show first 5
    print(f"  {mode.width}x{mode.height} @ {mode.frequency}Hz")

# Change to a specific mode
# target_mode = DisplayMode(1920, 1080, 60.0)
# if target_mode in all_modes:
#     monitor.setMode(target_mode)

# Reset to default mode
# monitor.setDefaultMode()
```

--------------------------------

### Get and Set Monitor Scale

Source: https://context7.com/kalmat/pymonctl/llms.txt

Retrieves the current display scaling factor and sets a new scaling factor for the monitor. The `applyGlobally` parameter can affect all monitors on Linux/GNOME systems.

```python
import pymonctl as pmc

monitor = pmc.getPrimary()

# Get current scale
print(f"Current scale: {monitor.scale}")

# Set new scale (125%)
# Note: On Linux/GNOME, applyGlobally=True affects all monitors
monitor.setScale((125.0, 125.0), applyGlobally=False)
print(f"New scale: {monitor.scale}")
```

--------------------------------

### Get Primary Monitor (Python)

Source: https://context7.com/kalmat/pymonctl/llms.txt

Retrieves the Monitor instance representing the primary display. This function is equivalent to calling the Monitor() constructor without any arguments. It returns a Monitor object with its properties.

```python
import pymonctl as pmc

primary = pmc.getPrimary()

print(f"Primary Monitor: {primary.name}")
print(f"  Size: {primary.size}")
print(f"  Position: {primary.position}")
print(f"  Default Mode: {primary.defaultMode}")
print(f"  Current Mode: {primary.mode}")

# Expected output:
# Primary Monitor: DELL U2415
#   Size: Size(width=1920, height=1200)
#   Position: Point(x=0, y=0)
#   Default Mode: DisplayMode(width=1920, height=1200, frequency=59.95)
#   Current Mode: DisplayMode(width=1920, height=1200, frequency=59.95)
```

--------------------------------

### Get All Allowed Monitor Modes (Python)

Source: https://github.com/kalmat/pymonctl/blob/master/docs/source/docstrings.md

Retrieves a list of all supported display modes for the monitor. Each mode in the list is a DisplayMode struct containing width, height, and frequency. This is an abstract property.

```python
@property
@abstractmethod
def allModes() -> list[DisplayMode]

```

--------------------------------

### Get All Monitors (Python)

Source: https://context7.com/kalmat/pymonctl/llms.txt

Retrieves a list of all connected Monitor instances. For performance-critical applications, consider enabling the update watchdog. This function returns a list of Monitor objects, each containing properties like name, size, position, and primary status.

```python
import pymonctl as pmc

# Get all connected monitors
monitors = pmc.getAllMonitors()

for monitor in monitors:
    print(f"Monitor: {monitor.name}")
    print(f"  Size: {monitor.size}")
    print(f"  Position: {monitor.position}")
    print(f"  Is Primary: {monitor.isPrimary}")
    print(f"  Frequency: {monitor.frequency} Hz")
    print()

# Expected output:
# Monitor: DELL U2415
#   Size: Size(width=1920, height=1200)
#   Position: Point(x=0, y=0)
#   Is Primary: True
#   Frequency: 59.95 Hz
```

--------------------------------

### Register/Unregister Monitor Plug Events

Source: https://context7.com/kalmat/pymonctl/llms.txt

Set up callbacks to be notified when monitors are plugged in or unplugged using `plugListenerRegister` and `plugListenerUnregister`. The `on_monitor_plugged` function serves as an example callback, receiving the names of affected monitors and their screen information. `isPlugListenerRegistered` checks if a listener is active.

```python
import pymonctl as pmc
import time

def on_monitor_plugged(names, screens_info):
    """Called when monitors are plugged/unplugged"""
    print(f"Monitor change detected: {names}")
    for name in names:
        if name in screens_info:
            print(f"  {name}: {screens_info[name]['size']}")
        else:
            print(f"  {name}: unplugged")

# Register the callback
pmc.plugListenerRegister(on_monitor_plugged)
print(f"Plug listener registered: {pmc.isPlugListenerRegistered(on_monitor_plugged)}")

# Wait for plug/unplug events
print("Plug/unplug monitors to see events (Ctrl+C to exit)...")
try:
    while True:
        time.sleep(1)
except KeyboardInterrupt:
    pass

# Unregister when done
pmc.plugListenerUnregister(on_monitor_plugged)
print("Listener unregistered")
```

--------------------------------

### Monitor Class - Get Position

Source: https://github.com/kalmat/pymonctl/blob/master/docs/source/docstrings.md

Gets the monitor's position coordinates (x, y) as a Point struct. This property cannot be set; use the setPosition() method instead.

```python
@property
@abstractmethod
def position() -> Optional[Point]
```

--------------------------------

### Monitor Class - Get Size

Source: https://github.com/kalmat/pymonctl/blob/master/docs/source/docstrings.md

Gets the dimensions (width, height) of the monitor as a Size struct. This property cannot be set directly; instead, select an allowed mode and set the monitor.mode property.

```python
@property
@abstractmethod
def size() -> Optional[Size]
```

--------------------------------

### Get Monitor Brightness

Source: https://github.com/kalmat/pymonctl/blob/master/docstrings.md

Retrieves the current brightness level of the monitor.

```APIDOC
## GET /monitors/{monitor_id}/brightness

### Description
Gets the current brightness level of the monitor.

### Method
GET

### Endpoint
`/monitors/{monitor_id}/brightness`

### Parameters
#### Path Parameters
- **monitor_id** (string) - Required - The identifier of the monitor.

### Response
#### Success Response (200)
- **brightness** (float) - The current brightness level of the monitor.

#### Response Example
```json
{
  "brightness": 0.8
}
```
```

--------------------------------

### Run PyMonCtl Tests

Source: https://github.com/kalmat/pymonctl/blob/master/README.md

This command executes the test suite for the PyMonCtl module. Navigate to the 'tests' directory and run this script to verify the module's functionality.

```bash
python3 test_pymonctl.py
```

--------------------------------

### getMonitorsCount

Source: https://github.com/kalmat/pymonctl/blob/master/docs/source/docstrings.md

Gets the total number of monitors currently connected to the system.

```APIDOC
## getMonitorsCount

### Description
Get the number of monitors currently connected to the system.

### Method
GET

### Endpoint
/monitors/count

### Parameters
#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **count** (int) - The number of connected monitors.

#### Response Example
```json
{
  "count": 2
}
```
```

--------------------------------

### Get Monitor Frequency

Source: https://github.com/kalmat/pymonctl/blob/master/docstrings.md

Retrieves the current refresh rate (frequency) of the monitor.

```APIDOC
## GET /monitors/{monitor_id}/frequency

### Description
Gets the current refresh rate of the monitor.

This property cannot be set independently. To change it, select an allowed mode from `monitor.allModes` and set the `monitor.mode` property.

### Method
GET

### Endpoint
`/monitors/{monitor_id}/frequency`

### Parameters
#### Path Parameters
- **monitor_id** (string) - Required - The identifier of the monitor.

### Response
#### Success Response (200)
- **frequency** (float) - The current refresh rate of the monitor in Hz.

#### Response Example
```json
{
  "frequency": 60.0
}
```
```

--------------------------------

### Turn On Monitor (Python)

Source: https://github.com/kalmat/pymonctl/blob/master/docs/source/docstrings.md

Wakes up a monitor if it is currently off or suspended. This method will not work if the monitor is detached. This is an abstract method.

```python
@abstractmethod
def turnOn()

```

--------------------------------

### Get All Monitors as Dictionary (Python)

Source: https://github.com/kalmat/pymonctl/blob/master/docs/source/docstrings.md

Fetches information for all connected monitors as a Python dictionary. Similar to getAllMonitors(), enabling the update watchdog is advised for repeated invocations. The dictionary keys are display names, and values contain detailed monitor properties.

```python
def getAllMonitorsDict() -> dict[str, ScreenValue]:
    # Implementation details...
    pass
```

--------------------------------

### Monitor Class Methods

Source: https://github.com/kalmat/pymonctl/blob/master/docstrings.md

Documentation for methods and properties available on the Monitor class.

```APIDOC
## Monitor Class

### Description
Provides access to monitor properties and methods.

### Methods and Properties

#### size

##### Description
Gets the dimensions of the monitor as a size struct (width, height). This property cannot be set directly; to change dimensions, select an allowed mode from `monitor.allModes` and set the `monitor.mode` property.

##### Type
Read-only property

##### Returns
- **Size** (object) - An object containing the width and height of the monitor.
  - **width** (int) - The width of the monitor in pixels.
  - **height** (int) - The height of the monitor in pixels.

##### Example
```python
monitor_size = monitor.size
print(f"Monitor size: {monitor_size.width}x{monitor_size.height}")
```

#### workarea

##### Description
Gets the dimensions of the "usable by applications" area of the screen (screen size minus docks, taskbars, etc.), returned as a rect struct (x, y, right, bottom). This property cannot be set.

##### Type
Read-only property

##### Returns
- **Rect** (object) - An object containing the coordinates and dimensions of the work area.
  - **x** (int) - The x-coordinate of the top-left corner.
  - **y** (int) - The y-coordinate of the top-left corner.
  - **right** (int) - The x-coordinate of the bottom-right corner.
  - **bottom** (int) - The y-coordinate of the bottom-right corner.

##### Example
```python
work_area = monitor.workarea
print(f"Work area: x={work_area.x}, y={work_area.y}, right={work_area.right}, bottom={work_area.bottom}")
```

#### position

##### Description
Gets the monitor's position coordinates as a point struct (x, y). This property cannot be set directly; use the `setPosition()` method instead.

##### Type
Read-only property

##### Returns
- **Point** (object) - An object containing the x and y coordinates of the monitor's top-left corner.
  - **x** (int) - The x-coordinate.
  - **y** (int) - The y-coordinate.

##### Example
```python
monitor_pos = monitor.position
print(f"Monitor position: x={monitor_pos.x}, y={monitor_pos.y}")
```

#### setPosition

##### Description
Sets the position of the monitor to the specified coordinates.

##### Method Signature
`setPosition(pos: Point)`

##### Parameters
- **pos** (Point) - Required - The new position for the monitor.

##### Example
```python
new_position = Point(x=0, y=0)
monitor.setPosition(new_position)
```
```

--------------------------------

### Get Monitor Scale

Source: https://github.com/kalmat/pymonctl/blob/master/docstrings.md

Retrieves the current scale factor for the monitor in both X and Y directions.

```APIDOC
## GET /monitors/{monitor_id}/scale

### Description
Gets the scale for the monitor.

Note: Not all scales are allowed for all monitors and/or modes.

### Method
GET

### Endpoint
`/monitors/{monitor_id}/scale`

### Parameters
#### Path Parameters
- **monitor_id** (string) - Required - The identifier of the monitor.

### Response
#### Success Response (200)
- **scale** (Tuple[float, float]) - A tuple containing the scale value in X and Y coordinates.

#### Response Example
```json
{
  "scale": [1.0, 1.0]
}
```
```

--------------------------------

### Arrange Monitors

Source: https://github.com/kalmat/pymonctl/blob/master/docs/source/docstrings.md

Arranges all monitors in a specified configuration. Requires a dictionary defining the relative position and reference monitor for each display. All monitors must be included, and one must be set as primary.

```python
def arrangeMonitors(arrangement: dict[str,
                                      dict[str,
                                           Optional[Union[str, int, Position,
                                                          Point, Size]]]])
```

--------------------------------

### Get Monitor Color Depth

Source: https://github.com/kalmat/pymonctl/blob/master/docstrings.md

Retrieves the color depth (bits per pixel) value for the monitor.

```APIDOC
## GET /monitors/{monitor_id}/colordepth

### Description
Gets the color depth (bits per pixel to describe color) value for the monitor.

This property cannot be set.

### Method
GET

### Endpoint
`/monitors/{monitor_id}/colordepth`

### Parameters
#### Path Parameters
- **monitor_id** (string) - Required - The identifier of the monitor.

### Response
#### Success Response (200)
- **colordepth** (int) - The color depth of the monitor in bits per pixel.

#### Response Example
```json
{
  "colordepth": 24
}
```
```

--------------------------------

### Get Monitor DPI

Source: https://github.com/kalmat/pymonctl/blob/master/docstrings.md

Retrieves the dots per inch (DPI) value for the monitor in both X and Y directions.

```APIDOC
## GET /monitors/{monitor_id}/dpi

### Description
Gets the DPI (dots/pixels per inch) value for the monitor.

This property cannot be set.

### Method
GET

### Endpoint
`/monitors/{monitor_id}/dpi`

### Parameters
#### Path Parameters
- **monitor_id** (string) - Required - The identifier of the monitor.

### Response
#### Success Response (200)
- **dpi** (Tuple[float, float]) - A tuple containing the DPI value in X and Y coordinates.

#### Response Example
```json
{
  "dpi": [96.0, 96.0]
}
```
```

--------------------------------

### Find Monitor Info by Name (Python)

Source: https://github.com/kalmat/pymonctl/blob/master/docs/source/docstrings.md

Retrieves the detailed information of a monitor whose name matches the provided string. It takes the monitor name as input and returns a dictionary containing the monitor's information, or an empty dictionary if the monitor is not found.

```python
def findMonitorWithNameInfo(name: str) -> dict[str, ScreenValue]:
    # Implementation details...
    pass
```

--------------------------------

### Register Monitor Change Listeners in Python

Source: https://github.com/kalmat/pymonctl/blob/master/README.md

This code snippet demonstrates how to register listener functions to be called when monitor plug/unplug events or property changes occur. It utilizes the pymonctl library and requires the 'time' module for the main loop. The listeners receive the names of changed monitors and their information.

```python
import pymonctl as pmc
import time

def countChanged(names, screensInfo):
    print("MONITOR PLUGGED/UNPLUGGED:", names)
    for name in names:
        print("MONITORS INFO:", screensInfo[name])

def propsChanged(names, screensInfo):
    print("MONITOR CHANGED:", names)
    for name in names:
        print("MONITORS INFO:", screensInfo[name])

pmc.plugListenerRegister(countChanged)
pmc.changeListenerRegister(propsChanged)

print("Plug/Unplug monitors, or change monitor properties while running")
print("Press Ctl-C to Quit")
while True:
    try:
        time.sleep(1)
    except KeyboardInterrupt:
        break

pmc.plugListenerUnregister(countChanged)
pmc.changeListenerUnregister(propsChanged)
```

--------------------------------

### Find Monitor by Name (Python)

Source: https://github.com/kalmat/pymonctl/blob/master/docs/source/docstrings.md

Searches for and returns a Monitor instance whose name matches the provided string. It takes the monitor name as an argument and returns the corresponding Monitor instance or None if no match is found.

```python
def findMonitorWithName(name: str) -> Optional[Monitor]:
    # Implementation details...
    pass
```

--------------------------------

### Turn On Monitor (Python)

Source: https://github.com/kalmat/pymonctl/blob/master/docstrings.md

Wakes up a monitor if it is currently off or in standby mode. This function is applicable only if the monitor is attached and not detached. It does not apply to detached monitors.

```python
@abstractmethod
def turnOn():
    """Turn on or wakeup monitor if it was off or suspended (but not if it is detached)."""
    pass
```

--------------------------------

### Get Monitor Box Dimensions

Source: https://github.com/kalmat/pymonctl/blob/master/docstrings.md

Retrieves the dimensions of a monitor as a box structure, including its x, y coordinates, width, and height.

```APIDOC
## GET /monitors/{monitor_id}/box

### Description
Gets the monitor dimensions as a box struct (x, y, width, height).

This property cannot be set.

### Method
GET

### Endpoint
`/monitors/{monitor_id}/box`

### Parameters
#### Path Parameters
- **monitor_id** (string) - Required - The identifier of the monitor.

### Response
#### Success Response (200)
- **box** (Box) - The dimensions of the monitor (x, y, width, height).

#### Response Example
```json
{
  "box": {
    "x": 0,
    "y": 0,
    "width": 1920,
    "height": 1080
  }
}
```
```

--------------------------------

### getAllMonitors

Source: https://github.com/kalmat/pymonctl/blob/master/docs/source/docstrings.md

Retrieves a list of all Monitor instances from plugged monitors. It's recommended to enable the update watchdog for frequent calls.

```APIDOC
## getAllMonitors

### Description
Get the list with all Monitor instances from plugged monitors. In case you plan to use this function in a scenario in which it could be invoked quickly and repeatedly, it’s highly recommended to enable update watchdog (see enableUpdate() function).

### Method
GET

### Endpoint
/monitors

### Parameters
#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **monitors** (list[Monitor]) - A list of Monitor instances.

#### Response Example
```json
[
  {
    "system_name": "monitor1",
    "id": "monitor1_id",
    "is_primary": true,
    "position": {"x": 0, "y": 0},
    "size": {"width": 1920, "height": 1080},
    "workarea": {"left": 0, "top": 0, "right": 1920, "bottom": 1040},
    "scale": [1.0, 1.0],
    "dpi": [96, 96],
    "orientation": 0,
    "frequency": 60,
    "colordepth": 24
  }
]
```
```

--------------------------------

### Get Monitor Color Depth (Python)

Source: https://github.com/kalmat/pymonctl/blob/master/docstrings.md

Retrieves the color depth (bits per pixel) of the monitor. This is a read-only property.

```python
@property
@abstractmethod
def colordepth() -> Optional[int]
```

--------------------------------

### getAllMonitorsDict

Source: https://github.com/kalmat/pymonctl/blob/master/docs/source/docstrings.md

Retrieves all monitor information as a dictionary. The dictionary keys are display names, and values contain detailed monitor properties. Recommended to enable update watchdog for frequent calls.

```APIDOC
## getAllMonitorsDict

### Description
Get all monitors info plugged to the system, as a dict. In case you plan to use this function in a scenario in which it could be invoked quickly and repeatedly, it’s highly recommended to enable update watchdog (see enableUpdate() function).

### Method
GET

### Endpoint
/monitors/info

### Parameters
#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **monitors_info** (dict[str, ScreenValue]) - A dictionary where keys are monitor display names and values are dictionaries containing monitor details.

#### Response Example
```json
{
  "monitor1": {
    "system_name": "monitor1",
    "id": "monitor1_id",
    "is_primary": true,
    "position": {"x": 0, "y": 0},
    "size": {"width": 1920, "height": 1080},
    "workarea": {"left": 0, "top": 0, "right": 1920, "bottom": 1040},
    "scale": [1.0, 1.0],
    "dpi": [96, 96],
    "orientation": 0,
    "frequency": 60,
    "colordepth": 24
  }
}
```
```

--------------------------------

### Get Mouse Position

Source: https://github.com/kalmat/pymonctl/blob/master/docs/source/docstrings.md

Retrieves the current screen coordinates (x, y) of the mouse pointer in pixels. Returns a Point struct.

```python
def getMousePos() -> Point
```

--------------------------------

### Get Monitor Rectangle Dimensions

Source: https://github.com/kalmat/pymonctl/blob/master/docstrings.md

Retrieves the dimensions of a monitor as a rectangle structure, including its x, y coordinates, right, and bottom boundaries.

```APIDOC
## GET /monitors/{monitor_id}/rect

### Description
Gets the monitor dimensions as a rect struct (x, y, right, bottom).

This property cannot be set.

### Method
GET

### Endpoint
`/monitors/{monitor_id}/rect`

### Parameters
#### Path Parameters
- **monitor_id** (string) - Required - The identifier of the monitor.

### Response
#### Success Response (200)
- **rect** (Rect) - The dimensions of the monitor (x, y, right, bottom).

#### Response Example
```json
{
  "rect": {
    "x": 0,
    "y": 0,
    "right": 1920,
    "bottom": 1080
  }
}
```
```

--------------------------------

### Get PyMonCtl Version

Source: https://github.com/kalmat/pymonctl/blob/master/docs/source/docstrings.md

Returns the current version of the PyMonCtl module as a string in the format 'x.x.xx'. By default, it returns only the version number.

```python
def version(numberOnly: bool = True) -> str
```

--------------------------------

### Get Monitor Dimensions and Positioning

Source: https://context7.com/kalmat/pymonctl/llms.txt

Provides read-only access to various properties of a monitor, including its size in pixels, the work area (excluding taskbars), its top-left position, its bounding box (left, top, width, height), and its bounding rectangle (left, top, right, bottom).

```python
import pymonctl as pmc

monitor = pmc.getPrimary()

# Size: width and height in pixels
size = monitor.size
print(f"Size: {size.width}x{size.height}")

# Position: top-left corner coordinates
pos = monitor.position
print(f"Position: ({pos.x}, {pos.y})")

# Box: position + dimensions (left, top, width, height)
box = monitor.box
print(f"Box: left={box.left}, top={box.top}, width={box.width}, height={box.height}")

# Rect: bounding rectangle (left, top, right, bottom)
rect = monitor.rect
print(f"Rect: left={rect.left}, top={rect.top}, right={rect.right}, bottom={rect.bottom}")

# Workarea: usable area excluding taskbars/docks
workarea = monitor.workarea
print(f"Workarea: left={workarea.left}, top={workarea.top}, right={workarea.right}, bottom={workarea.bottom}")
```

--------------------------------

### Update Screen Information

Source: https://github.com/kalmat/pymonctl/blob/master/docstrings.md

Functions to enable or disable a background thread that periodically updates monitor information, useful for dynamic multi-monitor setups.

```APIDOC
## POST /enableUpdateInfo

### Description
Enables a background thread to periodically update monitor information. This is recommended if you frequently need to query monitor details or if monitors can be dynamically added or removed. Enabling this can improve performance by avoiding repeated, potentially slow, queries.

### Method
POST

### Endpoint
/enableUpdateInfo

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates that update info has been enabled.

#### Response Example
```json
{
  "message": "Monitor update info enabled."
}
```

## POST /disableUpdateInfo

### Description
Disables the background thread for updating monitor information. After disabling, monitor information will be queried immediately when needed, which might be slower. You can re-enable this feature or call `getMonitors()` for updated information.

### Method
POST

### Endpoint
/disableUpdateInfo

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates that update info has been disabled.

#### Response Example
```json
{
  "message": "Monitor update info disabled."
}
```
```

--------------------------------

### Get Default Monitor Mode (Python)

Source: https://github.com/kalmat/pymonctl/blob/master/docs/source/docstrings.md

Retrieves the preferred or default display mode for the monitor, including width, height, and frequency. This is an abstract property.

```python
@property
@abstractmethod
def defaultMode() -> Optional[DisplayMode]

```

--------------------------------

### Find Monitor by Name (Python)

Source: https://context7.com/kalmat/pymonctl/llms.txt

Searches for and returns a Monitor instance that matches the provided monitor name. If no monitor with the specified name is found, it returns None. This function allows direct access to a monitor by its identifier.

```python
import pymonctl as pmc

# Find a specific monitor by name
monitor_name = "DELL U2415"
monitor = pmc.findMonitorWithName(monitor_name)

if monitor:
    print(f"Found monitor: {monitor.name}")
    print(f"  Size: {monitor.size}")
    print(f"  Brightness: {monitor.brightness}")
    print(f"  All available modes: {len(monitor.allModes)} modes")
else:
    print(f"Monitor '{monitor_name}' not found")

# Expected output:
# Found monitor: DELL U2415
#   Size: Size(width=1920, height=1200)
#   Brightness: 75
#   All available modes: 24 modes
```

--------------------------------

### Get Monitor Color Depth (Python)

Source: https://github.com/kalmat/pymonctl/blob/master/docs/source/docstrings.md

Retrieves the color depth (bits per pixel) of the monitor as an integer. This is a read-only property and cannot be set directly.

```python
@property
def colordepth() -> Optional[int]
```

--------------------------------

### Find Monitors at Point (Python)

Source: https://github.com/kalmat/pymonctl/blob/master/docs/source/docstrings.md

Identifies all Monitor instances that contain the specified coordinates (x, y). It takes x and y integer coordinates as input and returns a list of Monitor instances found at that point, or an empty list if none are found.

```python
def findMonitorsAtPoint(x: int, y: int) -> List[Monitor]:
    # Implementation details...
    pass
```

--------------------------------

### Get Monitor DPI (Python)

Source: https://github.com/kalmat/pymonctl/blob/master/docstrings.md

Retrieves the dots per inch (DPI) value for the monitor as a tuple of floats for X and Y coordinates. This is a read-only property.

```python
@property
@abstractmethod
def dpi() -> Optional[Tuple[float, float]]
```

--------------------------------

### Find Monitor Info at Point (Python)

Source: https://github.com/kalmat/pymonctl/blob/master/docs/source/docstrings.md

Retrieves detailed information for all monitors that contain the specified coordinates (x, y). It accepts x and y integer coordinates and returns a list of dictionaries, where each dictionary contains the info for a monitor at that point. Returns an empty list if no monitors are found.

```python
def findMonitorsAtPointInfo(x: int, y: int) -> List[dict[str, ScreenValue]]:
    # Implementation details...
    pass
```

--------------------------------

### Enable Monitor Update Info (Python)

Source: https://github.com/kalmat/pymonctl/blob/master/docs/source/docstrings.md

Enables a separate thread to periodically update monitor information. This is useful for tracking changes in resolution, position, or dynamic plugging/unplugging of monitors, and for frequent queries of monitor data without impacting the main process.

```python
def enableUpdateInfo()

```

--------------------------------

### Get Monitor Dimensions as Box (Python)

Source: https://github.com/kalmat/pymonctl/blob/master/docstrings.md

Retrieves the monitor's dimensions as a Box struct, containing x, y, width, and height. This is a read-only property.

```python
@property
@abstractmethod
def box() -> Optional[Box]
```

--------------------------------

### Get Monitor DPI (Python)

Source: https://github.com/kalmat/pymonctl/blob/master/docs/source/docstrings.md

Retrieves the Dots Per Inch (DPI) value for the monitor as a tuple of floats (X, Y). This is a read-only property and cannot be set directly.

```python
@property
def dpi() -> Optional[Tuple[float, float]]
```

--------------------------------

### Get Monitor Dimensions as Rect (Python)

Source: https://github.com/kalmat/pymonctl/blob/master/docstrings.md

Retrieves the monitor's dimensions as a Rect struct, containing x, y, right, and bottom coordinates. This is a read-only property.

```python
@property
@abstractmethod
def rect() -> Optional[Rect]
```

--------------------------------

### Find Monitors at Point (Python)

Source: https://context7.com/kalmat/pymonctl/llms.txt

Identifies and returns a list of Monitor instances that contain the specified screen coordinates (x, y). This is useful for determining which monitor a particular point or the mouse cursor is currently located on.

```python
import pymonctl as pmc

# Find monitors at specific screen coordinates
x, y = 100, 200
monitors = pmc.findMonitorsAtPoint(x, y)

if monitors:
    for monitor in monitors:
        print(f"Point ({x}, {y}) is on monitor: {monitor.name}")
        print(f"  Monitor box: {monitor.box}")
else:
    print(f"No monitor found at point ({x}, {y})")

# Expected output:
# Point (100, 200) is on monitor: DELL U2415
#   Monitor box: Box(left=0, top=0, width=1920, height=1200)
```

--------------------------------

### Register Monitor Plug Listener (Python)

Source: https://github.com/kalmat/pymonctl/blob/master/docs/source/docstrings.md

Registers a callback function to be invoked when the number of connected monitors changes. The callback receives a list of changed screen names and a dictionary of all screen information. This is useful for multi-monitor setups where monitors can be dynamically plugged or unplugged.

```python
def plugListenerRegister(
        monitorCountChanged: Callable[[List[str], dict[str, ScreenValue]],
                                      None])

```

--------------------------------

### Get Monitors Count (Python)

Source: https://github.com/kalmat/pymonctl/blob/master/docs/source/docstrings.md

Returns the total number of monitors currently connected to the system. This function provides a simple integer count of active displays.

```python
def getMonitorsCount() -> int:
    # Implementation details...
    pass
```

--------------------------------

### Get Monitor Count (Python)

Source: https://context7.com/kalmat/pymonctl/llms.txt

Returns the total number of monitors currently connected to the system as an integer. This is a simple utility function to quickly ascertain the number of active displays.

```python
import pymonctl as pmc

count = pmc.getMonitorsCount()
print(f"Number of connected monitors: {count}")

# Expected output:
# Number of connected monitors: 2
```