HSApplication
TypeObject representing an application. You should not instantiate this directly in JavaScript, but rather, use the methods from hs.application which will return appropriate HSApplication objects.
Properties
kind
string
The kind of application: "standard" (regular dock app), "accessory" (no dock), or "background" (agent)
Methods
kill() -> boolean
Terminate the application
Declaration
kill() -> booleanReturns
boolean
True if the application was terminated, otherwise false
Example
const app = hs.application.matchingName("Calculator")
app.kill()kill9() -> boolean
Force-terminate the application
Declaration
kill9() -> booleanReturns
boolean
True if the application was force-terminated, otherwise false
Example
const app = hs.application.matchingName("Calculator")
app.kill9()axElement() -> HSAXElement
The application's HSAXElement object, for use with the hs.ax APIs
Declaration
axElement() -> HSAXElementReturns
HSAXElement
An HSAXElement object, or nil if it could not be obtained
Example
const app = hs.application.frontmost()
const ax = app.axElement()activate(allWindows) -> None
Bring this application to the foreground
Declaration
activate(allWindows) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| allWindows | boolean | Pass true to raise all application windows. Defaults to false. |
Returns
None
Example
const app = hs.application.matchingName("Safari")
app.activate()
app.activate(true)hide() -> None
Hide this application and all its windows
Declaration
hide() -> NoneReturns
None
Example
const app = hs.application.matchingName("Safari")
app.hide()unhide() -> None
Unhide this application
Declaration
unhide() -> NoneReturns
None
Example
const app = hs.application.matchingName("Safari")
app.unhide()getMenuItems() -> [[String: Any]]
Get the full menu structure of this application
Declaration
getMenuItems() -> [[String: Any]]Returns
[[String: Any]]
An array of top-level menu objects, each with title and items keys, or null if unavailable
Example
const app = hs.application.frontmost()
app.getMenuItems().forEach(m => console.log(m.title))findMenuItemByName(name) -> [String: Any]
Find a menu item by searching all menus for a matching title (case-insensitive)
Declaration
findMenuItemByName(name) -> [String: Any]Parameters
| Name | Type | Description |
|---|---|---|
| name | string | The menu item title to search for |
Returns
[String: Any]
An object with title and enabled keys, or null if not found
Example
const app = hs.application.frontmost()
const item = app.findMenuItemByName("Select All")
console.log(item.enabled)findMenuItemByPath(path) -> [String: Any]
Find a menu item by following a hierarchical path of titles
Declaration
findMenuItemByPath(path) -> [String: Any]Parameters
| Name | Type | Description |
|---|---|---|
| path | string[] | An array of menu titles forming a path from the top-level menu to the item, e.g. ["Edit", "Select All"] |
Returns
[String: Any]
An object with title and enabled keys, or null if not found
Example
const app = hs.application.frontmost()
const item = app.findMenuItemByPath(["Edit", "Select All"])
console.log(item.enabled)selectMenuItemByName(name) -> boolean
Click a menu item found by searching all menus for a matching title (case-insensitive)
Declaration
selectMenuItemByName(name) -> booleanParameters
| Name | Type | Description |
|---|---|---|
| name | string | The menu item title to search for |
Returns
boolean
true if the menu item was found and clicked, false otherwise
Example
const safari = hs.application.matchingName("Safari")
safari.selectMenuItemByName("New Window")selectMenuItemByPath(path) -> boolean
Click a menu item found by following a hierarchical path of titles
Declaration
selectMenuItemByPath(path) -> booleanParameters
| Name | Type | Description |
|---|---|---|
| path | string[] | An array of menu titles forming a path from the top-level menu to the item, e.g. ["File", "New Window"] |
Returns
boolean
true if the menu item was found and clicked, false otherwise
Example
const safari = hs.application.matchingName("Safari")
safari.selectMenuItemByPath(["File", "New Window"])findWindow(pattern) -> HSWindow[]
Find windows whose title contains the given string (case-insensitive)
Declaration
findWindow(pattern) -> HSWindow[]Parameters
| Name | Type | Description |
|---|---|---|
| pattern | string | A string to search for in window titles |
Returns
HSWindow[]
An array of matching HSWindow objects
Example
const app = hs.application.frontmost()
app.findWindow("untitled").forEach(w => console.log(w.title))getWindow(title) -> HSWindow
Get the first window with exactly the given title
Declaration
getWindow(title) -> HSWindowParameters
| Name | Type | Description |
|---|---|---|
| title | string | The exact window title to search for |
Returns
HSWindow
The matching HSWindow, or null if not found
Example
const app = hs.application.frontmost()
const win = app.getWindow("index.html")