window

​
Inspect/manipulate windows
Notes:
See hs.screen and hs.geometry for more information on how Hammerspoon uses window/screen frames and coordinates
Submodules
​hs.window.filter​
​hs.window.highlight​
​hs.window.layout​
​hs.window.switcher​
​hs.window.tiling​
API Overview
Variables - Configurable values
​animationDuration​
​setFrameCorrectness​
Functions - API calls offered directly by the extension
​allWindows​
​desktop​
​invisibleWindows​
​list​
​minimizedWindows​
​orderedWindows​
​setShadows​
​snapshotForID​
​timeout​
​visibleWindows​
Constructors - API calls which return an object, typically one that offers API methods
​find​
​focusedWindow​
​frontmostWindow​
​get​
Methods - API calls which can only be made on an object returned by a constructor
​application​
​becomeMain​
​centerOnScreen​
​close​
​focus​
​focusTab​
​focusWindowEast​
​focusWindowNorth​
​focusWindowSouth​
​focusWindowWest​
​frame​
​id​
​isFullScreen​
​isMaximizable​
​isMinimized​
​isStandard​
​isVisible​
​maximize​
​minimize​
​move​
​moveOneScreenEast​
​moveOneScreenNorth​
​moveOneScreenSouth​
​moveOneScreenWest​
​moveToScreen​
​moveToUnit​
​otherWindowsAllScreens​
​otherWindowsSameScreen​
​raise​
​role​
​screen​
​sendToBack​
​setFrame​
​setFrameInScreenBounds​
​setFrameWithWorkarounds​
​setFullScreen​
​setSize​
​setTopLeft​
​size​
​snapshot​
​subrole​
​tabCount​
​title​
​toggleFullScreen​
​toggleZoom​
​topLeft​
​unminimize​
​windowsToEast​
​windowsToNorth​
​windowsToSouth​
​windowsToWest​
​zoomButtonRect​
API Documentation
Variables
​animationDuration​
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.
​setFrameCorrectness​
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
​allWindows​
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)
​invisibleWindows​
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.
​minimizedWindows​
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()
​orderedWindows​
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
​setShadows​
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
​snapshotForID​
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.
​visibleWindows​
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
​focusedWindow​
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
​frontmostWindow​
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
​application​
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
​becomeMain​
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()
​centerOnScreen​
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
​focusWindowEast​
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
​focusWindowNorth​
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
​focusWindowSouth​
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
​focusWindowWest​
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
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
​isFullScreen​
Signature
hs.window:isFullScreen() -> bool or nil
Type
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
​isMaximizable​
Signature
hs.window:isMaximizable() -> bool or nil
Type
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
​isMinimized​
Signature
hs.window:isMinimized() -> bool
Type
Method
Description
Gets the minimized state of the window
Parameters
None
Returns
True if the window is minimized, otherwise false
​isStandard​
Signature
hs.window:isStandard() -> bool
Type
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.
​isVisible​
Signature
hs.window:isVisible() -> boolean
Type
Method
Description
Determines if a window is visible (i.e. not hidden and not minimized)
Parameters
None
Returns
true if the window is visible, otherwise false
Notes
This does not mean the user can see the window - it may be obscured by other windows, or it may be off the edge of the screen
​maximize​
Signature
hs.window:maximize([duration]) -> hs.window object
Type
Method
Description
Maximizes the window
Parameters
duration - (optional) The number of seconds to animate the transition. Defaults to the value of hs.window.animationDuration
Returns
The hs.window object
Notes
The window will be resized as large as possible, without obscuring the dock/menu
​minimize​
Signature
hs.window:minimize() -> window
Type
Method
Description
Minimizes the window
Parameters
None
Returns
The hs.window object
Notes
This method will always animate per your system settings and is not affected by hs.window.animationDuration
​move​
Signature
hs.window:move(rect[, screen][, ensureInScreenBounds][, duration]) --> hs.window object
Type
Method
Description
Moves the window
Parameters
rect - It can be:
an hs.geometry point, or argument to construct one; will move the screen by this delta, keeping its size constant; screen is ignored
an hs.geometry rect, or argument to construct one; will set the window frame to this rect, in absolute coordinates; screen is ignored
an hs.geometry unit rect, or argument to construct one; will set the window frame to this rect relative to the desired screen; if screen is nil, use the screen the window is currently on
screen - (optional) An hs.screen object or argument for hs.screen.find; only valid if rect is a unit rect
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
​moveOneScreenEast​
Signature
hs.window:moveOneScreenEast([noResize, ensureInScreenBounds][, duration]) -> hs.window object
Type
Method
Description
Moves the window one screen east (i.e. right)
Parameters
noResize - (optional) if true, maintain the window's absolute size
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
​moveOneScreenNorth​
Signature
hs.window:moveOneScreenNorth([noResize, ensureInScreenBounds][, duration]) -> hs.window object
Type
Method
Description
Moves the window one screen north (i.e. up)
Parameters
noResize - (optional) if true, maintain the window's absolute size
ensureInScreenBounds - (optional) if 

Submodules

API Overview

API Documentation

Variables

​animationDuration​

​setFrameCorrectness​

Functions

​allWindows​

​desktop​

​invisibleWindows​

​list​

​minimizedWindows​

​orderedWindows​

​setShadows​

​snapshotForID​

​timeout​

​visibleWindows​

Constructors

​find​

​focusedWindow​

​frontmostWindow​

​get​

Methods

​application​

​becomeMain​

​centerOnScreen​

​close​

​focus​

​focusTab​

​focusWindowEast​

​focusWindowNorth​

​focusWindowSouth​

​focusWindowWest​

​frame​

​id​

​isFullScreen​

​isMaximizable​

​isMinimized​

​isStandard​

​isVisible​

​maximize​

​minimize​

​move​

​moveOneScreenEast​

​moveOneScreenNorth​

animationDuration

setFrameCorrectness

allWindows

desktop

invisibleWindows

list

minimizedWindows

orderedWindows

setShadows

snapshotForID

timeout

visibleWindows

find

focusedWindow

frontmostWindow

get

application

becomeMain

centerOnScreen

close

focus

focusTab

focusWindowEast

focusWindowNorth

focusWindowSouth

focusWindowWest

frame

id

isFullScreen

isMaximizable

isMinimized

isStandard

isVisible

maximize

minimize

move

moveOneScreenEast

moveOneScreenNorth