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

Variables - Configurable values

frontmostApp

Functions - API calls offered directly by the extension

apps
bundleIDs
is

Constructors - API calls which return an object, typically one that offers API methods

forBundleID

Fields - Variables which can only be accessed from an object returned by a constructor

baseLocale
baseResourcesPath
currentLocale
description
displayName
focusedWindow
focusedWindowUI
frontmost
hsApplication
info
installed
isWindowAnimationEnabled
localeResourcesPath
mainWindowUI
modalDialogOpen
path
pid
preferences
resourcesPath
running
showing
supportedLocales
UI
version
versionString
windows
windowsUI

Methods - API calls which can only be made on an object returned by a constructor

bestSupportedLocale
bundleID
doHide
doLaunch
doQuit
doRestart
doShow
hide
icon
isSupportedLocale
keyStroke
launch
notifier
quit
registerWindowType
searchResources
show
update

#API Documentation

#Variables

#frontmostApp


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.
Notes	None
Source	src/extensions/cp//app.lua line 127

#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.
Notes	None
Examples	None
Source	src/extensions/cp//app.lua line 108

#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.
Notes	None
Examples	None
Source	src/extensions/cp//app.lua line 91

#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`.
Notes	None
Examples	None
Source	src/extensions/cp//app.lua line 78

#Constructors

#forBundleID


Signature	`cp.app.forBundleID(bundleID)`
Type	Constructor
Description	Returns the `cp.app` for the specified Bundle ID. If the app has already been created, the same instance of `cp.app` will be returned on subsequent calls.
Parameters	bundleID - The application bundle ID to find the app for.
Returns	The `cp.app` for the bundle.
Notes	None
Examples	None
Source	src/extensions/cp//app.lua line 153

#Fields

#baseLocale


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.
Notes	None
Source	src/extensions/cp//app.lua line 603

#baseResourcesPath


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
Notes	None
Source	src/extensions/cp//app.lua line 740

#currentLocale


Signature	`cp.app.currentLocale <cp.prop: cp.i18n.localeID; live>`
Type	Field
Description	Gets and sets the current locale for the application.
Notes	None
Source	src/extensions/cp//app.lua line 647

#description


Signature	`cp.app.description -> string`
Type	Field
Description	Returns the short description of the class as "cp.app: "
Notes	None
Source	src/extensions/cp//app.lua line 1048

#displayName


Signature	`cp.app.displayName <cp.prop: string; read-only; live>`
Type	Field
Description	The application display name as a string.
Notes	None
Source	src/extensions/cp//app.lua line 586

#focusedWindow


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
Notes	None
Source	src/extensions/cp//app.lua line 452

#focusedWindowUI


Signature	`cp.app.focusedWindowUI <cp.prop: hs.axuielement; read-only; live>`
Type	Field
Description	Returns the UI containing the currently-focused window for the app.
Notes	None
Source	src/extensions/cp//app.lua line 462

#frontmost


Signature	`cp.app.frontmost <cp.prop: boolean; read-only; live>`
Type	Field
Description	Is the application currently frontmost?
Notes	None
Source	src/extensions/cp//app.lua line 312

#hsApplication


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.
Notes	None
Source	src/extensions/cp//app.lua line 245

#info


Signature	`cp.app.info <cp.prop: table; read-only; live>`
Type	Field
Description	The info table for the application, if available.
Notes	None
Source	src/extensions/cp//app.lua line 533

#installed


Signature	`cp.app.installed <cp.prop: boolean; read-only>`
Type	Field
Description	Checks if the application currently installed.
Notes	None
Source	src/extensions/cp//app.lua line 596

#isWindowAnimationEnabled


Signature	`cp.app.isWindowAnimationEnabled <cp.prop: bool; live>`
Type	Field
Description	A prop that determines if window animations (eg. popups, etc.) are enabled for the
Notes	None
Source	src/extensions/cp//app.lua line 771

#localeResourcesPath


Signature	`cp.app.localeResourcesPath <cp.prop: string; read-only; live>`
Type	Field
Description	A prop for the file path to the locale-specific resources
Notes	None
Source	src/extensions/cp//app.lua line 751

#mainWindowUI


Signature	`cp.app.mainWindowUI <cp.prop: hs.axuielement; read-only; live>`
Type	Field
Description	Returns the UI containing the currently-focused window for the app.
Notes	None
Source	src/extensions/cp//app.lua line 481

#modalDialogOpen


Signature	`cp.app.modalDialogOpen <cp.prop: boolean; read-only>`
Type	Field
Description	Checks if a modal dialog window is currently opon.
Notes	None
Source	src/extensions/cp//app.lua line 491

#path


Signature	`cp.app.path <cp.prop: string; read-only; live>`
Type	Field
Description	Path to the application, or `nil` if not found.
Notes	None
Source	src/extensions/cp//app.lua line 504

#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.
Notes	None
Source	src/extensions/cp//app.lua line 267

#preferences


Signature	`cp.app.preferences <cp.app.prefs>`
Type	Field
Description	The current preferences for the application.
Notes	None
Source	src/extensions/cp//app.lua line 238

#resourcesPath


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.
Notes	None
Source	src/extensions/cp//app.lua line 730

#running


Signature	`cp.app.running <cp.prop: boolean; read-only; live>`
Type	Field
Description	Checks if the application currently is running.
Notes	None
Source	src/extensions/cp//app.lua line 277

#showing


Signature	`cp.app.showing <cp.prop: boolean; read-only; live>`
Type	Field
Description	Is the app visible on screen?
Notes	None
Source	src/extensions/cp//app.lua line 299

#supportedLocales


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.
Notes	None
Source	src/extensions/cp//app.lua line 614

#UI


Signature	`cp.app.UI <cp.prop: hs.axuielement; read-only; live>`
Type	Field
Description	Returns the application's `axuielement`, if available.
Notes	None
Source	src/extensions/cp//app.lua line 287

#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.
Source	src/extensions/cp//app.lua line 573

#versionString


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.
Source	src/extensions/cp//app.lua line 560

#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.
Notes	None
Source	src/extensions/cp//app.lua line 418

#windowsUI


Signature	`cp.app.windowsUI <cp.prop: table of hs.axuielement; read-only; live>`
Type	Field
Description	Returns the UI containing the list of windows in the app.
Notes	None
Source	src/extensions/cp//app.lua line 432

#Methods

#bestSupportedLocale


Signature	`cp.app:bestSupportedLocale(locale) -> cp.i18n.localeID or nil`
Type	Method
Description	Finds the closest match for the specified locale. The returned locale will be in the same language as the provided locale, and as close a match as possible with the region and script.
Parameters	locale - The local to match
Returns	The closest supported locale or `nil` if none are available in the language.
Notes	None
Examples	None
Source	src/extensions/cp//app.lua line 1105

#bundleID


Signature	`cp.app:bundleID() -> string`
Type	Method
Description	Returns the Bundle ID for the app.
Parameters	None
Returns	The Bundle ID.
Notes	None
Examples	None
Source	src/extensions/cp//app.lua line 198

#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.
Notes	None
Examples	None
Source	src/extensions/cp//app.lua line 1017

#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. It will resolve to `true` when the app was launched.
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.
Examples	None
Source	src/extensions/cp//app.lua line 823

#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.
Examples	None
Source	src/extensions/cp//app.lua line 895

#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 was not running at the time, no action is taken and `false` is returned. If it was running then the app will be attempted to quit then restarted.
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. If you have multiple versions of the same app on your system, this will restart with the same version that was running when the restart was requested.
Examples	None
Source	src/extensions/cp//app.lua line 918

#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.
Notes	None
Examples	None
Source	src/extensions/cp//app.lua line 977

#hide


Signature	`cp.app:hide() -> self`
Type	Method
Description	Hides the application, if it's currently running.
Parameters	None
Returns	The `cp.app` instance.
Notes	None
Examples	None
Source	src/extensions/cp//app.lua line 1000

#icon


Signature	`cp.app:icon() -> image`
Type	Method
Description	Returns the application icon as a `hs.image`
Parameters	None
Returns	The icon as a `hs.image` object
Notes	None
Examples	None
Source	src/extensions/cp//app.lua line 211

#isSupportedLocale


Signature	`cp.app:isSupportedLocale(locale) -> boolean`
Type	Method
Description	Checks if the specified locale is supported. The `locale` can be either a string with the locale code (eg. "en_AU") or a `cp.i18n.localeID`.
Parameters	locale - The locale code string or `localeID` to check.
Returns	`true` if it is supported, otherwise `false`.
Notes	None
Examples	None
Source	src/extensions/cp//app.lua line 1083

#keyStroke


Signature	`cp.app:keyStroke(modifiers, character) -> none`
Type	Method
Description	Generates and emits a single keystroke event pair for the supplied keyboard modifiers and character to the application.
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
Notes	None
Examples	None
Source	src/extensions/cp//app.lua line 224

#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.
Notes	None
Examples	None
Source	src/extensions/cp//app.lua line 786

#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.
Notes	None
Examples	None
Source	src/extensions/cp//app.lua line 1035

#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 function runs, even if `true` is returned. The application may take some time, or may be prompting the user for input, etc.
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.
Notes	None
Examples	None
Source	src/extensions/cp//app.lua line 875

#registerWindowType


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. By default, it will use the `matches` function on the class itself to check. An alternate function can be provided by putting it in the `{matches = <function>}` property of the `options` table. By default, Windows instances are assumed to be short-lived, and will not persist beyond the window opening or closing. To indicate that it should stick around, add `persistent = true` to the `options` table. If the new `AXWindow` matches, this class will be used when requesting the set of windows via the [#windows] method or the [#focusedWindow] or [#mainWindow] props. Classes registered later will supersede those registered earlier, so ensure that matchers are specific enough to not recognise more window UIs than they should.
Examples	None
Source	src/extensions/cp//app.lua line 325

#searchResources


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 of the current app.
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.
Examples	None
Source	src/extensions/cp//app.lua line 1163

#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.
Notes	None
Examples	None
Source	src/extensions/cp//app.lua line 955

#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.
Notes	None
Examples	None
Source	src/extensions/cp//app.lua line 1133