XPLMMenus

Create menus and submenus in the X-Plane menu bar. Attach callbacks or commands to menu items.

Enumerations

XPLMMenuCheck

These enumerations define the various 'check' states for an X-Plane menu. 'Checking' in X-Plane actually appears as a light which may or may not be lit. So there are three possible states.

Constant Value Description
xplm_Menu_NoCheck 0 There is no symbol to the left of the menu item.
xplm_Menu_Unchecked 1 The menu has a mark next to it that is unmarked (not lit).
xplm_Menu_Checked 2 The menu has a mark next to it that is checked (lit).

Functions

XLuaFindPluginsMenu()

Returns: XPLMMenuID

This function returns the ID of the plug-ins menu, which is created for you at startup.

XLuaFindAircraftMenu()

Returns: XPLMMenuID

This function returns the ID of the menu for the currently-loaded aircraft, used for showing aircraft-specific commands. The aircraft menu is created by X-Plane at startup, but it remains hidden until it is populated via XPLMAppendMenuItem() or XPLMAppendMenuItemWithCommand(). Only plugins loaded with the user's current aircraft are allowed to access the aircraft menu. For all other plugins, this will return NULL, and any attempts to add menu items to it will fail.

XLuaCreateMenu(name, parentMenu, parentItem, callback, refcon)

Returns: XPLMMenuID

This function creates a new menu and returns its ID. It returns NULL if the menu cannot be created. Pass in a parent menu ID and an item index to create a submenu, or NULL for the parent menu to put the menu in the menu bar. The menu's name is only used if the menu is in the menubar. You also pass a handler function and a menu reference value. Pass NULL for the handler if you do not need callbacks from the menu (for example, if it only contains submenus). Important: you must pass a valid, non-empty menu title even if the menu is a submenu where the title is not visible.

Argument Type Notes
name string
parentMenu XPLMMenuID Enum — use a constant from XPLMMenuID
parentItem integer
handler function Callback — a Lua function you define
menuRef any Any Lua value; passed through to your callback unchanged
XLuaDestroyMenu(menuID)

Returns: (returns nothing)

This function destroys a menu that you have created. Use this to remove a submenu if necessary. (Normally this function will not be necessary.)

Argument Type Notes
menuID XPLMMenuID Enum — use a constant from XPLMMenuID
XLuaClearAllMenuItems(menuID)

Returns: (returns nothing)

This function removes all menu items from a menu, allowing you to rebuild it. Use this function if you need to change the number of items on a menu.

Argument Type Notes
menuID XPLMMenuID Enum — use a constant from XPLMMenuID
XLuaAppendMenuItem(menu, itemName, refcon, deprecatedAndIgnored)

Returns: integer

This routine appends a new menu item to the bottom of a menu and returns its index. Pass in the menu to add the item to, the items name, and a void * ref for this item. Returns a negative index if the append failed (due to an invalid parent menu argument). Note that all menu indices returned are relative to your plugin's menus only; if your plugin creates two sub-menus in the Plugins menu at different times, it doesn't matter how many other plugins also create sub-menus of Plugins in the intervening time: your sub-menus will be given menu indices 0 and 1. (The SDK does some work in the back-end to filter out menus that are irrelevant to your plugin in order to deliver this consistency for each plugin.)

Argument Type Notes
menu XPLMMenuID Enum — use a constant from XPLMMenuID
itemName string
itemRef any Any Lua value; passed through to your callback unchanged
deprecatedAndIgnored integer
XLuaAppendMenuItemWithCommand(menu, itemName, commandToExecute)

Returns: integer

Like XPLMAppendMenuItem(), but instead of the new menu item triggering the XPLMMenuHandler_f of the containiner menu, it will simply execute the command you pass in. Using a command for your menu item allows the user to bind a keyboard shortcut to the command and see that shortcut represented in the menu. Returns a negative index if the append failed (due to an invalid parent menu argument). Like XPLMAppendMenuItem(), all menu indices are relative to your plugin's menus only.

Argument Type Notes
menu XPLMMenuID Enum — use a constant from XPLMMenuID
itemName string
commandToExecute XPLMCommandRef Enum — use a constant from XPLMCommandRef
XLuaAppendMenuSeparator(menu)

Returns: (returns nothing)

This routine adds a separator to the end of a menu.

Argument Type Notes
menu XPLMMenuID Enum — use a constant from XPLMMenuID
XLuaSetMenuItemName(menu, index, itemName, deprecatedAndIgnored)

Returns: (returns nothing)

This routine changes the name of an existing menu item. Pass in the menu ID and the index of the menu item.

Argument Type Notes
menu XPLMMenuID Enum — use a constant from XPLMMenuID
index integer
itemName string
deprecatedAndIgnored integer
XLuaCheckMenuItem(menu, index, check)

Returns: (returns nothing)

Set whether a menu item is checked. Pass in the menu ID and item index.

Argument Type Notes
menu XPLMMenuID Enum — use a constant from XPLMMenuID
index integer
check XPLMMenuCheck Enum — use a constant from XPLMMenuCheck
XLuaCheckMenuItemState(menu, index)

Returns: {k} with keys: check

This routine returns whether a menu item is checked or not. A menu item's check mark may be on or off, or a menu may not have an icon at all.

Argument Type Notes
menu XPLMMenuID Enum — use a constant from XPLMMenuID
index integer

Output table keys:

Key Type
check number
XLuaEnableMenuItem(menu, index, enabled)

Returns: (returns nothing)

Sets whether this menu item is enabled. Items start out enabled.

Argument Type Notes
menu XPLMMenuID Enum — use a constant from XPLMMenuID
index integer
enabled boolean
XLuaRemoveMenuItem(menu, index)

Returns: (returns nothing)

Removes one item from a menu. Note that all menu items below are moved up one; your plugin must track the change in index numbers.

Argument Type Notes
menu XPLMMenuID Enum — use a constant from XPLMMenuID
index integer

Examples

Examples coming soon.