This class assists with working with macOS apps. It provides functions for
finding, checking the running status, version number, path, and many other
values related to an application. It also provides support for launching,
quitting, and other activities related to applications.
This extension differs from the hs.application
extension in several ways:
cp.app
instances are long-lived. You request it once and it will stay up-to-date even if the app quits.
- It makes extensive use of
cp.prop
, so you can watch
many most properties of the app and get live notifications when they change.
Signature |
cp.app.frontmostApp <cp.prop: cp.app; read-only; live> |
Type |
Variable |
Description |
Returns the most recent 'registered' app that was active, other than CommandPost itself. |
Signature |
cp.app.apps() -> table |
Type |
Function |
Description |
Returns a list of all apps that have been requested via forBundleID, in no particular order. |
Parameters |
|
Returns |
- A list of
cp.app instances.
|
Signature |
cp.app.bundleIDs() -> table |
Type |
Function |
Description |
Returns a list of Bundle IDs which have been requested via forBundleID. |
Parameters |
|
Returns |
|
Signature |
cp.app.is(thing) -> boolean |
Type |
Function |
Description |
Checks if the provided thing is a cp.app instance. |
Parameters |
- thing - The thing to check.
|
Returns |
true if it is a cp.app instance, otherwise false .
|
Signature |
cp.app.forBundleID(bundleID) |
Type |
Constructor |
Description |
Returns the cp.app for the specified Bundle ID. If the app has already been created, |
Parameters |
- bundleID - The application bundle ID to find the app for.
|
Returns |
- The
cp.app for the bundle.
|
Signature |
cp.app.baseLocale <cp.prop: cp.i18n.localeID; read-only> |
Type |
Field |
Description |
Returns the localeID of the development region. This is the 'Base' locale for I18N. |
Signature |
cp.app.baseResourcesPath <cp.prop: string; read-only; live> |
Type |
Field |
Description |
A prop for the file path to the Content/Resources/Base.lproj folder |
Signature |
cp.app.currentLocale <cp.prop: cp.i18n.localeID; live> |
Type |
Field |
Description |
Gets and sets the current locale for the application. |
Signature |
cp.app.description -> string |
Type |
Field |
Description |
Returns the short description of the class as "cp.app: " |
Signature |
cp.app.displayName <cp.prop: string; read-only; live> |
Type |
Field |
Description |
The application display name as a string. |
Signature |
cp.app.focusedWindow <cp.prop: cp.ui.Window; read-only; live> |
Type |
Field |
Description |
The currently-focused Window. This may be a subclass of Window if |
Signature |
cp.app.focusedWindowUI <cp.prop: hs._asm.axuielement; read-only; live> |
Type |
Field |
Description |
Returns the UI containing the currently-focused window for the app. |
Signature |
cp.app.frontmost <cp.prop: boolean; read-only; live> |
Type |
Field |
Description |
Is the application currently frontmost? |
Signature |
cp.app.hsApplication <cp.prop: hs.application; read-only; live> |
Type |
Field |
Description |
Returns the running hs.application for the application, or nil if it's not running. |
Signature |
cp.app.info <cp.prop: table; read-only; live> |
Type |
Field |
Description |
The info table for the application, if available. |
Signature |
cp.app.installed <cp.prop: boolean; read-only> |
Type |
Field |
Description |
Checks if the application currently installed. |
Signature |
cp.app.localeResourcesPath <cp.prop: string; read-only; live> |
Type |
Field |
Description |
A prop for the file path to the locale-specific resources |
Signature |
cp.app.mainWindowUI <cp.prop: hs._asm.axuielement; read-only; live> |
Type |
Field |
Description |
Returns the UI containing the currently-focused window for the app. |
Signature |
cp.app.modalDialogOpen <cp.prop: boolean; read-only> |
Type |
Field |
Description |
Checks if a modal dialog window is currently opon. |
Signature |
cp.app.path <cp.prop: string; read-only; live> |
Type |
Field |
Description |
Path to the application, or nil if not found. |
Signature |
cp.app.pid <cp.prop: number; read-only; live> |
Type |
Field |
Description |
Returns the PID for the currently-running application, or nil if it's not running. |
Signature |
cp.app.preferences <cp.app.prefs> |
Type |
Field |
Description |
The current preferences for the application. |
Signature |
cp.app.resourcesPath <cp.prop: string; read-only; live> |
Type |
Field |
Description |
A prop for the file path to the Contents/Resources folder inside the app. |
Signature |
cp.app.running <cp.prop: boolean; read-only; live> |
Type |
Field |
Description |
Checks if the application currently is running. |
Signature |
cp.app.showing <cp.prop: boolean; read-only; live> |
Type |
Field |
Description |
Is the app visible on screen? |
Signature |
cp.app.supportedLocales <cp.prop: table of cp.i18n.localeID; read-only; live> |
Type |
Field |
Description |
Returns a list of cp.i18n.localeID values for locales that are supported by this app. |
Signature |
cp.app.UI <cp.prop: hs._asm.axuielement; read-only; live> |
Type |
Field |
Description |
Returns the application's axuielement , if available. |
Signature |
cp.app.version <cp.prop: semver; read-only; live> |
Type |
Field |
Description |
The application version as a semver. |
Notes |
- If the application is running it will get the version of the active application as a string, otherwise, it will use
hs.application.infoForBundleID() to find the version.
|
Signature |
cp.app.versionString <cp.prop: string; read-only; live> |
Type |
Field |
Description |
The application version as a string . |
Notes |
- If the application is running it will get the version of the active application as a string, otherwise, it will use
hs.application.infoForBundleID() to find the version.
|
Signature |
cp.app.windows <cp.prop: table of cp.ui.Window; read-only; live> |
Type |
Field |
Description |
Returns a list containing the Window instances currently available. |
Signature |
cp.app.windowsUI <cp.prop: table of hs._asm.axuielement; read-only; live> |
Type |
Field |
Description |
Returns the UI containing the list of windows in the app. |
Signature |
cp.app:bestSupportedLocale(locale) -> cp.i18n.localeID or nil |
Type |
Method |
Description |
Finds the closest match for the specified locale. The returned locale |
Parameters |
- locale - The local to match
|
Returns |
- The closest supported locale or
nil if none are available in the language.
|
Signature |
cp.app:bundleID() -> string |
Type |
Method |
Description |
Returns the Bundle ID for the app. |
Parameters |
|
Returns |
|
Signature |
cp.app:doHide() -> cp.rx.go.Statement <boolean> |
Type |
Method |
Description |
Returns a Statement which will hide the app if it's currently running. |
Parameters |
|
Returns |
- A
Statement , resolving to true if the app is running and was successfully hidden, or false otherwise.
|
Signature |
cp.app:doLaunch([waitSeconds[, path]]) -> cp.rx.Statement <boolean> |
Type |
Method |
Description |
Returns a Statement that can be run to launch or focus the current app. |
Parameters |
- waitSeconds - (optional) The number of seconds to wait for it to load. Defaults to 30 seconds.
- path - (optional) The alternate path of the app to launch.
|
Returns |
- The
Statement , resolving to true after the app is frontmost.
|
Notes |
- By default the
Statement will time out after 30 seconds, sending an error signal.
|
Signature |
cp.app:doQuit() -> cp.rx.go.Statement <boolean> |
Type |
Method |
Description |
Returns a Statement that will attempt to quit the app when executed. |
Parameters |
|
Returns |
- The
Statement , resolving to true if the app was running and was quit successfully, otherwise false .
|
Notes |
- The Statement will time out after 60 seconds by default. This can be changed by calling the
TimeoutAfter method on the Statement before executing.
|
Signature |
cp.app:doRestart() -> cp.rx.go.Statement <boolean> |
Type |
Method |
Description |
Returns a Statement which will attempt to restart the app. If the app |
Parameters |
|
Returns |
- The
Statement , resolving to true if the app was running and was quit and restarted successfully, otherwise false .
|
Notes |
- The Statement will time out after 60 seconds by default. This can be changed by calling the
TimeoutAfter method on the Statement before executing.
|
Signature |
cp.app:doShow() -> cp.rx.go.Statement <boolean> |
Type |
Method |
Description |
Returns a Statement which will show the app if it's currently running. |
Parameters |
|
Returns |
- A
Statement , resolving to true if the app is running and was successfully shown, or false otherwise.
|
Signature |
cp.app:hide() -> self |
Type |
Method |
Description |
Hides the application, if it's currently running. |
Parameters |
|
Returns |
|
Signature |
cp.app:isSupportedLocale(locale) -> boolean |
Type |
Method |
Description |
Checks if the specified locale is supported. The locale can |
Parameters |
- locale - The locale code string or
localeID to check.
|
Returns |
true if it is supported, otherwise false .
|
Signature |
cp.app:keyStroke(modifiers, character) -> none |
Type |
Method |
Description |
Generates and emits a single keystroke event pair for the supplied keyboard |
Parameters |
- modifiers - A table containing the keyboard modifiers to apply ("fn", "ctrl", "alt", "cmd" or "shift")
- character - A string containing a character to be emitted
|
Returns |
|
Signature |
cp.app:launch([waitSeconds], [path]) -> self |
Type |
Method |
Description |
Launches the application, or brings it to the front if it was already running. |
Parameters |
waitSeconds - If provided, the number of seconds to wait until the launch completes. If nil , it will return immediately.path - An optional full path to an application without an extension (i.e /Applications/Final Cut Pro 10.3.4 ). This allows you to load previous versions of the application.
|
Returns |
|
Signature |
cp.app:notifier() -> cp.ui.notifier |
Type |
Method |
Description |
Returns a notifier that is tracking the application UI element. It has already been started. |
Parameters |
|
Returns |
|
Signature |
cp.app:quit(waitSeconds) -> self |
Type |
Method |
Description |
Asks the application to quit, if it's running. The app may not have actually quit after this |
Parameters |
waitSeconds - If povided, the number of seconds to wait until the quit completes. If nil , it will return immediately.
|
Returns |
|
Signature |
cp.app:registerWindowType(windowClass[, options]) -> cp.app |
Type |
Method |
Description |
Registers the specified class as one which will be used when accessing a specific AXWindow instance. |
Parameters |
- windowClass - The class that will be used to create the window. It should be a subclass of Window
- options - (optional) if provided, it will be passed the
hs.asm.axuielement being wrapped, and should return true or false .
|
Returns |
- the same instance of the
cp.app for further configuration.
|
Notes |
- Options:
matches : a function that will receive the AXWindow instance and should return true or false .persistent : if set to true , the Window instance will be cached and checked when windows appear and disappear.
|
Signature |
cp.app:searchResources(value) -> hs.task |
Type |
Method |
Description |
Creates a hs.task which will search for the specified string value in the resources |
Parameters |
- value - The string value to search for.
|
Returns |
hs.task which is already running, searching for the value . Results will be output in the Error Log.
|
Notes |
- This may take some time to complete, depending on how many resources the app contains.
|
Signature |
cp.app:show() -> self |
Type |
Method |
Description |
Ensure the app is onscreen if it is currently running. |
Parameters |
|
Returns |
|
Signature |
cp.app:update() -> self |
Type |
Method |
Description |
Updates the app, triggering any watchers if values have changed. |
Parameters |
|
Returns |
|