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
, andMenuFlag_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 beMenuCode_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 beMenuCode_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
See Also
APIMenuCodeID
ACAPI_Install_MenuHandler
RegisterInterface
Required Resources
API Functions