#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
ROLE
STORYBOARD_NAME

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

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

showing
UI

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

addMenuFinder
app
doFindMenuUI
doIsEnabled
doSelectMenu
findMenuUI
getMenuTitles
isChecked
isEnabled
selectMenu
visitMenuItems

#API Documentation

#Constants

#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

#ROLE


Signature	`cp.app.menu.ROLE -> string`
Type	Constant
Description	The menu role
Notes	None
Source	src/extensions/cp/app/menu.lua line 49

#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

#Constructors


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	a new menu instance
Notes	None
Examples	None
Source	src/extensions/cp/app/menu.lua line 403

#Fields

#showing


Signature	`cp.app.menu.showing <cp.prop: boolean; read-only; live>`
Type	Field
Description	Tells you if the app's Menu Bar is visible.
Notes	None
Source	src/extensions/cp/app/menu.lua line 434

#UI


Signature	`cp.app.menu.UI <cp.prop:hs.axuielement; read-only; live>`
Type	Field
Description	Returns the `axuielement` representing the menu.
Notes	None
Source	src/extensions/cp/app/menu.lua line 423

#Methods

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

#app


Signature	`cp.app.menu:app() -> cp.app`
Type	Method
Description	Returns the `cp.app` instance this belongs to.
Parameters	None
Returns	The `cp.app`.
Notes	None
Examples	None
Source	src/extensions/cp/app/menu.lua line 441

#doFindMenuUI


Signature	`cp.app.menu:doFindMenuUI(path[, options]) -> cp.rx.go.Statement <hs.axuielement>`
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

#doIsEnabled


Signature	`cp.app.menu:doIsEnabled(path, options) -> cp.rx.go.Statement`
Type	Method
Description	A Statement 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 to execute.
Notes	None
Examples	None
Source	src/extensions/cp/app/menu.lua line 620

#doSelectMenu


Signature	`cp.app.menu:doSelectMenu(path, options) -> cp.rx.go.Statement <boolean>`
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

#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

#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

#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

#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

#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

#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	Nothing
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