Internationalisation
Bundled Plugins API
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

Variables

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.

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.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.

frontmost

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.

info

Signature
cp.app.info <cp.prop: table; read-only; live>
Type
Field
Description
The info table for the application, if available.

installed

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.

path

Signature
cp.app.path <cp.prop: string; read-only; live>
Type
Field
Description
Path to the application, or nil if not found.

pid

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.

running

Signature
cp.app.running <cp.prop: boolean; read-only; live>
Type
Field
Description
Checks if the application currently is running.

showing

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.

UI

Signature
cp.app.UI <cp.prop: hs._asm.axuielement; read-only; live>
Type
Field
Description
Returns the application's axuielement, if available.

version

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.

windows

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.

windowsUI

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.

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([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.

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.

keyStroke

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
  • None

launch

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
  • 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.
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.

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.
Last modified 1mo ago