Xplm Menus

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

-- returns XPLMMenuID -> assign to local/var
local my_menuID = XPLMFindPluginsMenu(
)

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.

-- returns XPLMMenuID -> assign to local/var
local my_menuID = XPLMFindAircraftMenu(
)

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.

-- returns XPLMMenuID -> assign to local/var
local my_menuID = XPLMCreateMenu(
    inName,          -- string
    inParentMenu,    -- XPLMMenuID
    inParentItem,    -- int
    inHandler,       -- see XPLMMenuHandler_f
    inMenuRef        -- any Lua var/table
)

See associated types:

• XPLMMenuHandler_f
• XPLMMenuID

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

XPLMDestroyMenu(
    inMenuID     -- XPLMMenuID
)

See associated types:

• XPLMMenuID

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.

XPLMClearAllMenuItems(
    inMenuID     -- XPLMMenuID
)

See associated types:

• XPLMMenuID

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

-- returns int -> assign to local/var
local my_result = XPLMAppendMenuItem(
    inMenu,                    -- XPLMMenuID
    inItemName,                -- string
    inItemRef,                 -- any Lua var/table
    inDeprecatedAndIgnored     -- int
)

See associated types:

• XPLMMenuID

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.

-- returns int -> assign to local/var
local my_result = XPLMAppendMenuItemWithCommand(
    inMenu,                -- XPLMMenuID
    inItemName,            -- string
    inCommandToExecute     -- XPLMCommandRef
)

See associated types:

• XPLMMenuID

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

XPLMAppendMenuSeparator(
    inMenu     -- XPLMMenuID
)

See associated types:

• XPLMMenuID

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

XPLMSetMenuItemName(
    inMenu,                    -- XPLMMenuID
    inIndex,                   -- int
    inItemName,                -- string
    inDeprecatedAndIgnored     -- int
)

See associated types:

• XPLMMenuID

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

XPLMCheckMenuItem(
    inMenu,     -- XPLMMenuID
    index,      -- int
    inCheck     -- XPLMMenuCheck
)

See associated types:

• XPLMMenuCheck
• XPLMMenuID

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.

XPLMCheckMenuItemState(
    inMenu,      -- XPLMMenuID
    index,       -- int
    outCheck     -- XPLMMenuCheck
)

See associated types:

• XPLMMenuCheck
• XPLMMenuID

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

XPLMEnableMenuItem(
    inMenu,     -- XPLMMenuID
    index,      -- int
    enabled     -- boolean
)

See associated types:

• XPLMMenuID

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.

XPLMRemoveMenuItem(
    inMenu,     -- XPLMMenuID
    inIndex     -- int
)

See associated types:

• XPLMMenuID