hm.applications.md

Module hm.applications

API CHANGE: Running applications and app bundles are distinct objects. Edge cases with multiple bundles with the same id are solved.

Run, stop, query and manage applications.

Overview

• Module hm.applications

  • allBundles : {<#bundle>, ...} - property (read-only)
  • runningApplications : {<#application>, ...} - property (read-only)
  • runningBackgroundApplications : {<#application>, ...} - property (read-only)
  • activeApplication : <#application> - property
  • menuBarOwningApplication : <#application> - property
  • applicationForPID(pid) -> <#application> - function
  • bundlesForBundleID(bid) -> {<#bundle>, ...} - function
  • bundlesForFile(path,role) -> {<#bundle>, ...} - function
  • bundlesForURL(url) -> {<#bundle>, ...} - function
  • defaultBundleForBundleID(bid) -> <#bundle> - function
  • defaultBundleForFile(path,role) -> <#bundle> - function
  • defaultBundleForURL(url) -> <#bundle> - function
  • findBundle(hint,ignoreCase) - function
  • getBundle(bid) - function
  • launchOrFocus(name) - function
  • launchOrFocusByBundleID(bid) - function
  • newWatcher(fn,data,events,name) -> <#watcher> - function

• Class application

  • bundle : <#bundle> - property (read-only)
  • bundleID : <#string> - property (read-only)
  • kind : <#applicationKind> - property (read-only)
  • launchTime : <#number> - property (read-only)
  • name : <#string> - property (read-only)
  • ownsMenuBar : <#boolean> - property (read-only)
  • path : <#string> - property (read-only)
  • pid : <#number> - property (read-only)
  • visibleWindows : {<hm.windows#window>, ...} - property (read-only)
  • windows : {<hm.windows#window>, ...} - property (read-only)
  • active : <#boolean> - property
  • focusedWindow : <hm.windows#window> - property
  • hidden : <#boolean> - property
  • mainWindow : <hm.windows#window> - property
  • running : <#boolean> - property
  • activate() -> self - method
  • bringToFront() -> self - method
  • forceQuit(gracePeriod) -> self - method
  • hide() -> self - method
  • quit() -> self - method
  • unhide() -> self - method

• Class bundle

  • appName : <#string> - property (read-only)
  • application : <#application> - property (read-only)
  • id : <#string> - property (read-only)
  • name : <#string> - property (read-only)
  • path : <#string> - property (read-only)
  • launch() -> <#application> - method

• Class watcher

  • active : <#boolean> - property
  • start(events,fn,data) -> self - method
  • stop() -> self - method

• Type applicationKind

• Type bundleRole

• Type eventName

• Function prototypes

  • watcherCallback(application,event,data) - function prototype

---

Module hm.applications

Extends <hm#module>

Property (read-only) hm.applications.allBundles: {<#bundle>, ...}

All application bundles in the filesystem.

This property is cached, so it won't reflect changes in the filesystem after the first time it's requested.

Property (read-only) hm.applications.runningApplications: {<#application>, ...}

The currently running GUI applications.

This list only includes applications of <#applicationKind> "standard" and "accessory".

Property (read-only) hm.applications.runningBackgroundApplications: {<#application>, ...}

The currently running background applications.

This list only includes applications of <#applicationKind> "background".

Property hm.applications.activeApplication: <#application>

The active application.

This is the application that currently receives input events.

Property hm.applications.menuBarOwningApplication: <#application>

The application owning the menu bar.

Note that this is not necessarily the same as activeApplication.

Function hm.applications.applicationForPID(pid) -> <#application>

Internal/advanced use only

• pid: <?>

• Returns <#application>:

Function hm.applications.bundlesForBundleID(bid) -> {<#bundle>, ...}

Internal/advanced use only

INTERNAL CHANGE: returns all bundles for a given bundle id

• bid: <?>

• Returns {<#bundle>, ...}:

Function hm.applications.bundlesForFile(path,role) -> {<#bundle>, ...}

Internal/advanced use only

• path: <?>

• role: <?>

• Returns {<#bundle>, ...}:

Function hm.applications.bundlesForURL(url) -> {<#bundle>, ...}

Internal/advanced use only

• url: <?>

• Returns {<#bundle>, ...}:

Function hm.applications.defaultBundleForBundleID(bid) -> <#bundle>

Internal/advanced use only

• bid: <?>

• Returns <#bundle>:

Function hm.applications.defaultBundleForFile(path,role) -> <#bundle>

Internal/advanced use only

• path: <?>

• role: <?>

• Returns <#bundle>:

Function hm.applications.defaultBundleForURL(url) -> <#bundle>

Internal/advanced use only

• url: <?>

• Returns <#bundle>:

Function hm.applications.findBundle(hint,ignoreCase)

• hint: <?>
• ignoreCase: <?>

Function hm.applications.getBundle(bid)

• bid: <?>

Function hm.applications.launchOrFocus(name)

• name: <?>

Function hm.applications.launchOrFocusByBundleID(bid)

• bid: <?>

Function hm.applications.newWatcher(fn,data,events,name) -> <#watcher>

Internal/advanced use only

Creates a new watcher for application events.

• fn: <#watcherCallback> (optional) callback function

• data: <?> (optional)

• events: {<#eventName>, ...} (optional)

• name: <#string>

• Returns <#watcher>: the new watcher

---

Class application

Extends <hm#module.object>

Defines type checker hm.applications#application application

Type for running application objects.

Property (read-only) <#application>.bundle: <#bundle>

The application bundle.

If the application does not have a bundle structure, this property is nil.

Property (read-only) <#application>.bundleID: <#string>

The application bundle identifier.

This is a shortcut for app.bundle.id.

Property (read-only) <#application>.kind: <#applicationKind>

The application's kind.

Property (read-only) <#application>.launchTime: <#number>

The absolute time when the application was launched.

Property (read-only) <#application>.name: <#string>

The application name.

Property (read-only) <#application>.ownsMenuBar: <#boolean>

Whether this application currently owns the menu bar.

Property (read-only) <#application>.path: <#string>

The application bundle's path.

This is a shortcut for app.bundle.path.

Property (read-only) <#application>.pid: <#number>

The application process identifier.

Property (read-only) <#application>.visibleWindows: {<hm.windows#window>, ...}

The application's visible windows (not minimized).

When the application is hidden this property is an empty list.

Property (read-only) <#application>.windows: {<hm.windows#window>, ...}

INTERNAL CHANGE: the ad-hoc filtering is done here at the source rather than downstream in hm.windows

The application's windows.

Property <#application>.active: <#boolean>

Whether this is the active application.

The active application is the one currently receiving input events.

Property <#application>.focusedWindow: <hm.windows#window>

The application's focused window.

Property <#application>.hidden: <#boolean>

Whether the application is currently hidden.

Property <#application>.mainWindow: <hm.windows#window>

Internal/advanced use only

The application's main window.

Property <#application>.running: <#boolean>

Whether the application is currently running.

This property can be set to false to terminate the application.

Method <#application>:activate() -> self

Makes this the active application.

• Returns self: <#application>

Method <#application>:bringToFront() -> self

Activates this application and puts all its windows on top of other windows.

• Returns self: <#application>

Method <#application>:forceQuit(gracePeriod) -> self

Force quits the application.

• gracePeriod: <#number> (optional) number of seconds to wait for the app to quit normally before forcequitting; pass 0 to force quit immediately. If omitted defaults to 10.

• Returns self: <#application>

Method <#application>:hide() -> self

Hides the application.

• Returns self: <#application>

Method <#application>:quit() -> self

Quits the application.

• Returns self: <#application>

Method <#application>:unhide() -> self

Unhides the application.

• Returns self: <#application>

---

Class bundle

Extends <hm#module.object>

Defines type checker hm.applications#bundle appBundle

Type for application bundle objects.

Property (read-only) <#bundle>.appName: <#string>

The name of the bundled application.

Property (read-only) <#bundle>.application: <#application>

The application object for this bundle.

If this app bundle isn't currently running, this property is nil.

Property (read-only) <#bundle>.id: <#string>

The bundle ID.

Property (read-only) <#bundle>.name: <#string>

The name of the bundle on the filesystem.

Property (read-only) <#bundle>.path: <#string>

The bundle full path.

Method <#bundle>:launch() -> <#application>

Launches this bundle.

• Returns <#application>: the running application object for this bundle

---

Class watcher

Extends <hm#module.object>

Internal/advanced use only

Defines type checker hm.applications#watcher

Type for application watcher objects.

Property <#watcher>.active: <#boolean>

Whether this watcher is currently active.

Method <#watcher>:start(events,fn,data) -> self

Starts the watcher.

• events: {<#eventName>, ...} (optional)

• fn: <#watcherCallback> (optional)

• data: <?> (optional)

• Returns self: <#watcher>

Method <#watcher>:stop() -> self

Stops the watcher.

• Returns self: <#watcher>

---

Type applicationKind

Extends <#string>

A string describing an application's kind.

Valid values are:

• "standard": the application has a main window, a menu bar, and (usually) appears in the Dock
• "accessory": the application has a transient user interface (for example a menulet)
• "background": the application does not have any user interface (for example daemons and helpers)

---

Type bundleRole

Extends <#string>

Defines type checker hm.applications#bundleRole

The required role for finding app bundles.

Valid values are "viewer", "editor", "all" or nil (same as "all")

---

Type eventName

Extends <#string>

Internal/advanced use only

Defines type checker hm.applications#eventName

Application event name.

Valid values are "launching", "launched", "activated", "deactivated", "hidden", "unhidden", "terminated".

---

Function prototype watcherCallback(application,event,data)

Internal/advanced use only

Callback for application watchers.

• application: <#application> the application that caused the event
• event: <#eventName> the event
• data: <?>