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
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 (viastring.match) the screen name as perhs.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 perhs.screen:position()an hs.geometry size object, or constructor argument, with the resolution of the screen as perhs.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
- one or more hs.screen objects that match the supplied search criterion, or
nilif none found
- 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>
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
- 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
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
- A boolean, true if the gamma settings were applied, false if an error occurred
- 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