Configuration

DisplayMonitor

OS:: 🪟 Windows 🍎 macOS

<DisplayMonitor preventIdle="enabled" debounceTime="5s">
  <Display name="DELL.*" preventIdle="always" />
  <DisplayBuiltIn preventIdle="never" />
</DisplayMonitor>

Without selectors, all external displays are watched. A configuration containing only DisplayBuiltIn selects only the built-in panel. An additional empty <Display /> selects all external displays.

preventIdle

default:: enabled

Controls whether external displays contribute activity during inspection:

enabled: active unless the display is known to be powered off.
always: active while connected, regardless of power state.
never: watch events without contributing activity.

true is an alias for always, and false for never. A display-level setting overrides the monitor default.

disabled

default:: false
OS:: 🍎 macOS

Holds selected displays disconnected in software. An external display can override this monitor-level default. On Windows, attempting to disable a display logs an unsupported-operation warning.

debounceTime

⏱️ duration:
default:: 5s

The grace period for a display to reconnect before its removal is treated as a disconnect. This avoids triggering disconnect actions for brief interruptions during mode changes or link negotiation.

onUsage

⚡️ event:

Triggered on every inspection that reports display activity. Periodic inspection requires timeout on SystemMonitor.

onIdle

⚡️ event:

Triggered when all monitored displays are idle.

Display

Selects external displays. All supplied criteria must match; an empty <Display /> matches every external display.

Connection and power events support delayed actions.

name

🔍 regex:

A regular expression matched against the display’s reported model name. * selects any name. This is a hardware model name, not a user-defined label for the rule.

vendor

The manufacturer code, for example DEL. Matched case-insensitively.

product

The numeric product code.

serial

The reported serial string or numeric serial written in decimal. Serial strings are matched case-insensitively.

resolution

The exact native resolution, for example 3840x2160. The current desktop resolution does not affect this criterion.

minWidth

The minimum native width in pixels.

minHeight

The minimum native height in pixels.

preventIdle

default:: inherited from DisplayMonitor

Controls whether this display contributes activity. Accepts the same values as the monitor-level setting.

disabled

default:: inherited from DisplayMonitor
OS:: 🍎 macOS

Holds this display disconnected in software while the configuration applies.

onConnect

⚡️ event:

Triggered when the display connects.

onDisconnect

⚡️ event:

Triggered when the display disconnects after the configured grace period.

onPowerOn

⚡️ event:

Triggered when the platform reports that the display is powered on.

onPowerOff

⚡️ event:

Triggered when the platform reports that the display is powered off.

DisplayBuiltIn

Selects the built-in panel. There are no name or hardware-selection attributes. Lid events support delayed actions; the opposite event cancels a pending action.

preventIdle

default:: never

Controls whether the built-in panel contributes activity. Accepts the same values as DisplayMonitor, but does not inherit its default.

disabled

default:: false
OS:: 🍎 macOS

Holds the built-in panel disconnected in software. Does not inherit the monitor-level setting.

onLidOpen

⚡️ event:

Triggered when the laptop lid opens.

onLidClose

⚡️ event:

Triggered when the laptop lid closes.