app.screen - Screen & Appearance API

Screen information, appearance mode, brightness control, screenshots, and color picking.

Screen Information

app.screen.list()

Get all connected displays.

Returns: array<table> - each item contains:

• id (number) - display ID
• name (string) - display name
• width (number) - width (points)
• height (number) - height (points)
• scaleFactor (number) - scale factor (2.0 for Retina)
• isMain (boolean) - whether this is the main display
• isBuiltIn (boolean) - whether this is the built-in display

local screens = app.screen.list()
for _, s in ipairs(screens) do
    app.log.info(s.name .. ": " .. s.width .. "x" .. s.height)
end

app.screen.mainScreen()

Get main display information.

Returns: table - contains the following fields:

• id (number) - display ID
• name (string) - display name
• width (number) - width (points)
• height (number) - height (points)
• scaleFactor (number) - scale factor (2.0 for Retina)

Note: Unlike list(), mainScreen() does not include isMain and isBuiltIn fields.

local main = app.screen.mainScreen()
app.log.info("Main screen: " .. main.width .. "x" .. main.height .. " @" .. main.scaleFactor .. "x")

Appearance

app.screen.isDarkMode()

Check if dark mode is enabled.

Returns: boolean

if app.screen.isDarkMode() then
    app.log.info("Dark mode")
end

app.screen.setDarkMode(enabled)

Set dark mode.

Parameters:

• enabled (boolean) - whether to enable

Returns: boolean, error

app.screen.setDarkMode(true)   -- Enable dark mode
app.screen.setDarkMode(false)  -- Enable light mode

app.screen.accentColor()

Get the system accent color.

Returns: string - "red", "orange", "yellow", "green", "blue", "purple", "pink", "graphite"

local color = app.screen.accentColor()  -- "blue"

Brightness

app.screen.brightness()

Get the built-in display brightness.

Returns: number|nil, error - 0.0 to 1.0

local brightness = app.screen.brightness()
if brightness then
    app.log.info("Brightness: " .. math.floor(brightness * 100) .. "%")
end

app.screen.setBrightness(value)

Set the built-in display brightness.

Parameters:

• value (number) - brightness value (0.0-1.0, automatically clamped)

Returns: boolean, error

app.screen.setBrightness(0.8)  -- Set to 80%

Screenshots & Color Picking

app.screen.capture(path, options?)

Capture the screen and save as an image.

Parameters:

• path (string) - save path
• options (table, optional):
  • displayId (number) - specific display ID

Returns: boolean, error

-- Capture main screen
app.screen.capture("/tmp/screenshot.png")

-- Capture specific display
app.screen.capture("/tmp/ext_screen.jpg", {displayId = 2})

app.screen.colorPicker()

Open the system color picker (requires macOS 10.15+).

Returns: table|nil, error

• hex (string) - “#RRGGBB” format
• r, g, b (number) - 0-255
• a (number) - 0.0-1.0

Returns nil if the user cancels.

local color = app.screen.colorPicker()
if color then
    app.log.info("Color: " .. color.hex)
    app.clipboard.setText(color.hex)
end

Event Watching

app.screen.watch(event, callback)

Watch for screen and appearance change events.

Parameters:

• event (string) - event name:
  • "darkModeChanged" - fired when dark/light mode switches, callback receives: {isDarkMode}
  • "displayChanged" - fired when display configuration changes (connect/disconnect/resolution change), callback receives: {displays}
• callback (function) - callback function:
  • darkModeChanged event: receives {isDarkMode (boolean)}
  • displayChanged event: receives {displays (array)} — same format as app.screen.list() return value

Returns: string, error - watcher handle ID

app.screen.watch("darkModeChanged", function(e)
    if e.isDarkMode then
        app.log.info("Switched to dark mode")
    else
        app.log.info("Switched to light mode")
    end
end)

app.screen.watch("displayChanged", function(e)
    app.log.info("Display configuration changed, displays: " .. #e.displays)
end)

app.screen.stopAllWatchers()

Stop all screen event watchers registered by the current plugin.

Returns: boolean

app.screen.stopAllWatchers()

app.screen.listWatchers()

List all screen event watchers registered by the current plugin.

Returns: array<table> - each item contains:

• id (string) - watcher handle ID
• event (string) - event name being watched

local watchers = app.screen.listWatchers()
for _, w in ipairs(watchers) do
    app.log.info(w.id .. " -> " .. w.event)
end

Examples

Toggle Dark Mode

function MyPlugin:handleToggleDarkMode(context)
    local isDark = app.screen.isDarkMode()
    local ok, err = app.screen.setDarkMode(not isDark)
    if ok then
        app.notification.show("Appearance", isDark and "Switched to light mode" or "Switched to dark mode")
    end
end