cp.app.menu.md

docs » 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
• 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" }.