menu

Last updated 23 days ago

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

Constructors

new

Signature

cp.app.menu.new(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

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". Examples: * myApp:menu():doFindMenuUI({"Edit", "Copy"}):Now(function(item) print(item:title() .. " enabled: ", item:enabled()) end, error)

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. 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".

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. 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" }.