# hs.screen

Manipulate screens (i.e. monitors)

The macOS coordinate system used by Hammerspoon assumes a grid that spans all the screens (positioned as per System Preferences->Displays->Arrangement). The origin 0,0 is at the top left corner of the primary screen. (Screens to the left of the primary screen, or above it, and windows on these screens, will have negative coordinates)

---

# Submodules

• hs.screen.watcher

---

# API Overview

Variables - Configurable values

• strictScreenInDirection

Functions - API calls offered directly by the extension

• accessibilitySettings
• find
• restoreGamma
• screenPositions

Constructors - API calls which return an object, typically one that offers API methods

• allScreens
• mainScreen
• primaryScreen

Methods - API calls which can only be made on an object returned by a constructor

• absoluteToLocal
• availableModes
• currentMode
• desktopImageURL
• frame
• fromUnitRect
• fullFrame
• getBrightness
• getForceToGray
• getGamma
• getInfo
• getInvertedPolarity
• getUUID
• id
• localToAbsolute
• mirrorOf
• mirrorStop
• name
• next
• position
• previous
• rotate
• setBrightness
• setForceToGray
• setGamma
• setInvertedPolarity
• setMode
• setOrigin
• setPrimary
• shotAsJPG
• shotAsPNG
• snapshot
• toEast
• toNorth
• toSouth
• toUnitRect
• toWest

---

# API Documentation

# Variables

# strictScreenInDirection

---

# Functions

# accessibilitySettings

---

# find

| | | | --------------------------------------------|-------------------------------------------------------------------------------------| | Signature | hs.screen.find(hint) -> hs.screen object(s) | | Type | Function | | Description | Finds screens | | Parameters |

• hint - search criterion for the desired screen(s); it can be: a number as per hs.screen:id() a string containing the UUID of the desired screen a string pattern that matches (via string.match) the screen name as per hs.screen:name() (for convenience, the matching will be done on lowercased strings) an hs.geometry point object, or constructor argument, with the x and y position of the screen in the current layout as per hs.screen:position() an hs.geometry size object, or constructor argument, with the resolution of the screen as per hs.screen:fullFrame() an hs.geometry rect object, or constructor argument, with an arbitrary rect in absolute coordinates; the screen containing the largest part of the rect will be returned

| | Returns |

• one or more hs.screen objects that match the supplied search criterion, or nil if none found

| | Notes |

• for convenience you call this as hs.screen(hint)
• Example:
• lua</li><li>hs.screen(724562417) --> Color LCD - by id</li><li>hs.screen'Dell' --> DELL U2414M - by name</li><li>hs.screen'Built%-in' --> Built-in Retina Display, note the % to escape the hyphen repetition character</li><li>hs.screen'0,0' --> PHL BDM4065 - by position, same as hs.screen.primaryScreen()</li><li>hs.screen{x=-1,y=0} --> DELL U2414M - by position, screen to the immediate left of the primary screen</li><li>hs.screen'3840x2160' --> PHL BDM4065 - by screen resolution</li><li>hs.screen'-500,240 700x1300' --> DELL U2414M, by arbitrary rect</li><li>

| | Examples | None | | Source | extensions/screen/screen.lua line 43 |

---

# restoreGamma

---

# screenPositions

---

# Constructors

# allScreens

---

# mainScreen

---

# primaryScreen

---

# Methods

# absoluteToLocal

---

# availableModes

---

# currentMode

---

# desktopImageURL

---

# frame

---

# fromUnitRect

---

# fullFrame

---

# getBrightness

---

# getForceToGray

---

# getGamma

---

# getInfo

---

# getInvertedPolarity

---

# getUUID

---

# id

---

# localToAbsolute

---

# mirrorOf

---

# mirrorStop

---

# name

---

# next

---

# position

---

# previous

---

# rotate

| | | | --------------------------------------------|-------------------------------------------------------------------------------------| | Signature | hs.screen:rotate([degrees]) -> bool or rotation angle | | Type | Method | | Description | Gets/Sets the rotation of a screen | | Parameters |

• degrees - An optional number indicating how many degrees clockwise, to rotate. If no number is provided, the current rotation will be returned. This number must be one of: 0 90 180 270

| | Returns |

• If the rotation is being set, a boolean, true if the operation succeeded, otherwise false. If the rotation is being queried, a number will be returned

| | Notes | None | | Examples | None | | Source | extensions/screen/libscreen.m line 1023 |

---

# setBrightness

---

# setForceToGray

---

# setGamma

| | | | --------------------------------------------|-------------------------------------------------------------------------------------| | Signature | hs.screen:setGamma(whitepoint, blackpoint) -> boolean | | Type | Method | | Description | Sets the current white point and black point of the screen | | Parameters |

• whitepoint - A table containing color component values between 0.0 and 1.0 for each of the keys: red green blue
• blackpoint - A table containing color component values between 0.0 and 1.0 for each of the keys: red green blue

| | Returns |

• A boolean, true if the gamma settings were applied, false if an error occurred

| | Notes |

• If the whitepoint and blackpoint specified, are very similar, it will be impossible to read the screen. You should exercise caution, and may wish to bind a hotkey to hs.screen.restoreGamma() when experimenting

| | Examples | None | | Source | extensions/screen/libscreen.m line 512 |

---

# setInvertedPolarity

---

# setMode

---

# setOrigin

---

# setPrimary

---

# shotAsJPG

---

# shotAsPNG

---

# snapshot

---

# toEast

---

# toNorth

---

# toSouth

---

# toUnitRect

---

# toWest

---

---