cp.app.md

docs » 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

• cp.app.menu
• cp.app.prefs

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

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

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,
Parameters	bundleID - The application bundle ID to find the app for.
Returns	The cp.app for the bundle.

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.

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

currentLocale

Signature	cp.app.currentLocale <cp.prop: cp.i18n.localeID; live>
Type	Field
Description	Gets and sets the current locale for the application.

description

Signature	cp.app.description -> string
Type	Field
Description	Returns the short description of the class as "cp.app: "

displayName

Signature	cp.app.displayName <cp.prop: string; read-only; live>
Type	Field
Description	The application display name as a string.

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

focusedWindowUI

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?

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.

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.

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

mainWindowUI

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.

modalDialogOpen

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.

preferences

Signature	cp.app.preferences <cp.app.prefs>
Type	Field
Description	The current preferences for the application.

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.

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?

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.

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.

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.

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

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

isSupportedLocale

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.

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.

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