Getting Started
Contributing
Control CommandPost
Plugins
Internationalisation
CommandPost API
Bundled Plugins API
Hammerspoon API
window
Inspect/manipulate windows
Notes:
- See
hs.screenandhs.geometryfor more information on how Hammerspoon uses window/screen frames and coordinates
Submodules
API Overview
- Variables - Configurable values
- Functions - API calls offered directly by the extension
- Constructors - API calls which return an object, typically one that offers API methods
- Methods - API calls which can only be made on an object returned by a constructor
API Documentation
Variables
Signature
hs.window.animationDuration (number)Type
Variable
Description
The default duration for animations, in seconds. Initial value is 0.2; set to 0 to disable animations.
Signature
hs.window.setFrameCorrectnessType
Variable
Description
Using
hs.window:setFrame() in some cases does not work as expected: namely, the bottom (or Dock) edge, and edges between screens, mightFunctions
Signature
hs.window.allWindows() -> list of hs.window objectsType
Function
Description
Returns all windows
Parameters
- None
Returns
- A list of
hs.windowobjects representing all open windows
Notes
visibleWindows(),orderedWindows(),get(),find(), and several more functions and methods in this and other modules make use of this function, so it is important to understand its limitations- This function queries all applications for their windows every time it is invoked; if you need to call it a lot and performance is not acceptable consider using the
hs.window.filtermodule - This function can only return windows in the current Mission Control Space; if you need to address windows across different Spaces you can use the
hs.window.filtermodule - if
Displays have separate Spacesis on (in System Preferences>Mission Control) the current Space is defined as the union of all currently visible Spaces - minimized windows and hidden windows (i.e. belonging to hidden apps, e.g. via cmd-h) are always considered to be in the current Space
- This function filters out the desktop "window"; use
hs.window.desktop()to address it. (Note however thaths.application.get'Finder':allWindows()will include the desktop in the returned list) - Beside the limitations discussed above, this function will return all windows as reported by OSX, including some "windows" that one wouldn't expect: for example, every Google Chrome (actual) window has a companion window for its status bar; therefore you might get unexpected results - in the Chrome example, calling
hs.window.focusWindowSouth()from a Chrome window would end up "focusing" its status bar, and therefore the proper window itself, seemingly resulting in a no-op. In order to avoid such surprises you can use thehs.window.filtermodule, and more specifically the default windowfilter (hs.window.filter.default) which filters out known cases of not-actual-windows - Some windows will not be reported by OSX - e.g. things that are on different Spaces, or things that are Full Screen
Signature
hs.window.desktop() -> hs.window objectType
Function
Description
Returns the desktop "window"
Parameters
- None
Returns
- An
hs.windowobject representing the desktop, or nil if Finder is not running
Notes
- The desktop belongs to Finder.app: when Finder is the active application, you can focus the desktop by cycling through windows via cmd-`
- The desktop window has no id, a role of
AXScrollAreaand no subrole - The desktop is filtered out from
hs.window.allWindows()(and downstream uses)
Signature
hs.window.invisibleWindows() -> list of hs.window objectsType
Function
Description
Gets all invisible windows
Parameters
- None
Returns
- A list containing
hs.windowobjects representing all windows that are not visible as perhs.window:isVisible()
Signature
hs.window.list(allWindows) -> tableType
Function
Description
Gets a table containing all the window data retrieved from
CGWindowListCreate.Parameters
- allWindows - Get all the windows, even those "below" the Dock window.
Returns
trueis succesful otherwisefalseif an error occured.
Notes
- This allows you to get window information without Accessibility Permissions.
Signature
hs.window.minimizedWindows() -> list of hs.window objectsType
Function
Description
Gets all minimized windows
Parameters
- None
Returns
- A list containing
hs.windowobjects representing all windows that are minimized as perhs.window:isMinimized()
Signature
hs.window.orderedWindows() -> list of hs.window objectsType
Function
Description
Returns all visible windows, ordered from front to back
Parameters
- None
Returns
- A list of
hs.windowobjects representing all visible windows, ordered from front to back
Signature
hs.window.setShadows(shadows)Type
Function
Description
Enables/Disables window shadows
Parameters
- shadows - A boolean, true to show window shadows, false to hide window shadows
Returns
- None
Notes
- This function uses a private, undocumented OS X API call, so it is not guaranteed to work in any future OS X release
Signature
hs.window.snapshotForID(ID [, keepTransparency]) -> hs.image-objectType
Function
Description
Returns a snapshot of the window specified by the ID as an
hs.image objectParameters
- ID - Window ID of the window to take a snapshot of.
- keepTransparency - optional boolean value indicating if the windows alpha value (transparency) should be maintained in the resulting image or if it should be fully opaque (default).
Returns
hs.imageobject of the window snapshot or nil if unable to create a snapshot
Notes
- See also method
hs.window:snapshot() - Because the window ID cannot always be dynamically determined, this function will allow you to provide the ID of a window that was cached earlier.
Signature
hs.window.timeout(value) -> booleanType
Function
Description
Sets the timeout value used in the accessibility API.
Parameters
- value - The number of seconds for the new timeout value.
Returns
trueis succesful otherwisefalseif an error occured.
Signature
hs.window.visibleWindows() -> list of hs.window objectsType
Function
Description
Gets all visible windows
Parameters
- None
Returns
- A list containing
hs.windowobjects representing all windows that are visible as perhs.window:isVisible()
Constructors
Signature
hs.window.find(hint) -> hs.window object(s)Type
Constructor
Description
Finds windows
Parameters
- hint - search criterion for the desired window(s); it can be:
- an id number as per
hs.window:id() - a string pattern that matches (via
string.find) the window title as perhs.window:title()(for convenience, the matching will be done on lowercased strings)
Returns
- one or more hs.window objects that match the supplied search criterion, or
nilif none found
Notes
- for convenience you can call this as
hs.window(hint) - see also
hs.window.get - for more sophisticated use cases and/or for better performance if you call this a lot, consider using
hs.window.filter
Signature
hs.window.focusedWindow() -> windowType
Constructor
Description
Returns the window that has keyboard/mouse focus
Parameters
- None
Returns
- An
hs.windowobject representing the currently focused window
Signature
hs.window.frontmostWindow() -> hs.window objectType
Constructor
Description
Returns the focused window or, if no window has focus, the frontmost one
Parameters
- None
Returns
- An
hs.windowobject representing the frontmost window, ornilif there are no visible windows
Signature
hs.window.get(hint) -> hs.window objectType
Constructor
Description
Gets a specific window
Parameters
- hint - search criterion for the desired window; it can be:
- an id number as per
hs.window:id() - a window title string as per
hs.window:title()
Returns
- the first hs.window object that matches the supplied search criterion, or
nilif not found
Notes
- see also
hs.window.findandhs.application:getWindow()
Methods
Signature
hs.window:application() -> app or nilType
Method
Description
Gets the
hs.application object the window belongs toParameters
- None
Returns
- An
hs.applicationobject representing the application that owns the window, or nil if an error occurred
Signature
hs.window:becomeMain() -> windowType
Method
Description
Makes the window the main window of its application
Parameters
- None
Returns
- The
hs.windowobject
Notes
- Make a window become the main window does not transfer focus to the application. See
hs.window.focus()
Signature
hs.window:centerOnScreen([screen][, ensureInScreenBounds][, duration]) --> hs.window objectType
Method
Description
Centers the window on a screen
Parameters
- screen - (optional) An
hs.screenobject or argument forhs.screen.find; if nil, use the screen the window is currently on - ensureInScreenBounds - (optional) if
true, usesetFrameInScreenBounds()to ensure the resulting window frame is fully contained within the window's screen - duration - (optional) The number of seconds to animate the transition. Defaults to the value of
hs.window.animationDuration
Returns
- The
hs.windowobject
Signature
hs.window:close() -> boolType
Method
Description
Closes the window
Parameters
- None
Returns
- True if the operation succeeded, false if not
Signature
hs.window:focus() -> hs.window objectType
Method
Description
Focuses the window
Parameters
- None
Returns
- The
hs.windowobject
Signature
hs.window:focusTab(index) -> boolType
Method
Description
Focuses the tab in the window's tab group at index, or the last tab if
Parameters
- index - A number, a 1-based index of a tab to focus
Returns
- true if the tab was successfully pressed, or false if there was a problem
Signature
hs.window:focusWindowEast([candidateWindows[, frontmost[, strict]]]) -> booleanType
Method
Description
Focuses the nearest possible window to the east (i.e. right)
Parameters
- candidateWindows - (optional) a list of candidate windows to consider; if nil, all visible windows to the east are candidates.
- frontmost - (optional) boolean, if true focuses the nearest window that isn't occluded by any other window
- strict - (optional) boolean, if true only consider windows at an angle between 45° and -45° on the eastward axis
Returns
trueif a window was found and focused,falseotherwise;nilif the search couldn't take place
Notes
- If you don't pass
candidateWindows, Hammerspoon will query for the list of all visible windows every time this method is called; this can be slow, and some undesired "windows" could be included (see the notes forhs.window.allWindows()); consider using the equivalent methods inhs.window.filterinstead
Signature
hs.window:focusWindowNorth([candidateWindows[, frontmost[, strict]]]) -> booleanType
Method
Description
Focuses the nearest possible window to the north (i.e. up)
Parameters
- candidateWindows - (optional) a list of candidate windows to consider; if nil, all visible windows to the east are candidates.
- frontmost - (optional) boolean, if true focuses the nearest window that isn't occluded by any other window
- strict - (optional) boolean, if true only consider windows at an angle between 45° and -45° on the eastward axis
Returns
trueif a window was found and focused,falseotherwise;nilif the search couldn't take place
Notes
- If you don't pass
candidateWindows, Hammerspoon will query for the list of all visible windows every time this method is called; this can be slow, and some undesired "windows" could be included (see the notes forhs.window.allWindows()); consider using the equivalent methods inhs.window.filterinstead
Signature
hs.window:focusWindowSouth([candidateWindows[, frontmost[, strict]]]) -> booleanType
Method
Description
Focuses the nearest possible window to the south (i.e. down)
Parameters
- candidateWindows - (optional) a list of candidate windows to consider; if nil, all visible windows to the east are candidates.
- frontmost - (optional) boolean, if true focuses the nearest window that isn't occluded by any other window
- strict - (optional) boolean, if true only consider windows at an angle between 45° and -45° on the eastward axis
Returns
trueif a window was found and focused,falseotherwise;nilif the search couldn't take place
Notes
- If you don't pass
candidateWindows, Hammerspoon will query for the list of all visible windows every time this method is called; this can be slow, and some undesired "windows" could be included (see the notes forhs.window.allWindows()); consider using the equivalent methods inhs.window.filterinstead
Signature
hs.window:focusWindowWest([candidateWindows[, frontmost[, strict]]]) -> booleanType
Method
Description
Focuses the nearest possible window to the west (i.e. left)
Parameters
- candidateWindows - (optional) a list of candidate windows to consider; if nil, all visible windows to the east are candidates.
- frontmost - (optional) boolean, if true focuses the nearest window that isn't occluded by any other window
- strict - (optional) boolean, if true only consider windows at an angle between 45° and -45° on the eastward axis
Returns
trueif a window was found and focused,falseotherwise;nilif the search couldn't take place
Notes
- If you don't pass
candidateWindows, Hammerspoon will query for the list of all visible windows every time this method is called; this can be slow, and some undesired "windows" could be included (see the notes forhs.window.allWindows()); consider using the equivalent methods inhs.window.filterinstead
Signature
hs.window:frame() -> hs.geometry rectType
Method
Description
Gets the frame of the window in absolute coordinates
Parameters
- None
Returns
- An hs.geometry rect containing the co-ordinates of the top left corner of the window and its width and height
Signature
hs.window:id() -> number or nilType
Method
Description
Gets the unique identifier of the window
Parameters
- None
Returns
- A number containing the unique identifier of the window, or nil if an error occurred
Signature
hs.window:isFullScreen() -> bool or nilType
Method
Description
Gets the fullscreen state of the window
Parameters
- None
Returns
- True if the window is fullscreen, false if not. Nil if an error occurred
Signature
hs.window:isMaximizable() -> bool or nilType
Method
Description
Determines if a window is maximizable
Parameters
- None
Returns
- True if the window is maximizable, False if it isn't, or nil if an error occurred
Signature
hs.window:isMinimized() -> boolType
Method
Description
Gets the minimized state of the window
Parameters
- None
Returns
- True if the window is minimized, otherwise false
Signature
hs.window:isStandard() -> boolType
Method
Description
Determines if the window is a standard window
Parameters
- None
Returns
- True if the window is standard, otherwise false
Notes
- "Standard window" means that this is not an unusual popup window, a modal dialog, a floating window, etc.
Signature
hs.window:isVisible() -> booleanType
Method
Description
Determines if a window is visible (i.e. not hidden and not minimized)
Parameters
- None
Returns
trueif the window is visible, otherwisefalse
Notes