# cp.app.menu
Represents an app's menu bar, providing multi-lingual access to find and
trigger menu items.
---
## API Overview
**Constants** - _Useful values which cannot be changed_
* [NIB_FILE](#nib_file)
* [ROLE](#role)
* [STORYBOARD_NAME](#storyboard_name)
**Constructors** - _API calls which return an object, typically one that offers API methods_
* [menu](#menu)
**Fields** - _Variables which can only be accessed from an object returned by a constructor_
* [showing](#showing)
* [UI](#ui)
**Methods** - _API calls which can only be made on an object returned by a constructor_
* [addMenuFinder](#addmenufinder)
* [app](#app)
* [doFindMenuUI](#dofindmenuui)
* [doIsEnabled](#doisenabled)
* [doSelectMenu](#doselectmenu)
* [findMenuUI](#findmenuui)
* [getMenuTitles](#getmenutitles)
* [isChecked](#ischecked)
* [isEnabled](#isenabled)
* [selectMenu](#selectmenu)
* [visitMenuItems](#visitmenuitems)
---
## API Documentation
#### Constants
### [NIB_FILE](#nib_file)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.app.menu.NIB_FILE -> string` |
| **Type** | Constant |
| **Description** | Main NIB File. |
| **Notes** | None |
| **Source** | [src/extensions/cp/app/menu.lua line 59](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/app/menu.lua#L59) |
---
### [ROLE](#role)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.app.menu.ROLE -> string` |
| **Type** | Constant |
| **Description** | The menu role |
| **Notes** | None |
| **Source** | [src/extensions/cp/app/menu.lua line 49](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/app/menu.lua#L49) |
---
### [STORYBOARD_NAME](#storyboard_name)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.app.menu.STORYBOARD_NAME -> string` |
| **Type** | Constant |
| **Description** | Main Storyboard name. |
| **Notes** | None |
| **Source** | [src/extensions/cp/app/menu.lua line 69](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/app/menu.lua#L69) |
---
#### Constructors
### [menu](#menu)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.app.menu(app) -> menu` |
| **Type** | Constructor |
| **Description** | Constructs a new menu for the specified App. |
| **Parameters** | - app - The `cp.app` instance the menu belongs to.
|
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/app/menu.lua line 403](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/app/menu.lua#L403) |
---
#### Fields
### [showing](#showing)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.app.menu.showing ` |
| **Type** | Field |
| **Description** | Tells you if the app's Menu Bar is visible. |
| **Notes** | None |
| **Source** | [src/extensions/cp/app/menu.lua line 434](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/app/menu.lua#L434) |
---
### [UI](#ui)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.app.menu.UI ` |
| **Type** | Field |
| **Description** | Returns the `axuielement` representing the menu. |
| **Notes** | None |
| **Source** | [src/extensions/cp/app/menu.lua line 423](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/app/menu.lua#L423) |
---
#### Methods
### [addMenuFinder](#addmenufinder)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.app.menu:addMenuFinder(finder) -> nothing` |
| **Type** | Method |
| **Description** | Registers an `AXMenuItem` finder function. The finder's job is to take an individual 'find' step and return either the matching child, or `nil` if it can't be found. It is used by the [addMenuFinder](#addMenuFinder) function. |
| **Parameters** | - `finder` - The finder function
|
| **Returns** | - The `AXMenuItem` found, or `nil`.
|
| **Notes** | - The `finder` should have the following signature:
- `function(parentItem, path, childName, locale) -> childItem`
- The elements are:
- parentItem - The `AXMenuItem` containing the children. E.g. the `Go To` menu under `Window`.
- path - An array of strings in the specified locale leading to the parent item. E.g. `{"Window", "Go To"}`.
- childName - The name of the next child to find, in the specified locale. E.g. `"Libraries"`.
- locale - The `cp.i18n.localeID` that the menu titles are in.
- childItem - The `AXMenuItem` that was found, or `nil` if not found.
|
| **Examples** | None |
| **Source** | [src/extensions/cp/app/menu.lua line 637](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/app/menu.lua#L637) |
---
### [app](#app)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.app.menu:app() -> cp.app` |
| **Type** | Method |
| **Description** | Returns the `cp.app` instance this belongs to. |
| **Parameters** | |
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/app/menu.lua line 441](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/app/menu.lua#L441) |
---
### [doFindMenuUI](#dofindmenuui)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.app.menu:doFindMenuUI(path[, options]) -> cp.rx.go.Statement ` |
| **Type** | Method |
| **Description** | Returns a `Statement` that when executed will emit each of the menu items along the path. |
| **Parameters** | - path - the table of path items.
- options - (optional) table of additional configuration options.
|
| **Returns** | - The `Statement`, ready to be executed.
|
| **Notes** | - Each step on the path can be either one of:
- a string - The exact name of the menu item.
- a number - The menu item number, starting from 1.
- a function - Passed one argument - the Menu UI to check - returning `true` if it matches.
- The `options` may contain:
- locale - The locale that any strings in the path are in. Defaults to "en".
- plain - Whether or not to disable the pattern matching feature. Defaults to `false`.
- Examples:
- `myApp:menu():doFindMenuUI({"Edit", "Copy"}):Now(function(item) print(item:title() .. " enabled: ", item:enabled()) end, error)`
|
| **Examples** | None |
| **Source** | [src/extensions/cp/app/menu.lua line 685](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/app/menu.lua#L685) |
---
### [doIsEnabled](#doisenabled)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.app.menu:doIsEnabled(path, options) -> cp.rx.go.Statement` |
| **Type** | Method |
| **Description** | A [Statement](cp.rx.go.Statement.md) that returns `true` if the item at the end of the path is enabled. |
| **Parameters** | - path - The menu path to check.
- options - The options.
|
| **Returns** | - A [Statement](cp.rx.go.Statement.md) to execute.
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/app/menu.lua line 620](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/app/menu.lua#L620) |
---
### [doSelectMenu](#doselectmenu)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.app.menu:doSelectMenu(path, options) -> cp.rx.go.Statement ` |
| **Type** | Method |
| **Description** | Selects a Menu Item based on the provided menu path. |
| **Parameters** | - path - The list of menu items you'd like to activate.
- options - (optional) The table of options to apply.
|
| **Returns** | - The `Statement`, ready to execute.
|
| **Notes** | - Each step on the path can be either one of:
- a string - The exact name of the menu item.
- a number - The menu item number, starting from 1.
- a function - Passed one argument - the Menu UI to check - returning `true` if it matches.
- The `options` may include:
- locale - The `localeID` or `string` for the locale that the path values are in.
- pressAll - If `true`, all menu items will be pressed on the way to the final destination.
- plain - Whether or not to disable the pattern matching feature. Defaults to `false`.
- Examples:
- `previewApp:menu():doSelectMenu({"File", "Take Screenshot", "From Entire Screen"}):Now()`
|
| **Examples** | None |
| **Source** | [src/extensions/cp/app/menu.lua line 483](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/app/menu.lua#L483) |
---
### [findMenuUI](#findmenuui)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.app.menu:findMenuUI(path[, options]) -> Menu UI, table` |
| **Type** | Method |
| **Description** | Finds a specific Menu UI element for the provided path. |
| **Parameters** | - path - The path list to search for.
- options - (Optional) The table of options.
|
| **Returns** | - The Menu UI, or `nil` if it could not be found.
- The full list of Menu UIs for the path in a table.
|
| **Notes** | - E.g. `findMenuUI({"Edit", "Copy"})` returns the 'Copy' menu item in the 'Edit' menu.
- Each step on the path can be either one of:
- a string - The exact name of the menu item.
- a number - The menu item number, starting from 1.
- a function - Passed one argument - the Menu UI to check - returning `true` if it matches.
- The `options` can contain:
- locale - The `localeID` or `string` with the locale code. Defaults to "en".
- plain - Whether or not to disable the pattern matching feature. Defaults to `false`.
|
| **Examples** | None |
| **Source** | [src/extensions/cp/app/menu.lua line 821](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/app/menu.lua#L821) |
---
### [getMenuTitles](#getmenutitles)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.app.menu:getMenuTitles([locales]) -> table` |
| **Type** | Method |
| **Description** | Returns a table with the available menus, items and sub-menu, in the specified locales (if available). If no `locales` are specified, the app's current locale is loaded. |
| **Parameters** | - locales - An optional single `localeID` or a list of `localeID`s to ensure are loaded.
|
| **Returns** | - A table of Menu Bar Values
|
| **Notes** | - This menu may get added to over time if additional locales are loaded - previously loaded locales are not removed from the cache.
|
| **Examples** | None |
| **Source** | [src/extensions/cp/app/menu.lua line 454](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/app/menu.lua#L454) |
---
### [isChecked](#ischecked)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.app.menu:isChecked(path[, options]) -> boolean` |
| **Type** | Method |
| **Description** | Is a menu item checked? |
| **Parameters** | - path - At table containing the path to the menu bar item.
- options - The locale the path is in. Defaults to "en".
|
| **Returns** | - `true` if checked otherwise `false`.
|
| **Notes** | - The `options` may include:
- locale - The `localeID` or `string` with the locale code. Defaults to "en".
|
| **Examples** | None |
| **Source** | [src/extensions/cp/app/menu.lua line 582](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/app/menu.lua#L582) |
---
### [isEnabled](#isenabled)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.app.menu:isEnabled(path[, options]) -> boolean` |
| **Type** | Method |
| **Description** | Is a menu item enabled? |
| **Parameters** | - path - At table containing the path to the menu bar item.
- options - The optional table of options.
|
| **Returns** | - `true` if enabled otherwise `false`.
|
| **Notes** | - The `options` may include:
- locale - The `localeID` or `string` with the locale code. Defaults to "en".
|
| **Examples** | None |
| **Source** | [src/extensions/cp/app/menu.lua line 601](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/app/menu.lua#L601) |
---
### [selectMenu](#selectmenu)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.app.menu:selectMenu(path[, options]) -> boolean` |
| **Type** | Method |
| **Description** | Selects a Menu Item based on the list of menu titles in English. |
| **Parameters** | - path - The list of menu items you'd like to activate.
- options - (optional) The table of options to apply.
|
| **Returns** | - `true` if the press was successful.
|
| **Notes** | - Each step on the path can be either one of:
- a string - The exact name of the menu item.
- a number - The menu item number, starting from 1.
- a function - Passed one argument - the Menu UI to check - returning `true` if it matches.
- The `options` may include:
- locale - The `localeID` or `string` for the locale that the path values are in.
- pressAll - If `true`, all menu items will be pressed on the way to the final destination.
- plain - Whether or not to disable the pattern matching feature. Defaults to `false`.
- Example usage:
- `require("cp.app").forBundleID("com.apple.FinalCut"):menu():selectMenu({"View", "Browser", "Toggle Filmstrip/List View"})`
|
| **Examples** | None |
| **Source** | [src/extensions/cp/app/menu.lua line 526](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/app/menu.lua#L526) |
---
### [visitMenuItems](#visitmenuitems)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.app.menu:visitMenuItems(visitFn[, options]]) -> nil` |
| **Type** | Method |
| **Description** | Walks the menu tree, calling the `visitFn` on all the 'item' values - that is, `AXMenuItem`s that don't have any sub-menus. |
| **Parameters** | - visitFn - The function called for each menu item.
- options - (optional) The table of options.
|
| **Returns** | |
| **Notes** | - The `options` may include:
- locale - The `localeID` or `string` with the locale code. Defaults to "en".
- startPath - The path to the menu item to start at.
- The `visitFn` will be called on each menu item with the following parameters:
- `function(path, menuItem)`
- The `menuItem` is the AXMenuItem object, and the `path` is an array with the path to that menu item. For example, if it is the "Copy" item in the "Edit" menu, the path will be `{ "Edit" }`.
|
| **Examples** | None |
| **Source** | [src/extensions/cp/app/menu.lua line 977](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/app/menu.lua#L977) |
---
---