hammerspoon2-docs
    Preparing search index...

    Class HSScreen

    An object representing a single display attached to the 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.

    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";
    Index

    Constructors

    constructor

    Properties

    ambientLight availableModes desktopImage frame fullFrame id mode name position rotation uuid

    Methods

    absoluteToLocal localToAbsolute mirrorOf mirrorStop next previous setMode setOrigin setPrimary snapshot toEast toNorth toSouth toWest

    Constructors

    Properties

    ambientLight: number | null

    The ambient light level measured by this display's built-in sensor, in lux. Returns null if the display does not have an ambient light sensor or if the reading is currently unavailable.

    availableModes: Record<string, any>[]

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

    desktopImage: string | null

    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.

    frame: HSRect

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

    fullFrame: HSRect

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

    id: number

    Unique display identifier (matches CGDirectDisplayID).

    mode: Record<string, any>

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

    name: string

    The manufacturer-assigned localized display name.

    position: HSPoint

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

    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.

    uuid: string

    The display's UUID string.

    Methods

    • 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.

      Parameters

      • rect: HSRect

        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.

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

      Parameters

      • rect: HSRect

        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.

      This uses private macOS APIs to set rotation.

    • Configure this screen to mirror another screen.

      Parameters

      Returns boolean

      true on success.

    • Stop mirroring, restoring this screen to an independent display.

      Returns boolean

      true on success.

    • The next screen in hs.screen.all() order, wrapping around.

      Returns HSScreen

      An HSScreen object

    • The previous screen in hs.screen.all() order, wrapping around.

      Returns HSScreen

      An HSScreen object

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

      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.

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

      Parameters

      • x: number

        The X coordinate to move to

      • y: number

        The Y coordinate to move to

      Returns boolean

      true on success.

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

      Returns boolean

      true on success.

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

      Returns Promise<HSImage>

      Resolves with the captured image, or rejects if the capture fails (e.g. permission denied).

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

      Returns HSScreen | null

      An HSScreen object

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

      Returns HSScreen | null

      An HSScreen object

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

      Returns HSScreen | null

      An HSScreen object

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

      Returns HSScreen | null

      An HSScreen object

    Settings

    Member Visibility

    On This Page

    Coordinate systemExamples
    Constructors
    Properties
    Methods