hs.window.md

docs » hs.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 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

moveOneScreenSouth

Signature	hs.window:moveOneScreenSouth([noResize, ensureInScreenBounds][, duration]) -> hs.window object
Type	Method
Description	Moves the window one screen south (i.e. down)
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

moveOneScreenWest

Signature	hs.window:moveOneScreenWest([noResize, ensureInScreenBounds][, duration]) -> hs.window object
Type	Method
Description	Moves the window one screen west (i.e. left)
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

moveToScreen

Signature	hs.window:moveToScreen(screen[, noResize, ensureInScreenBounds][, duration]) -> hs.window object
Type	Method
Description	Moves the window to a given screen, retaining its relative position and size
Parameters	screen - An hs.screen object, or an argument for hs.screen.find(), representing the screen to move the window to 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

moveToUnit

Signature	hs.window:moveToUnit(unitrect[, duration]) -> hs.window object
Type	Method
Description	Moves and resizes the window to occupy a given fraction of the screen
Parameters	unitrect - An hs.geometry unit rect, or constructor argument to create one duration - (optional) The number of seconds to animate the transition. Defaults to the value of hs.window.animationDuration
Returns	The hs.window object
Notes	An example, which would make a window fill the top-left quarter of the screen: win:moveToUnit'[0,0,50,50]'

otherWindowsAllScreens

Signature	hs.window:otherWindowsAllScreens() -> list of hs.window objects
Type	Method
Description	Gets every window except this one
Parameters	None
Returns	A table containing hs.window objects representing all visible windows other than this one

otherWindowsSameScreen

Signature	hs.window:otherWindowsSameScreen() -> list of hs.window objects
Type	Method
Description	Gets other windows on the same screen
Parameters	None
Returns	A table of hs.window objects representing the visible windows other than this one that are on the same screen

raise

Signature	hs.window:raise() -> window
Type	Method
Description	Brings a window to the front of the screen without focussing it
Parameters	None
Returns	The hs.window object

role

Signature	hs.window:role() -> string
Type	Method
Description	Gets the role of the window
Parameters	None
Returns	A string containing the role of the window

screen

Signature	hs.window:screen() -> hs.screen object
Type	Method
Description	Gets the screen which the window is on
Parameters	None
Returns	An hs.screen object representing the screen which most contains the window (by area)

sendToBack

Signature	hs.window:sendToBack() -> hs.window object
Type	Method
Description	Sends the window to the back
Parameters	None
Returns	The hs.window object
Notes	Due to the way this method works and OSX limitations, calling this method when you have a lot of randomly overlapping (as opposed to neatly tiled) windows might be visually jarring, and take a fair amount of time to complete. So if you don't use orderly layouts, or if you have a lot of windows in general, you're probably better off using hs.application:hide() (or simply cmd-h)

setFrame

Signature	hs.window:setFrame(rect[, duration]) -> hs.window object
Type	Method
Description	Sets the frame of the window in absolute coordinates
Parameters	rect - An hs.geometry rect, or constructor argument, describing the frame to be applied to the window duration - (optional) The number of seconds to animate the transition. Defaults to the value of hs.window.animationDuration
Returns	The hs.window object

setFrameInScreenBounds

Signature	hs.window:setFrameInScreenBounds([rect][, duration]) -> hs.window object
Type	Method
Description	Sets the frame of the window in absolute coordinates, possibly adjusted to ensure it is fully inside the screen
Parameters	rect - An hs.geometry rect, or constructor argument, describing the frame to be applied to the window; if omitted, the current window frame will be used duration - (optional) The number of seconds to animate the transition. Defaults to the value of hs.window.animationDuration
Returns	The hs.window object

setFrameWithWorkarounds

Signature	hs.window:setFrameWithWorkarounds(rect[, duration]) -> hs.window object
Type	Method
Description	Sets the frame of the window in absolute coordinates, using the additional workarounds described in hs.window.setFrameCorrectness
Parameters	rect - An hs.geometry rect, or constructor argument, describing the frame to be applied to the window duration - (optional) The number of seconds to animate the transition. Defaults to the value of hs.window.animationDuration
Returns	The hs.window object

setFullScreen

Signature	hs.window:setFullScreen(fullscreen) -> window
Type	Method
Description	Sets the fullscreen state of the window
Parameters	fullscreen - A boolean, true if the window should be set fullscreen, false if not
Returns	The hs.window object

setSize

Signature	hs.window:setSize(size) -> window
Type	Method
Description	Resizes the window
Parameters	size - A size-table containing the width and height the window should be resized to
Returns	The hs.window object

setTopLeft

Signature	hs.window:setTopLeft(point) -> window
Type	Method
Description	Moves the window to a given point
Parameters	point - A point-table containing the absolute co-ordinates the window should be moved to
Returns	The hs.window object

size

Signature	hs.window:size() -> size
Type	Method
Description	Gets the size of the window
Parameters	None
Returns	A size-table containing the width and height of the window

snapshot

Signature	hs.window:snapshot([keepTransparency]) -> hs.image-object
Type	Method
Description	Returns a snapshot of the window as an hs.image object
Parameters	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 function hs.window.snapshotForID()

subrole

Signature	hs.window:subrole() -> string
Type	Method
Description	Gets the subrole of the window
Parameters	None
Returns	A string containing the subrole of the window
Notes	This typically helps to determine if a window is a special kind of window - such as a modal window, or a floating window

tabCount

Signature	hs.window:tabCount() -> number or nil
Type	Method
Description	Gets the number of tabs in the window has, or nil if the window doesn't have tabs.
Parameters	None
Returns	A number containing the number of tabs, or nil if an error occurred

title

Signature	hs.window:title() -> string
Type	Method
Description	Gets the title of the window
Parameters	None
Returns	A string containing the title of the window

toggleFullScreen

Signature	hs.window:toggleFullScreen() -> hs.window object
Type	Method
Description	Toggles the fullscreen state of the window
Parameters	None
Returns	The hs.window object
Notes	Not all windows support being full-screened

toggleZoom

Signature	hs.window:toggleZoom() -> window
Type	Method
Description	Toggles the zoom state of the window (this is effectively equivalent to clicking the green maximize/fullscreen button at the top left of a window)
Parameters	None
Returns	The hs.window object

topLeft

Signature	hs.window:topLeft() -> point
Type	Method
Description	Gets the absolute co-ordinates of the top left of the window
Parameters	None
Returns	A point-table containing the absolute co-ordinates of the top left corner of the window

unminimize

Signature	hs.window:unminimize() -> window
Type	Method
Description	Un-minimizes the window
Parameters	None
Returns	The hs.window object

windowsToEast

Signature	hs.window:windowsToEast([candidateWindows[, frontmost[, strict]]]) -> list of hs.window objects
Type	Method
Description	Gets all windows to the east of this window
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 unoccluded windows will be placed before occluded ones in the result list strict - (optional) boolean, if true only consider windows at an angle between 45° and -45° on the eastward axis
Returns	A list of hs.window objects representing all windows positioned east (i.e. right) of the window, in ascending order of distance
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

windowsToNorth

Signature	hs.window:windowsToNorth([candidateWindows[, frontmost[, strict]]]) -> list of hs.window objects
Type	Method
Description	Gets all windows to the north of this window
Parameters	candidateWindows - (optional) a list of candidate windows to consider; if nil, all visible windows to the north are candidates. frontmost - (optional) boolean, if true unoccluded windows will be placed before occluded ones in the result list strict - (optional) boolean, if true only consider windows at an angle between 45° and -45° on the northward axis
Returns	A list of hs.window objects representing all windows positioned north (i.e. up) of the window, in ascending order of distance
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

windowsToSouth

Signature	hs.window:windowsToSouth([candidateWindows[, frontmost[, strict]]]) -> list of hs.window objects
Type	Method
Description	Gets all windows to the south of this window
Parameters	candidateWindows - (optional) a list of candidate windows to consider; if nil, all visible windows to the south are candidates. frontmost - (optional) boolean, if true unoccluded windows will be placed before occluded ones in the result list strict - (optional) boolean, if true only consider windows at an angle between 45° and -45° on the southward axis
Returns	A list of hs.window objects representing all windows positioned south (i.e. down) of the window, in ascending order of distance
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

windowsToWest

Signature	hs.window:windowsToWest([candidateWindows[, frontmost[, strict]]]) -> list of hs.window objects
Type	Method
Description	Gets all windows to the west of this window
Parameters	candidateWindows - (optional) a list of candidate windows to consider; if nil, all visible windows to the west are candidates. frontmost - (optional) boolean, if true unoccluded windows will be placed before occluded ones in the result list strict - (optional) boolean, if true only consider windows at an angle between 45° and -45° on the westward axis
Returns	A list of hs.window objects representing all windows positioned west (i.e. left) of the window, in ascending order of distance
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

zoomButtonRect

Signature	hs.window:zoomButtonRect() -> rect-table or nil
Type	Method
Description	Gets a rect-table for the location of the zoom button (the green button typically found at the top left of a window)
Parameters	None
Returns	A rect-table containing the bounding frame of the zoom button, or nil if an error occured
Notes	The co-ordinates in the rect-table (i.e. the x and y values) are in absolute co-ordinates, not relative to the window the button is part of, or the screen the window is on Although not perfect as such, this method can provide a useful way to find a region of the titlebar suitable for simulating mouse click events on, with hs.eventtap