HSScreen

Type

An object representing a single display attached to the system.

Coordinate system

All geometry is returned in Hammerspoon screen coordinates: the origin (0, 0) is at the top-left of the primary display, and y increases downward. This matches Hammerspoon v1 and is the inverse of the raw macOS/CoreGraphics convention.

Examples

const s = hs.screen.main();
console.log(s.name);               // e.g. "Built-in Retina Display"
console.log(s.frame.w);            // usable width in points

console.log(s.mode.width, s.mode.scale); // e.g. 1440, 2

s.desktopImage = "/Users/me/wallpaper.jpg";

Properties

id

number

Unique display identifier (matches `CGDirectDisplayID`).

Hammerspoon 2/Modules/hs.screen/HSScreen.swift:39

name

string

The manufacturer-assigned localized display name.

Hammerspoon 2/Modules/hs.screen/HSScreen.swift:42

uuid

string

The display's UUID string.

Hammerspoon 2/Modules/hs.screen/HSScreen.swift:45

frame

HSRect

The usable screen area in Hammerspoon coordinates, excluding the menu bar and Dock.

Hammerspoon 2/Modules/hs.screen/HSScreen.swift:50

fullFrame

HSRect

The full screen area in Hammerspoon coordinates, including menu bar and Dock regions.

Hammerspoon 2/Modules/hs.screen/HSScreen.swift:53

position

HSPoint

The screen's top-left corner in global Hammerspoon coordinates.

Hammerspoon 2/Modules/hs.screen/HSScreen.swift:56

mode

NSDictionary

The currently active display mode. An object with keys: `width`, `height`, `scale`, `frequency`.

Hammerspoon 2/Modules/hs.screen/HSScreen.swift:63

availableModes

NSDictionary[]

All display modes supported by this screen. Each element has keys: `width`, `height`, `scale`, `frequency`.

Hammerspoon 2/Modules/hs.screen/HSScreen.swift:68

rotation

number

The current screen rotation in degrees (0, 90, 180, or 270). Assign one of `0`, `90`, `180`, or `270` to rotate the display.

Hammerspoon 2/Modules/hs.screen/HSScreen.swift:87

desktopImage

string

The URL string of the current desktop background image for this screen, or `null`. Assign a new absolute file path or `file://` URL string to change the wallpaper.

Hammerspoon 2/Modules/hs.screen/HSScreen.swift:171

Methods

setMode(width, height, scale, frequency)

Switch to the given display mode. Pass `0` for `scale` or `frequency` to match any value.

Hammerspoon 2/Modules/hs.screen/HSScreen.swift:80

Parameters

  • width number

    Horizontal resolution in pixels.

  • height number

    Vertical resolution in pixels.

  • scale number

    Backing scale factor (e.g. `2` for HiDPI, `1` for non-HiDPI). Pass `0` to ignore.

  • frequency number

    Refresh rate in Hz. Pass `0` to ignore.

Returns

boolean - `true` on success.

snapshot()

Capture the current contents of this screen as an image. Requires **Screen Recording** permission.

Hammerspoon 2/Modules/hs.screen/HSScreen.swift:96

Parameters

None

Returns

Promise<HSImage> - Resolves with the captured image, or rejects if the capture fails (e.g. permission denied).

toEast()

The nearest screen whose left edge is at or beyond this screen's right edge, or `null`.

Hammerspoon 2/Modules/hs.screen/HSScreen.swift:110

Parameters

None

Returns

HSScreen - An HSScreen object

toWest()

The nearest screen whose right edge is at or before this screen's left edge, or `null`.

Hammerspoon 2/Modules/hs.screen/HSScreen.swift:114

Parameters

None

Returns

HSScreen - An HSScreen object

toNorth()

The nearest screen that is physically above this screen, or `null`.

Hammerspoon 2/Modules/hs.screen/HSScreen.swift:118

Parameters

None

Returns

HSScreen - An HSScreen object

toSouth()

The nearest screen that is physically below this screen, or `null`.

Hammerspoon 2/Modules/hs.screen/HSScreen.swift:122

Parameters

None

Returns

HSScreen - An HSScreen object

setOrigin(x, y)

Move this screen so its top-left corner is at the given position in global Hammerspoon coordinates.

Hammerspoon 2/Modules/hs.screen/HSScreen.swift:132

Parameters

  • x number

    The X coordinate to move to

  • y number

    The Y coordinate to move to

Returns

boolean - `true` on success.

setPrimary()

Designate this screen as the primary display (moves the menu bar here).

Hammerspoon 2/Modules/hs.screen/HSScreen.swift:137

Parameters

None

Returns

boolean - `true` on success.

mirrorOf(screen)

Configure this screen to mirror another screen.

Hammerspoon 2/Modules/hs.screen/HSScreen.swift:143

Parameters

  • screen HSScreen

    The screen to mirror.

Returns

boolean - `true` on success.

mirrorStop()

Stop mirroring, restoring this screen to an independent display.

Hammerspoon 2/Modules/hs.screen/HSScreen.swift:148

Parameters

None

Returns

boolean - `true` on success.

absoluteToLocal(rect)

Convert a rect in global Hammerspoon coordinates to coordinates local to this screen. The result origin is relative to this screen's top-left corner.

Hammerspoon 2/Modules/hs.screen/HSScreen.swift:158

Parameters

  • rect JSValue

    An `HSRect` in global Hammerspoon coordinates.

Returns

HSRect - The rect offset to be relative to this screen's top-left, or `null` if the input is invalid.

localToAbsolute(rect)

Convert a rect in local screen coordinates to global Hammerspoon coordinates.

Hammerspoon 2/Modules/hs.screen/HSScreen.swift:164

Parameters

  • rect JSValue

    An `HSRect` relative to this screen's top-left corner.

Returns

HSRect - The rect in global Hammerspoon coordinates, or `null` if the input is invalid.