CommandPost Developer Guide
DownloadUser GuideFacebook Group
Search…
⌃K
Links

menu

​
Represents an app's menu bar, providing multi-lingual access to find and trigger menu items.

API Overview

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
Signature
cp.app.menu.STORYBOARD_NAME -> string
Type
Constant
Description
Main Storyboard name.

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

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

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.
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)
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
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()
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.
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".
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"})
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" }.
CommandPost API - Previous
app
Next - CommandPost API
prefs
Last modified 1yr ago