docs » SleepCorners

Trigger or prevent screen saver/sleep by moving your mouse pointer to specified hot corners on your screen.

While this functionality is provided by macOS in the Mission Control System Preferences, it doesn't provide any type of visual feedback so it's easy to forget which corners have been assigned which roles.

For best results while using this spoon, it is recommended that you disable "Start Screen Saver" and "Disable Screen Saver" if they are currently assigned to a corner with the Mission Control System Preferences Panel as this Spoon can't override them and may result in confusing or incorrect behavior.

The visual feed back provided by this spoon is of a small plus (for triggering sleep now) or a small minus (to prevent sleep) when the mouse pointer is moved into the appropriate corner. This feedback was inspired by a vague recollection of an early Mac screen saver (After Dark maybe?) which provided similar functionality. If someone knows for certain, please inform me and I will give appropriate attribution.

Note that sleep prevention is not guaranteed; macOS may override our attempts at staying awake in extreme situations (CPU temperature dangerously high, low battery, etc.) See hs.caffeinate for more details.

Download: https://github.com/Hammerspoon/Spoons/raw/master/Spoons/SleepCorners.spoon.zip

API Overview

API Documentation

Variables

feedbackSize
Signature SleepCorners.feedbackSize
Type Variable
Description Specifies the height and width in screen pixels, default 20, of the visual feedback to be displayed when the mouse pointer moves into one of the recognized hot corners
Source Source/SleepCorners.spoon/init.lua line 99
immediateSleepModifiers
Signature SleepCorners.immediateSleepModifiers
Type Variable
Description A table, default `{ fn = true }`, specifying keyboard modifiers which if held when the mouse pointer enters the sleep now hot corner will trigger sleep immediately rather then delay for [SleepCorners.sleepDelay](#sleepDelay) seconds.
Notes
  • This variable may be set to nil or an empty table, disabling the immediate sleep option, or a table containing one or more of the following keys:
  • fn - Set to true to require that the Fn key be pressed. May not be available on all keyboards, especially non-Apple ones.
  • cmd - Set to true to require that the Command (⌘) key be pressed
  • alt - Set to true to require that the Alt (or Option) (⌥) key be pressed
  • shift - Set to true to require that the Shift (⇧) key be pressed
  • ctrl - Set to true to require that the Control (^) key be pressed
  • If this table contains multiple keys, then all of the specified modifiers must be pressed for immediate sleep to take affect.
Source Source/SleepCorners.spoon/init.lua line 120
immediateSleepShouldLock
Signature SleepCorners.immediateSleepShouldLock
Type Variable
Description Specifies whether the sleep now corner, when the modifiers defined for [SleepCorners.immediateSleepModifiers](#immediateSleepModifiers) are also held, should trigger the display sleep or lock the users session. Defaults to true.
Notes
  • When this variable is set to true, triggering the sleep now corner for immediate sleep will lock the users session. When this variable is false, the display will be put to sleep instead.
  • Note that depending upon the user's settings in the Security & Privacy System Preferences, triggering the display sleep may also lock the user session immediately.
Source Source/SleepCorners.spoon/init.lua line 143
neverSleepCorner
Signature SleepCorners.neverSleepCorner
Type Variable
Description Specifies the location of the never sleep corner on the screen. Defaults to "LR".
Source Source/SleepCorners.spoon/init.lua line 86
neverSleepLockModifiers
Signature SleepCorners.neverSleepLockModifiers
Type Variable
Description A table, default `{ fn = true }`, specifying keyboard modifiers which if held when the mouse pointer enters the never sleep hot corner will disable display sleep and leave it disabled even if the mouse pointer leaves the hot corner. While the never sleep lock is in effect the never sleep visual feedback will remain visible in the appropriate corner of the screen. The never sleep lock may is unlocked when you move the mouse pointer back into the never sleep corner with the modifiers held down a second time or move the mouse pointer into the sleep now corner.
Notes
  • This variable may be set to nil or an empty table, disabling the never sleep lock option, or a table containing one or more of the following keys:
  • fn - Set to true to require that the Fn key be pressed. May not be available on all keyboards, especially non-Apple ones.
  • cmd - Set to true to require that the Command (⌘) key be pressed
  • alt - Set to true to require that the Alt (or Option) (⌥) key be pressed
  • shift - Set to true to require that the Shift (⇧) key be pressed
  • ctrl - Set to true to require that the Control (^) key be pressed
  • If this table contains multiple keys, then all of the specified modifiers must be pressed for the never sleep lock to be triggered.
Source Source/SleepCorners.spoon/init.lua line 152
preferSleepNow
Signature SleepCorners.preferSleepNow
Type Variable
Description Specifies which action should be preferred if both the sleep now and never sleep hot corners are assigned to the same location on the screen. The default is false.
Source Source/SleepCorners.spoon/init.lua line 111
sleepDelay
Signature SleepCorners.sleepDelay
Type Variable
Description Specifies the number of seconds, default 2, the mouse pointer must remain within the trigger area of the sleep now corner in order to put the system's display to sleep.
Source Source/SleepCorners.spoon/init.lua line 55
sleepNowCorner
Signature SleepCorners.sleepNowCorner
Type Variable
Description Specifies the location of the sleep now corner on the screen. Defaults to "LL".
Source Source/SleepCorners.spoon/init.lua line 73
sleepNowShouldLock
Signature SleepCorners.sleepNowShouldLock
Type Variable
Description Specifies whether the sleep now corner should trigger the display sleep or lock the users session. Defaults to false.
Notes
  • When this variable is set to true, triggering the sleep now corner will lock the users session. When this variable is false, the display will be put to sleep instead.
  • Note that depending upon the user's settings in the Security & Privacy System Preferences, triggering the display sleep may also lock the user session immediately.
Source Source/SleepCorners.spoon/init.lua line 134
sleepScreen
Signature SleepCorners.sleepScreen
Type Variable
Description Specifies the screen on which the sleep corners are made active. Defaults to the value returned by `hs.screen.primaryScreen()`.
Source Source/SleepCorners.spoon/init.lua line 62
triggerSize
Signature SleepCorners.triggerSize
Type Variable
Description Specifies the height and width in screen pixels, default 2, of the trigger area for the recognized hot corners.
Source Source/SleepCorners.spoon/init.lua line 104

Methods

bindHotkeys
Signature SleepCorners:bindHotkeys(mapping) -> self
Type Method
Description Binds hotkeys for SleepCorners
Parameters
  • mapping - A table containing hotkey modifier/key details for one or more of the following commands:
    • "start" - start monitoring the defined corners
    • "stop" - stop monitoring the defined corners
    • "toggle" - toggles monitoring on or off
    • "show" - shows the current corners for 3 seconds as a reminder of their assigned locations
Returns
  • the SleepCorners spoon object
Notes
  • the mapping table is a table of one or more key-value pairs of the format command = { { modifiers }, key } where:
    • command - is one of the commands listed above
    • modifiers - is a table containing keyboard modifiers, as specified in hs.hotkey.bind()
    • key - is a string containing the name of a keyboard key, as specified in hs.hotkey.bind()
Source Source/SleepCorners.spoon/init.lua line 632
isActive
Signature SleepCorners:isActive() -> boolean
Type Method
Description Returns whether or not the sleep corners are currently active
Parameters
  • None
Returns
  • true if the sleep corners are currently active or false if they are not
Notes
  • This method only identifies whether or not the SleepCorners spoon has been started; it does not check whether or not the specified corners have been set to a location of "*" with SleepCorners.sleepNowCorner or SleepCorners.neverSleepCorner.
  • If you want to check to see if SleepCorners has been started and that at least one of the corners is assigned to a corner, you should use something like SleepCorners:isActive() and (SleepCorners.sleepNowCorner ~= "*" or SleepCorners.neverSleepCorner ~= "*")
Source Source/SleepCorners.spoon/init.lua line 458
show
Signature SleepCorners:show([duration]) -> self
Type Method
Description Temporarily show the SleepCorner feedback images in their current locations as a reminder of their positions on the screen.
Parameters
  • duration - an optional number, default 3, specifying the number of seconds the feedback images should be displayed. If you specify false and the feedback images are currently being shown, the timer will be cur short and the images will be removed immediately.
Returns
  • the SleepCorners spoon object
Notes
  • this method will temporarily show the feedback images even if SleepCorners has been stopped (or has not yet been started).
Source Source/SleepCorners.spoon/init.lua line 580
start
Signature SleepCorners:start() -> self
Type Method
Description Starts monitoring the defined sleep corners to allow triggering or preventing the system display sleep state.
Parameters
  • None
Returns
  • the SleepCorners spoon object
Notes
  • has no effect if SleepCorners has already been started
Source Source/SleepCorners.spoon/init.lua line 478
stop
Signature SleepCorners:stop() -> self
Type Method
Description Stop monitoring the defined sleep corners.
Parameters
  • None
Returns
  • the SleepCorners spoon object
Notes
  • has no effect if SleepCorners has already been stopped
  • if SleepCorners was active, this method will return the display idle sleep setting back to its previous state and reset the never sleep lock if it has been triggered.
Source Source/SleepCorners.spoon/init.lua line 508
toggle
Signature SleepCorners:toggle([state]) -> self
Type Method
Description Toggles or sets whether or not SleepCorners is currently monitoring the defined screen corners for managing the system display's sleep state and displays an alert indicating the new state of the SleepCorners spoon.
Parameters
  • state - an optional boolean which specifies specifically whether SleepCorners should be started if it isn't already running (true) or stopped if it currently is running (false)
Returns
  • the SleepCorners spoon object
Notes
  • If state is not provided, this method will start SleepCorners if it is currently stopped or stop it if is currently started.
  • SleepCorners:toggle(true) is equivalent to SleepCorners:start() with the addition of displaying an alert specifying that SleepCorners is active.
  • SleepCorners:toggle(false) is equivalent to SleepCorners:stop() with the addition of displaying an alert specifying that SleepCorners has been deactivated.
Source Source/SleepCorners.spoon/init.lua line 544