{
   Copyright 2005-2012 Sandy Barbour and Ben Supnik All rights reserved.  See
   license.txt for usage. X-Plane SDK Version: 2.1.1                          
}

UNIT XPLMMenus;
INTERFACE
{
   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.    
}

USES
    XPLMDefs, XPLMUtilities;
   {$A4}
{___________________________________________________________________________
 * 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.                                  
   }
TYPE
   XPLMMenuCheck = (
     { 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
 
   );
   PXPLMMenuCheck = ^XPLMMenuCheck;

   {
    XPLMMenuID
    
    This is a unique ID for each menu you create.                              
   }
   XPLMMenuID = pointer;
   PXPLMMenuID = ^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).                                                     
   }
     XPLMMenuHandler_f = PROCEDURE(
                                    inMenuRef           : pointer;    
                                    inItemRef           : pointer); cdecl;   

   {
    XPLMFindPluginsMenu
    
    This function returns the ID of the plug-ins menu, which is created for you
    at startup.                                                                
   }
   FUNCTION XPLMFindPluginsMenu: XPLMMenuID;
    cdecl; external XPLM_DLL;

{$IFDEF 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.                                
   }
   FUNCTION XPLMFindAircraftMenu: XPLMMenuID;
    cdecl; external XPLM_DLL;
{$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.                                  
   }
   FUNCTION XPLMCreateMenu(
                                        inName              : XPLMString;    
                                        inParentMenu        : XPLMMenuID;    
                                        inParentItem        : Integer;    
                                        inHandler           : XPLMMenuHandler_f;    
                                        inMenuRef           : pointer) : XPLMMenuID;    
    cdecl; external XPLM_DLL;

   {
    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.)     
   }
   PROCEDURE XPLMDestroyMenu(
                                        inMenuID            : XPLMMenuID);    
    cdecl; external XPLM_DLL;

   {
    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.
   }
   PROCEDURE XPLMClearAllMenuItems(
                                        inMenuID            : XPLMMenuID);    
    cdecl; external XPLM_DLL;

   {
    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.)                                                                   
   }
   FUNCTION XPLMAppendMenuItem(
                                        inMenu              : XPLMMenuID;    
                                        inItemName          : XPLMString;    
                                        inItemRef           : pointer;    
                                        inDeprecatedAndIgnored: Integer) : Integer;    
    cdecl; external XPLM_DLL;

{$IFDEF 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.                                                                
   }
   FUNCTION XPLMAppendMenuItemWithCommand(
                                        inMenu              : XPLMMenuID;    
                                        inItemName          : XPLMString;    
                                        inCommandToExecute  : XPLMCommandRef) : Integer;    
    cdecl; external XPLM_DLL;
{$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).                                                            
   }
   PROCEDURE XPLMAppendMenuSeparator(
                                        inMenu              : XPLMMenuID);    
    cdecl; external XPLM_DLL;

   {
    XPLMSetMenuItemName
    
    This routine changes the name of an existing menu item.  Pass in the menu
    ID and the index of the menu item.                                         
   }
   PROCEDURE XPLMSetMenuItemName(
                                        inMenu              : XPLMMenuID;    
                                        inIndex             : Integer;    
                                        inItemName          : XPLMString;    
                                        inDeprecatedAndIgnored: Integer);    
    cdecl; external XPLM_DLL;

   {
    XPLMCheckMenuItem
    
    Set whether a menu item is checked.  Pass in the menu ID and item index.   
   }
   PROCEDURE XPLMCheckMenuItem(
                                        inMenu              : XPLMMenuID;    
                                        index               : Integer;    
                                        inCheck             : XPLMMenuCheck);    
    cdecl; external XPLM_DLL;

   {
    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.        
   }
   PROCEDURE XPLMCheckMenuItemState(
                                        inMenu              : XPLMMenuID;    
                                        index               : Integer;    
                                        outCheck            : PXPLMMenuCheck);    
    cdecl; external XPLM_DLL;

   {
    XPLMEnableMenuItem
    
    Sets whether this menu item is enabled.  Items start out enabled.          
   }
   PROCEDURE XPLMEnableMenuItem(
                                        inMenu              : XPLMMenuID;    
                                        index               : Integer;    
                                        enabled             : Integer);    
    cdecl; external XPLM_DLL;

{$IFDEF 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.                   
   }
   PROCEDURE XPLMRemoveMenuItem(
                                        inMenu              : XPLMMenuID;    
                                        inIndex             : Integer);    
    cdecl; external XPLM_DLL;
{$ENDIF XPLM210}


IMPLEMENTATION

END.
