This module provides some basic functions for controlling macOS Spaces.
The functionality provided by this module is considered experimental and subject to change. By using a combination of private APIs and Accessibility hacks (via hs.axuielement), some basic functions for controlling the use of Spaces is possible with Hammerspoon, but there are some limitations and caveats.
It should be noted that while the functions provided by this module have worked for some time in third party applications and in a previous experimental module that has received limited testing over the last few years, they do utilize some private APIs which means that Apple could change them at any time.
The functions which allow you to create new spaes, remove spaces, and jump to a specific space utilize hs.axuielement
and perform accessibility actions through the Dock application to manipulate Mission Control. Because we are essentially directing the Dock to perform User Interactions, there is some visual feedback which we cannot entirely suppress. You can minimize, but not entirely remove, this by enabling "Reduce motion" in System Preferences -> Accessibility -> Display.
It is recommended that you also enable "Displays have separate Spaces" in System Preferences -> Mission Control.
This module is a distillation of my previous hs._asm.undocumented.spaces
module, changes inspired by reviewing the Yabai
source, and some experimentation with hs.axuielement
. If you require more sophisticated control, I encourage you to check out https://github.com/koekeishiya/yabai -- it does require some additional setup (changes to SIP, possibly edits to sudoers
, etc.) but may be worth the extra steps for some power users.
Signature | hs.spaces.MCwaitTime |
---|---|
Type | Variable |
Description | Specifies how long to delay before performing the accessibility actions for hs.spaces.gotoSpace and hs.spaces.removeSpace |
Notes |
|
Source | extensions/spaces/spaces.lua line 215 |
Signature | hs.spaces.activeSpaceOnScreen([screen]) -> integer | nil, error |
---|---|
Type | Function |
Description | Returns the currently visible (active) space for the specified screen. |
Parameters |
|
Returns |
|
Source | extensions/spaces/spaces.lua line 425 |
Signature | hs.spaces.activeSpaces() -> table | nil, error |
---|---|
Type | Function |
Description | Returns a key-value table specifying the active spaces for all screens. |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/spaces/spaces.lua line 488 |
Signature | hs.spaces.addSpaceToScreen([screen], [closeMC]) -> true | nil, errMsg |
---|---|
Type | Function |
Description | Adds a new space on the specified screen |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/spaces/spaces.lua line 686 |
Signature | hs.spaces.allSpaces() -> table | nil, error |
---|---|
Type | Function |
Description | Returns a Kay-Value table containing the IDs of all spaces for all screens. |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/spaces/spaces.lua line 396 |
Signature | hs.spaces.closeMissionControl() -> None |
---|---|
Type | Function |
Description | Opens the Mission Control display |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/spaces/spaces.lua line 315 |
Signature | hs.spaces.data_managedDisplaySpaces() -> table | nil, error |
---|---|
Type | Function |
Description | Returns a table containing information about the managed display spaces |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/spaces/libspaces.m line 33 |
Signature | hs.spaces.data_missionControlAXUIElementData(callback) -> None |
---|---|
Type | Function |
Description | Generate a table containing the results of |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/spaces/spaces.lua line 174 |
Signature | hs.spaces.focusedSpace() -> integer |
---|---|
Type | Function |
Description | Returns the space ID of the currently focused space |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/spaces/libspaces.m line 61 |
Signature | hs.spaces.gotoSpace(spaceID) -> true | nil, errMsg |
---|---|
Type | Function |
Description | Change to the specified space. |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/spaces/spaces.lua line 751 |
Signature | hs.spaces.missionControlSpaceNames([closeMC]) -> table | nil, error |
---|---|
Type | Function |
Description | Returns a table containing the space names as they appear in Mission Control associated with their space ID. This is provided for informational purposes only -- all of the functions of this module use the spaceID to insure accuracy. |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/spaces/spaces.lua line 632 |
Signature | hs.spaces.moveWindowToSpace(window, spaceID[, force]) -> true | nil, error |
---|---|
Type | Function |
Description | Moves the window with the specified windowID to the space specified by spaceID. |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/spaces/libspaces.m line 134 |
Signature | hs.spaces.openMissionControl() -> None |
---|---|
Type | Function |
Description | Opens the Mission Control display |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/spaces/spaces.lua line 299 |
Signature | hs.spaces.removeSpace(spaceID, [closeMC]) -> true | nil, errMsg |
---|---|
Type | Function |
Description | Removes the specified space. |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/spaces/spaces.lua line 811 |
Signature | hs.spaces.screensHaveSeparateSpaces() -> bool |
---|---|
Type | Function |
Description | Determine if the user has enabled the "Displays Have Separate Spaces" option within Mission Control. |
Parameters |
|
Returns |
|
Source | extensions/spaces/libspaces.m line 17 |
Signature | hs.spaces.setDefaultMCwaitTime([time]) -> None |
---|---|
Type | Function |
Description | Sets the initial value for hs.spaces.MCwaitTime to be set to when this module first loads. |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/spaces/spaces.lua line 225 |
Signature | hs.spaces.spaceDisplay(spaceID) -> string | nil, error |
---|---|
Type | Function |
Description | Returns the screen UUID for the screen that the specified space is on. |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/spaces/spaces.lua line 517 |
Signature | hs.spaces.spacesForScreen([screen]) -> table | nil, error |
---|---|
Type | Function |
Description | Returns a table containing the IDs of the spaces for the specified screen in their current order. |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/spaces/spaces.lua line 331 |
Signature | hs.spaces.spaceType(spaceID) -> string | nil, error |
---|---|
Type | Function |
Description | Returns a string indicating whether the space is a user space or a full screen/tiled application space. |
Parameters |
|
Returns |
|
Source | extensions/spaces/spaces.lua line 550 |
Signature | hs.spaces.toggleAppExpose() -> None |
---|---|
Type | Function |
Description | Toggles the current applications Exposé display |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/spaces/spaces.lua line 271 |
Signature | hs.spaces.toggleLaunchPad() -> None |
---|---|
Type | Function |
Description | Toggles the Launch Pad display. |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/spaces/spaces.lua line 285 |
Signature | hs.spaces.toggleMissionControl() -> None |
---|---|
Type | Function |
Description | Toggles the Mission Control display |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/spaces/spaces.lua line 257 |
Signature | hs.spaces.toggleShowDesktop() -> None |
---|---|
Type | Function |
Description | Toggles moving all windows on/off screen to display the desktop underneath. |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/spaces/spaces.lua line 243 |
Signature | hs.spaces.windowsForSpace(spaceID) -> table | nil, error |
---|---|
Type | Function |
Description | Returns a table containing the window IDs of all windows on the specified space |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/spaces/libspaces.m line 80 |
Signature | hs.spaces.windowSpaces(window) -> table | nil, error |
---|---|
Type | Function |
Description | Returns a table containing the space IDs for all spaces that the specified window is on. |
Parameters |
|
Returns |
|
Notes |
|
Source | extensions/spaces/libspaces.m line 186 |