Monitor Functions and Object

Functions for retrieving screen resolution and multi-monitor info. Click on a function name for details. The Keysharp-specific Monitor object below adds display identity, metadata, brightness control and change notifications.

Monitor Object

class Monitor extends Object

Represents one display. This class is exported by the KS module:

#Import "Ks" { Monitor }

Note: This class is experimental: it and its nested types may change or be removed without deprecation. See #Warn Experimental.

Snapshot semantics

Identity and geometry are read when a Monitor is created; call Refresh to re-read them. Other metadata, such as Model or RefreshRate, is read when first used and then kept. Brightness and the VCP methods query the device on every call. A property the display does not report is the empty string.

Obtaining a Monitor

M := Monitor(N)
M := Monitor.Primary
M := Monitor.FromPoint(X, Y)
M := Monitor.FromMouse()
M := Monitor.FromWindow(WinTitle, WinText, ExcludeTitle, ExcludeText)
M := Monitor.FromId(Id)
Monitors := Monitor.All
Count := Monitor.Count

Identity

Note: For a monitor which reports no serial number, Id identifies the port it is plugged into, not the panel; on macOS, it identifies the model, so identical displays share one Id. Id is the empty string when the display exposes no usable identity.

Geometry

Note: Scale is not a screen-coordinate conversion factor and must never be applied to absolute positions.

Brightness and DDC/CI

Percent := M.Brightness
M.Brightness := Percent
Supported := M.IsBrightnessSupported
Feature := M.GetVCP(Code)
M.SetVCP(Code, Value)

Over DDC/CI, each read or assignment of Brightness takes tens of milliseconds. On a monitor or platform which does not support it, Brightness throws an OSError naming the reason; reading IsBrightnessSupported performs one brightness read to test this without an exception.

VCP codes are defined by the MCCS standard, for example 0x10 brightness, 0x12 contrast, 0x60 input source, 0x62 speaker volume and 0xD6 power mode.

SetVCP reads the feature before writing it, so each call performs two device transactions.

Warning: SetVCP drives the monitor's firmware directly. Setting an input-source or power code will switch the monitor away from this computer, and some displays react badly to codes they document but mishandle. Verify a code against the monitor's own MCCS documentation first.

Display change notifications

Hook := Monitor.OnChange(Callback)
Hooks := Monitor.Hooks

Calls Callback whenever the display configuration changes, and returns a running MonitorHook controlling the subscription.

Callback is a function object which receives (Hook, Change):

To inspect the new layout, read Monitor.Count or Monitor.All in the callback, or call Refresh on a Monitor obtained earlier.

The callback is not called for a notification which changed nothing observable.

The returned hook is an EventHook. Monitor.Hooks is an Array of the running hooks. A MonitorHook does not keep the script running, so a script which only waits for display changes calls Persistent.

Remarks

The built-in variables A_ScreenWidth and A_ScreenHeight contain the dimensions of the primary monitor, in pixels.

SysGet can be used to retrieve the bounding rectangle of all display monitors. For example, this retrieves the width and height of the virtual screen:

MsgBox SysGet(78) " x " SysGet(79)

Geometry, Name, Index and the factories work on every platform. What varies is metadata and device control.

Windows

Brightness works on the built-in panel and on external monitors which support DDC/CI.

Linux

New queries refresh display geometry and scale after display changes; existing Monitor objects retain their snapshot semantics. Work-area queries account for panels and docks independently of display-layout changes.

On X11, geometry, refresh rate and orientation are read through keysharp-desktop. On Wayland, RefreshRate and Orientation are the empty string and 0 if the native compositor connection is unavailable. Adapter is the DRM driver name, such as amdgpu or i915.

For external monitors, Brightness and the VCP methods need the i2c-dev kernel module and access to the i2c bus. A root install adds a udev rule granting the local-seat user access to display-controller i2c buses, and ddcutil's own rule also works; without either, they throw an OSError naming the requirement. OnChange works on X11 and every Wayland compositor.

macOS

Model and Adapter are always the empty string, and Connection distinguishes only built-in from external. RefreshRate is the empty string on some built-in panels.

Brightness works on the built-in panel, Apple displays and other external monitors which support DDC/CI. The VCP methods work only on external DDC/CI monitors.

Note: DDC/CI on Intel Macs is unverified. Some USB-C hubs and docks do not carry the DDC channel through to the monitor, in which case Brightness and the VCP methods throw an OSError for a display that would otherwise support them.

Related

DllCall, Win functions, SysGet, EventHook

Examples

MonitorCount := MonitorGetCount()
MonitorPrimary := MonitorGetPrimary()
MsgBox "Monitor Count:`t" MonitorCount "`nPrimary Monitor:`t" MonitorPrimary
Loop MonitorCount
{
    MonitorGet A_Index, &L, &T, &R, &B
    MonitorGetWorkArea A_Index, &WL, &WT, &WR, &WB
    MsgBox
    (
        "Monitor:`t#" A_Index "
        Name:`t" MonitorGetName(A_Index) "
        Left:`t" L " (" WL " work)
        Top:`t" T " (" WT " work)
        Right:`t" R " (" WR " work)
        Bottom:`t" B " (" WB " work)"
    )
}

#Import "Ks" { Monitor }

for M in Monitor.All
{
    Info := "Monitor:`t#" M.Index (M.IsPrimary ? " (primary)" : "") "`n"
    Info .= "Name:`t" M.Name "`n"
    Info .= "Model:`t" M.Manufacturer " " M.Model "`n"
    Info .= "Size:`t" M.Width "x" M.Height " at " (M.Scale * 100) "%`n"
    Info .= "Refresh:`t" M.RefreshRate "`n"
    Info .= "Id:`t" M.Id
    MsgBox Info
}

#Import "Ks" { Monitor }

for M in Monitor.All
    if (M.IsBrightnessSupported)
        M.Brightness := Max(0, M.Brightness - 20)

#Import "Ks" { Monitor }

Hook := Monitor.OnChange(DisplaysChanged)
Persistent

DisplaysChanged(Hook, Change)
{
    if (Change = "Topology")
        ToolTip "Monitors attached or removed: now " Monitor.Count
    else
        ToolTip "Display settings changed"

    SetTimer () => ToolTip(), -3000
}

#Import "Ks" { Monitor }

Id := Monitor.FromWindow("A").Id
IniWrite Id, "layout.ini", "Editor", "Monitor"

; ... on a later run:
Saved := IniRead("layout.ini", "Editor", "Monitor", "")
M := Monitor.FromId(Saved)

if (M)
    MsgBox "That display is attached, as monitor #" M.Index
else
    MsgBox "That display is not currently attached."