CommandPost Developer Guide
DownloadUser GuideFacebook Group
Search…
⌃K
Links

window

​
Inspect/manipulate windows
Notes:
  • See hs.screen and hs.geometry for more information on how Hammerspoon uses window/screen frames and coordinates

Submodules

API Overview

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.setFrameCorrectness
Type
Variable
Description
Using hs.window:setFrame() in some cases does not work as expected: namely, the bottom (or Dock) edge, and edges between screens, might

Functions

Signature
hs.window.allWindows() -> list of hs.window objects
Type
Function
Description
Returns all windows
Parameters
  • None
Returns
  • A list of hs.window objects 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.filter module
  • 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.filter module
  • if Displays have separate Spaces is 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 that hs.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 the hs.window.filter module, 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

​desktop​

Signature
hs.window.desktop() -> hs.window object
Type
Function
Description
Returns the desktop "window"
Parameters
  • None
Returns
  • An hs.window object 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 AXScrollArea and no subrole
  • The desktop is filtered out from hs.window.allWindows() (and downstream uses)
Signature
hs.window.invisibleWindows() -> list of hs.window objects
Type
Function
Description
Gets all invisible windows
Parameters
  • None
Returns
  • A list containing hs.window objects representing all windows that are not visible as per hs.window:isVisible()

​list​

Signature
hs.window.list(allWindows) -> table
Type
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
  • true is succesful otherwise false if an error occured.
Notes
  • This allows you to get window information without Accessibility Permissions.
Signature
hs.window.minimizedWindows() -> list of hs.window objects
Type
Function
Description
Gets all minimized windows
Parameters
  • None
Returns
  • A list containing hs.window objects representing all windows that are minimized as per hs.window:isMinimized()
Signature
hs.window.orderedWindows() -> list of hs.window objects
Type
Function
Description
Returns all visible windows, ordered from front to back
Parameters
  • None
Returns
  • A list of hs.window objects 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-object
Type
Function
Description
Returns a snapshot of the window specified by the ID as an hs.image object
Parameters
  • 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.image object 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.

​timeout​

Signature
hs.window.timeout(value) -> boolean
Type
Function
Description
Sets the timeout value used in the accessibility API.
Parameters
  • value - The number of seconds for the new timeout value.
Returns
  • true is succesful otherwise false if an error occured.
Signature
hs.window.visibleWindows() -> list of hs.window objects
Type
Function
Description
Gets all visible windows
Parameters
  • None
Returns
  • A list containing hs.window objects representing all windows that are visible as per hs.window:isVisible()

Constructors

​find​

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 per hs.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 nil if 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() -> window
Type
Constructor
Description
Returns the window that has keyboard/mouse focus
Parameters
  • None
Returns
  • An hs.window object representing the currently focused window
Signature
hs.window.frontmostWindow() -> hs.window object
Type
Constructor
Description
Returns the focused window or, if no window has focus, the frontmost one
Parameters
  • None
Returns
  • An hs.window object representing the frontmost window, or nil if there are no visible windows

​get​

Signature
hs.window.get(hint) -> hs.window object
Type
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 nil if not found
Notes
  • see also hs.window.find and hs.application:getWindow()

Methods

Signature
hs.window:application() -> app or nil
Type
Method
Description
Gets the hs.application object the window belongs to
Parameters
  • None
Returns
  • An hs.application object representing the application that owns the window, or nil if an error occurred
Signature
hs.window:becomeMain() -> window
Type
Method
Description
Makes the window the main window of its application
Parameters
  • None
Returns
  • The hs.window object
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 object
Type
Method
Description
Centers the window on a screen
Parameters
  • screen - (optional) An hs.screen object or argument for hs.screen.find; if nil, use the screen the window is currently on
  • ensureInScreenBounds - (optional) if true, use setFrameInScreenBounds() 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.window object

​close​

Signature
hs.window:close() -> bool
Type
Method
Description
Closes the window
Parameters
  • None
Returns
  • True if the operation succeeded, false if not

​focus​

Signature
hs.window:focus() -> hs.window object
Type
Method
Description
Focuses the window
Parameters
  • None
Returns
  • The hs.window object

​focusTab​

Signature
hs.window:focusTab(index) -> bool
Type
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]]]) -> boolean
Type
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
  • true if a window was found and focused, false otherwise; nil if 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 for hs.window.allWindows()); consider using the equivalent methods in hs.window.filter instead
Signature
hs.window:focusWindowNorth([candidateWindows[, frontmost[, strict]]]) -> boolean
Type
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
  • true if a window was found and focused, false otherwise; nil if 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 for hs.window.allWindows()); consider using the equivalent methods in hs.window.filter instead
Signature
hs.window:focusWindowSouth([candidateWindows[, frontmost[, strict]]]) -> boolean
Type
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
  • true if a window was found and focused, false otherwise; nil if 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 for hs.window.allWindows()); consider using the equivalent methods in hs.window.filter instead
Signature
hs.window:focusWindowWest([candidateWindows[, frontmost[, strict]]]) -> boolean
Type
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
  • true if a window was found and focused, false otherwise; nil if 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 for hs.window.allWindows()); consider using the equivalent methods in hs.window.filter instead

​frame​

Signature
hs.window:frame() -> hs.geometry rect
Type
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

​id​

Signature
hs.window:id() -> number or nil
Type