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