ray
Owner: IIIlllIIIllI URL: git@github.com:nyangkosense/ray.git
SDK/CHeaders/XPLM/XPLMMenus.h
#ifndef _XPLMMenus_h_
#define _XPLMMenus_h_
/*
* Copyright 2005-2022 Laminar Research, Sandy Barbour and Ben Supnik All
* rights reserved. See license.txt for usage. X-Plane SDK Version: 4.0.0
*
*/
/***************************************************************************
* XPLMMenus
***************************************************************************/
/*
* Plug-ins can create menus in the menu bar of X-Plane. This is done by
* creating a menu and then creating items. Menus are referred to by an
* opaque ID. Items are referred to by (zero-based) index number.
*
* Menus are "sandboxed" between plugins - no plugin can access the menus of
* any other plugin. Furthermore, all menu indices 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.)
*
* When you create a menu item, you specify how we should handle clicks on
* that menu item. You can either have the XPLM trigger a callback (the
* XPLMMenuHandler_f associated with the menu that contains the item), or you
* can simply have a command be triggered (with no associated call to your
* menu handler). The advantage of the latter method is that X-Plane will
* display any keyboard shortcuts associated with the command. (In contrast,
* there are no keyboard shortcuts associated with menu handler callbacks with
* specific parameters.)
*
* Menu text in X-Plane is UTF8; X-Plane's character set covers latin, greek
* and cyrillic characters, Katakana, as well as some Japanese symbols. Some
* APIs have a inDeprecatedAndIgnored parameter that used to select a
* character set; since X-Plane 9 all localization is done via UTF-8 only.
*
*/
#include "XPLMDefs.h"
#include "XPLMUtilities.h"
#ifdef __cplusplus
extern "C" {
#endif
/***************************************************************************
* XPLM MENUS
***************************************************************************/
/*
* 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.
*
*/
enum {
/* There is no symbol to the left of the menu item. */
xplm_Menu_NoCheck = 0,
/* The menu has a mark next to it that is unmarked (not lit). */
xplm_Menu_Unchecked = 1,
/* The menu has a mark next to it that is checked (lit). */
xplm_Menu_Checked = 2,
};
typedef int XPLMMenuCheck;
/*
* XPLMMenuID
*
* This is a unique ID for each menu you create.
*
*/
typedef void * XPLMMenuID;
/*
* XPLMMenuHandler_f
*
* 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
*
* This function returns the ID of the plug-ins menu, which is created for you
* at startup.
*
*/
XPLM_API XPLMMenuID XPLMFindPluginsMenu(void);
#if defined(XPLM300)
/*
* XPLMFindAircraftMenu
*
* 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);
#endif /* XPLM300 */
/*
* XPLMCreateMenu
*
* 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,
void * inMenuRef);
/*
* XPLMDestroyMenu
*
* 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
*
* 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
*
* 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);
#if defined(XPLM300)
/*
* XPLMAppendMenuItemWithCommand
*
* 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);
#endif /* XPLM300 */
/*
* XPLMAppendMenuSeparator
*
* This routine adds a separator to the end of a menu.
*
* Returns a negative index if the append failed (due to an invalid parent
* menu argument).
*
*/
XPLM_API void XPLMAppendMenuSeparator(
XPLMMenuID inMenu);
/*
* XPLMSetMenuItemName
*
* 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
*
* 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
*
* 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
*
* Sets whether this menu item is enabled. Items start out enabled.
*
*/
XPLM_API void XPLMEnableMenuItem(
XPLMMenuID inMenu,
int index,
int enabled);
#if defined(XPLM210)
/*
* XPLMRemoveMenuItem
*
* 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);
#endif /* XPLM210 */
#ifdef __cplusplus
}
#endif
#endif