Xplm Menus

XPLMMenuCheck

enum

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.

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

XPLMMenuID

typedef

This is a unique ID for each menu you create.

typedef void * XPLMMenuID;

XPLMMenuHandler_f

callback

A menu handler function takes two reference pointers, one for the menu (specified when the menu was created) and one for the item (specified when the item was created).

typedef void (* XPLMMenuHandler_f)(
                         void *               inMenuRef,
                         void *               inItemRef
                    );

XPLMFindPluginsMenu

function

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

XPLM_API XPLMMenuID XPLMFindPluginsMenu(void);

XPLMFindAircraftMenu

function XPLM300

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.

XPLM_API XPLMMenuID XPLMFindAircraftMenu(void);

XPLMCreateMenu

function

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.

XPLM_API XPLMMenuID XPLMCreateMenu(
                         const char *         inName,
                         XPLMMenuID           inParentMenu,
                         int                  inParentItem,
                         XPLMMenuHandler_f    inHandler,    /* Can be NULL */
                         void *               inMenuRef
                    );

XPLMDestroyMenu

function

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

XPLM_API void       XPLMDestroyMenu(
                         XPLMMenuID           inMenuID
                    );

XPLMClearAllMenuItems

function

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.

XPLM_API void       XPLMClearAllMenuItems(
                         XPLMMenuID           inMenuID
                    );

XPLMAppendMenuItem

function

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

XPLM_API int        XPLMAppendMenuItem(
                         XPLMMenuID           inMenu,
                         const char *         inItemName,
                         void *               inItemRef,
                         int                  inDeprecatedAndIgnored
                    );

XPLMAppendMenuItemWithCommand

function XPLM300

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.

XPLM_API int        XPLMAppendMenuItemWithCommand(
                         XPLMMenuID           inMenu,
                         const char *         inItemName,
                         XPLMCommandRef       inCommandToExecute
                    );

XPLMAppendMenuSeparator

function

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

XPLM_API void       XPLMAppendMenuSeparator(
                         XPLMMenuID           inMenu
                    );

XPLMSetMenuItemName

function

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

XPLM_API void       XPLMSetMenuItemName(
                         XPLMMenuID           inMenu,
                         int                  inIndex,
                         const char *         inItemName,
                         int                  inDeprecatedAndIgnored
                    );

XPLMCheckMenuItem

function

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

XPLM_API void       XPLMCheckMenuItem(
                         XPLMMenuID           inMenu,
                         int                  index,
                         XPLMMenuCheck        inCheck
                    );

XPLMCheckMenuItemState

function

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.

XPLM_API void       XPLMCheckMenuItemState(
                         XPLMMenuID           inMenu,
                         int                  index,
                         XPLMMenuCheck *      outCheck
                    );

XPLMEnableMenuItem

function

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

XPLM_API void       XPLMEnableMenuItem(
                         XPLMMenuID           inMenu,
                         int                  index,
                         int                  enabled
                    );

XPLMRemoveMenuItem

function XPLM210

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.

XPLM_API void       XPLMRemoveMenuItem(
                         XPLMMenuID           inMenu,
                         int                  inIndex
                    );