hs.window
ModuleModule for interacting with windows
Types
This module provides the following types:
Properties
hs.window.allWindowsIgnore
string[]
A list of bundle identifiers to ignore when fetching a list of all windows
Methods
hs.window.focusedWindow() -> HSWindow
Get the currently focused window
Declaration
hs.window.focusedWindow() -> HSWindowReturns
HSWindow
The focused window, or nil if none
Example
const win = hs.window.focusedWindow()
console.log(win && win.title)hs.window.allWindows() -> HSWindow[]
Get all windows from all applications
Declaration
hs.window.allWindows() -> HSWindow[]Returns
HSWindow[]
An array of all windows
Example
const wins = hs.window.allWindows()
console.log(wins.length)hs.window.visibleWindows() -> HSWindow[]
Get all visible (not minimized) windows
Declaration
hs.window.visibleWindows() -> HSWindow[]Returns
HSWindow[]
An array of visible windows
Example
const vis = hs.window.visibleWindows()hs.window.windowsForApp(app) -> HSWindow[]
Get windows for a specific application
Declaration
hs.window.windowsForApp(app) -> HSWindow[]Parameters
| Name | Type | Description |
|---|---|---|
| app | HSApplication | An HSApplication object |
Returns
HSWindow[]
An array of windows for that application
Example
const app = hs.application.frontmost()
const wins = hs.window.windowsForApp(app)hs.window.windowsOnScreen(screenIndex) -> HSWindow[]
Get all windows on a specific screen
Declaration
hs.window.windowsOnScreen(screenIndex) -> HSWindow[]Parameters
| Name | Type | Description |
|---|---|---|
| screenIndex | number | The screen index (0 for main screen) |
Returns
HSWindow[]
An array of windows on that screen
Example
const wins = hs.window.windowsOnScreen(0)hs.window.windowAtPoint(point) -> HSWindow
Get the window at a specific screen position
Declaration
hs.window.windowAtPoint(point) -> HSWindowParameters
| Name | Type | Description |
|---|---|---|
| point | HSPoint | An HSPoint containing the coordinates |
Returns
HSWindow
The topmost window at that position, or nil if none
Example
const win = hs.window.windowAtPoint({x: 500, y: 300})hs.window.orderedWindows() -> HSWindow[]
Get ordered windows (front to back)
Declaration
hs.window.orderedWindows() -> HSWindow[]Returns
HSWindow[]
An array of windows in z-order
Example
const wins = hs.window.orderedWindows()hs.window.snapshotForID(id, keepTransparency) -> Promise<HSImage>
Capture the current on-screen contents of the window with the given ID.
Requires **Screen Recording** permission.
Declaration
hs.window.snapshotForID(id, keepTransparency) -> Promise<HSImage>Parameters
| Name | Type | Description |
|---|---|---|
| id | number | The window's underlying ID (see the `id` property on `hs.window` objects). |
| keepTransparency | boolean | Whether to preserve the window's alpha channel. If `false` (the default), transparent regions are filled with an opaque black background. |
Returns
Promise<HSImage>
Resolves with the captured image, or rejects if no window with that ID can be found, or the capture fails.
Example
hs.window.snapshotForID(12345).then(img => img.saveToFile("/tmp/window.png"))hs.window.findByTitle(title) -> HSWindow[]
Find windows by title
Parameter title: The window title to search for. All windows with titles that include this string, will be matched
Declaration
hs.window.findByTitle(title) -> HSWindow[]Parameters
| Name | Type | Description |
|---|---|---|
| title | any | The window title to search for. All windows with titles that include this string, will be matched |
Returns
HSWindow[]
An array of HSWindow objects with matching titles
hs.window.currentWindows() -> HSWindow[]
Get all windows for the current application
Declaration
hs.window.currentWindows() -> HSWindow[]Returns
HSWindow[]
An array of HSWindow objects
hs.window.moveToLeftHalf(win) -> boolean
Move a window to left half of screen
Parameter win: An HSWindow object
Declaration
hs.window.moveToLeftHalf(win) -> booleanParameters
| Name | Type | Description |
|---|---|---|
| win | any | An HSWindow object |
Returns
boolean
True if the operation was successful, otherwise False
hs.window.moveToRightHalf(win) -> boolean
Move a window to right half of screen
Parameter win: An HSWindow object
Declaration
hs.window.moveToRightHalf(win) -> booleanParameters
| Name | Type | Description |
|---|---|---|
| win | any | An HSWindow object |
Returns
boolean
True if the operation was successful, otherwise False
hs.window.maximize(win) -> boolean
Maximize a window
Parameter win: An HSWindow object
Declaration
hs.window.maximize(win) -> booleanParameters
| Name | Type | Description |
|---|---|---|
| win | any | An HSWindow object |
Returns
boolean
True if the operation was successful, otherwise false