ACAPI_Register_Menu |

Registers the menu items of the add-on.

    GSErrCode  ACAPI_Register_Menu (
        short             menuStrResID,
        short             promptStrResID,
        APIMenuCodeID     menuPosCode,
        GSFlags           menuFlags
    );

Parameters

menuStrResID: [in] The resource ID of the menu resource, which should be in the resource fork of the add-on.
promptStrResID: [in] The resource ID of the propmt string resource, which should be in the resource fork of the add-on. These strings appear in the status bar.
menuPosCode: [in] Defines the server application’s menu to insert the command into.
menuFlags: [in] Flags describing whether you would like to see any separator item in the menu before or after the registered menu item. Its possible values are: MenuFlag_Default, MenuFlag_SeparatorBefore, and MenuFlag_SeparatorAfter

Return Values

NoError: The function has completed with success.

For other common API errors see the API Errors document.

Remarks

This function should be called from the RegisterInterface routine in your add-on. You can register more than one menu from the same add-on, even appearing in different menus of the server application.

The supplied menuStrResID parameter should be the same in the ACAPI_Install_MenuHandler function, which you have to call from your Initialize routine.

The following scenarios are possible:

the add-on inserts one menu item at the position defined by menuPosCode


'STR#' 32500    "Menu Description" {
/* [  1] */        "My add-on's solo menuitem"
}

the add-on inserts a submenu at the position defined by menuPosCode


'STR#' 32501    "Menu Description" {
/* [  1] */        "My add-on's submenu"
/* [  2] */            "My add-on's menuitem #1"
/* [  3] */            "My add-on's menuitem #2"
}

the add-on inserts its own main menu; menuPosCode should be MenuCode_UserDef


'STR#' 32502    "Menu Description" {
/* [  1] */        "My add-on's main menu"
/* [  2] */            "My add-on's solo menuitem"
}

the add-on inserts its own main menu with a submenu; menuPosCode should be MenuCode_UserDef


'STR#' 32503    "Menu Description" {
/* [  1] */        "My add-on's main menu"
/* [  2] */            "My add-on's submenu"
/* [  3] */                "My add-on's menuitem #1"
/* [  4] */                "My add-on's menuitem #2"
}

As you see, the add-on may define its own main menu, if it uses MenuCode_UserDef and the menu position. In this case the first item in the STR# resource will be the title of the main menu, and the other items correspond to the menu items in the non-main menu case. If this first item is the same as one of the server application’s main menu titles, then the API won’t open a new main menu, rather it inserts the add-on’s menu into the original main menu, as defined by the rules for that menu. This also means if you use an already existing menu title (e.g. Window) which doesn’t have an insertion place for add-ons, your add-on’s menu won’t appear.

This implies that the location of the add-on within the Add-Ons folder doesn’t have any impact on the menu position of your add-on’s commands.

The appearance of menu items can be controlled by control codes appended to the menu item string resource as described in the Required Resources section.

Example

In the GRC file:


'STR#' 32500 "Menu strings" {
/* [  1] */     "Show Selections^ES^E3^ED^32500"
}

'STR#' 32520 "Status bar prompt strings" {
/* [  1] */     "Show Selections palette"
}

/* Toolbar icon resource ("RFIX\Images\TB_show_selections.png") */
'GICN' 32500 "TB_show_selections" {
    "TB_show_selections"
}

In the RegisterInterface function:


//------------------------------------------------------
// Interface definitions
//------------------------------------------------------
GSErrCode __ACENV_CALL    RegisterInterface (void)
{
    GSErrCode    err;

    // Register menu command
    err = ACAPI_Register_Menu (32500, 32520, MenuCode_Palettes, MenuFlag_Default);

    return err;
}   // RegisterInterface

Requirements

Version: API 4.1 or later

Header: ACAPinc.h

Parameters

Return Values

Remarks

Example

Requirements

See Also