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
​menu​
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.
​ROLE​
Signature
cp.app.menu.ROLE -> string
Type
Constant
Description
The menu role
​STORYBOARD_NAME​
Signature
cp.app.menu.STORYBOARD_NAME -> string
Type
Constant
Description
Main Storyboard name.
Constructors
​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
a new menu instance
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.
​UI​
Signature
cp.app.menu.UI <cp.prop:hs._asm.axuielement; read-only; live>
Type
Field
Description
Returns the axuielement representing the menu.
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'
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.
​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.
​doFindMenuUI​
Signature
cp.app.menu:doFindMenuUI(path[, options]) -> cp.rx.go.Statement <hs._asm.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)
​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.
​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()
​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
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.
​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).
Parameters
locales - An optional single localeID or a list of localeIDs 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.
​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".
​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".
​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"})
​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,
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" }.