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

# 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
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
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 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.
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, AXMenuItems 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

© Copyright 2024 LateNite Films Pty Ltd. All rights reserved.