app

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.

Submodules

API Overview

API Documentation

Functions

apps

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

None

Returns

A list of cp.app instances.

bundleIDs

Signature

cp.app.bundleIDs() -> table

Type

Function

Description

Returns a list of Bundle IDs which have been requested via forBundleID.

Parameters

None

Returns

A list of Bundle IDs.

is

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.

Constructors

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.

Fields

Signature

cp.app.frontmostApp <cp.prop: cp.app; read-only; live>

Type

Field

Description

Returns the most recent 'registered' app that was active, other than CommandPost itself.

Methods

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.

bundleID

Signature

cp.app:bundleID() -> string

Type

Method

Description

Returns the Bundle ID for the app.

Parameters

None

Returns

The Bundle ID.

doHide

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

None

Returns

A Statement, resolving to true if the app is running and was successfully hidden, or false otherwise.

doLaunch

Signature

cp.app:doLaunch() -> cp.rx.Statement <boolean>

Type

Method

Description

Returns a Statement that can be run to launch or focus the current app.

Parameters

None

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.

doQuit

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

None.

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.

doRestart

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

None.

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.

doShow

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

None

Returns

A Statement, resolving to true if the app is running and was successfully shown, or false otherwise.

hide

Signature

cp.app:hide() -> self

Type

Method

Description

Hides the application, if it's currently running.

Parameters

None

Returns

The cp.app instance.

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.

launch

Signature

cp.app:launch(waitSeconds) -> self

Type

Method

Description

Launches the application, or brings it to the front if it was already running.

Parameters

waitSeconds - If povided, the number of seconds to wait until the launch completes. If nil, it will return immediately.

Returns

The cp.app instance.

Signature

cp.app:menu() -> cp.app.menu

Type

Method

Description

Returns the main menu for the application.

Parameters

None

Returns

The cp.app.menu for the cp.app instance.

notifier

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

None

Returns

The notifier.

quit

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

The cp.app instance.

restart

Signature

cp.app:restart(waitSeconds) -> self

Type

Method

Description

Restart the application, if currently running. If not, no action is taken.

Parameters

waitSeconds - If povided, the number of seconds to wait until the quit completes. If nil, it will return immediately.

Returns

The cp.app instance.

show

Signature

cp.app:show() -> self

Type

Method

Description

Ensure the app is onscreen if it is currently running.

Parameters

None

Returns

The cp.app instance.

update

Signature

cp.app:update() -> self

Type

Method

Description

Updates the app, triggering any watchers if values have changed.

Parameters

None

Returns

The cp.app instance.