Menu integration

Functions providing a way to integrate the Add-On into the menu structure of Archicad. More...

Classes
class	ACAPI::UI::Menu::MenuItem
	MenuItem is a representation of one of this addon's menu item. More...
class	ACAPI::UI::Menu::MenuManager
	A class that contains menu item related functions. More...
struct	API_MenuItemRef
	Reference to a menu item mounted by the API tool add-on. More...

Functions
MenuManager	ACAPI::UI::Menu::CreateMenuManager ()
	A function to create menu manager instance, that lets you query and manipulate menu related data.
GSErrCode	ACAPI_MenuItem_GetMenuItemFlags (const API_MenuItemRef *menuItemRef, GSFlags *itemFlags, GS::UniString *menuItemText=nullptr)
	Returns the flag values of the specified menu item mounted by API tool add-on.
GSErrCode	ACAPI_MenuItem_SetMenuItemFlags (const API_MenuItemRef *menuItemRef, GSFlags *itemFlags, GS::UniString *menuItemText=nullptr)
	Sets the flag values of the specified menu item.
GSErrCode	ACAPI_MenuItem_GetMenuItemText (const API_MenuItemRef *menuItemRef, char *itemText, GS::UniString *itemUniText=nullptr)
	Returns the text of the specified menu item.
GSErrCode	ACAPI_MenuItem_SetMenuItemText (const API_MenuItemRef *menuItemRef, char *itemText, GS::UniString *itemUniText=nullptr)
	Sets the text of the specified menu item.
GSErrCode	ACAPI_MenuItem_AddMenuItemText (const API_MenuItemRef *menuItemRef, char *weText, GS::UniString *weUniText=nullptr)
	Sets the text of a specified menu item that will appear in the Work Environment dialog.
GSErrCode	ACAPI_MenuItem_RegisterMenu (short menuStrResID, short promptStrResID, APIMenuCodeID menuPosCode, GSFlags menuFlags)
	Registers the menu items of the add-on.
GSErrCode	ACAPI_MenuItem_InstallMenuHandler (short menuStrResID, APIMenuCommandProc *handlerProc)
	Installs a callback procedure for handling the add-on's menu commands.

Detailed Description

Functions providing a way to integrate the Add-On into the menu structure of Archicad.

Function Documentation

ACAPI_MenuItem_AddMenuItemText()

GSErrCode ACAPI_MenuItem_AddMenuItemText	(	const API_MenuItemRef *	menuItemRef,
		char *	weText,
		GS::UniString *	weUniText = nullptr )

Sets the text of a specified menu item that will appear in the Work Environment dialog.

Parameters

menuItemRef	[in] The referenced menu item.
weText	[in] The text (if you don't pass weUniText) that will appear as the name of the menu item in the menu customization part of the work environment dialog.
weUniText	[in] The Unicode text that will appear as the name of the menu item in the menu customization part of the work environment dialog.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - menuItemRef or both itemText and itemUniText are nullptr

Remarks

We use this function mainly for palettes. In the Palettes menu the item is usually the title of the palette (e.g. "Element Information"), whereas in the Work Environment dialog it reads "Show/Hide Element Information".

ACAPI_MenuItem_GetMenuItemFlags()

GSErrCode ACAPI_MenuItem_GetMenuItemFlags	(	const API_MenuItemRef *	menuItemRef,
		GSFlags *	itemFlags,
		GS::UniString *	menuItemText = nullptr )

Returns the flag values of the specified menu item mounted by API tool add-on.

Parameters

menuItemRef	[in] Identifies the menu item.
itemFlags	[out] Menu item flags. Flag Value Meaning API_MenuItemDisabled The menu item is currently disabled API_MenuItemChecked The menu item is currently checked
menuItemText	[out] Optional Unicode menu item text to get.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - any of the parameters are nullptr
• APIERR_BADINDEX - the specified menu item does not belong to the caller add-on

Remarks

This function is used to get the current status of a menu item which belongs to the caller API tool add-on. The menu item is referenced with the resource ID and the string number. To change the status of a menu item use the ACAPI_MenuItem_SetMenuItemFlags function.

Example

void    EnableACMenuItem (short itemInd, bool enable)
{
    API_MenuItemRef itemRef {};
    GSFlags itemFlags;
 
    itemRef.menuResID = 32500;
    itemRef.itemIndex = itemInd;
 
    itemFlags = 0;
    ACAPI_MenuItem_GetMenuItemFlags (&itemRef, &itemFlags);
    if (enable)
        itemFlags &= ~API_MenuItemDisabled;
    else
        itemFlags |= API_MenuItemDisabled;
    ACAPI_MenuItem_SetMenuItemFlags (&itemRef, &itemFlags);
}      // EnableACMenuItem

ACAPI_MenuItem_GetMenuItemText()

GSErrCode ACAPI_MenuItem_GetMenuItemText	(	const API_MenuItemRef *	menuItemRef,
		char *	itemText,
		GS::UniString *	itemUniText = nullptr )

Returns the text of the specified menu item.

Parameters

menuItemRef	[in] Identifies the menu item.
itemText	[out] Menu item text (if you don't pass itemUniText).
itemUniText	[out] Optional Unicode menu item text to set.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - menuItemRef or both itemText and itemUniText are nullptr
• APIERR_BADINDEX - the specified menu item does not belong to the caller add-on

Remarks

This function is used to get the text of a menu item which belongs to the caller API tool add-on. The menu item is referenced with the resource ID and the string number. To change the text of a menu item use the ACAPI_MenuItem_SetMenuItemText function.

Example

void ReportChosenCommand (short menuResID, short itemInd)
{
    API_MenuItemRef itemRef {};
    char itemStr [256], message [256];
 
    itemRef.menuResID = menuResID;
    itemRef.itemIndex = itemInd;
    if (ACAPI_MenuItem_GetMenuItemText (&itemRef, itemStr) == NoError) {
        sprintf (message, "You have chosen the %s command", itemStr);
        ACAPI_WriteReport (itemStr, true);
    }
}

ACAPI_MenuItem_InstallMenuHandler()

GSErrCode ACAPI_MenuItem_InstallMenuHandler	(	short	menuStrResID,
		APIMenuCommandProc *	handlerProc )

Installs a callback procedure for handling the add-on's menu commands.

Parameters

menuStrResID	[in] An identifier of the menu to install the callback procedure for. This should be the same what you used in the ACAPI_MenuItem_RegisterMenu as a menu string resource number in the RegisterInterface function.
handlerProc	[in] The callback function to handle the menu commands.

Returns

• NoError - The function has completed with success.

Remarks

This function should be called in the Initialize function of your add-on. It installs the callback function which is called when the user chooses one of your menu commands.

Example

// -----------------------------------------------------------------------------
// Called when the add-on has been loaded into memory
// -----------------------------------------------------------------------------
GSErrCode Initialize (void)
 
{
    GSErrCode   err = NoError;
 
    err = ACAPI_MenuItem_InstallMenuHandler (32500, CustomAPIMenuCommandProc);
 
    return err;
}

ACAPI_MenuItem_RegisterMenu()

GSErrCode ACAPI_MenuItem_RegisterMenu	(	short	menuStrResID,
		short	promptStrResID,
		APIMenuCodeID	menuPosCode,
		GSFlags	menuFlags )

Registers the menu items of the add-on.

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

Returns

• NoError - The function has completed with success.

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_MenuItem_InstallMenuHandler 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#' 32800 "Menu strings" {
/* [  1] */ "Show Selections^ES^E3^ED^32800"
}
 
'STR#' 32620 "Status bar prompt strings" {
/* [  1] */ "Show Selections palette"
}

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

In the RegisterInterface function:

//------------------------------------------------------
// Interface definitions
//------------------------------------------------------
GSErrCode RegisterInterface ()
{
    // Register menu command
    return ACAPI_MenuItem_RegisterMenu (32600, 32620, MenuCode_Palettes, MenuFlag_Default);
}

ACAPI_MenuItem_SetMenuItemFlags()

GSErrCode ACAPI_MenuItem_SetMenuItemFlags	(	const API_MenuItemRef *	menuItemRef,
		GSFlags *	itemFlags,
		GS::UniString *	menuItemText = nullptr )

Sets the flag values of the specified menu item.

Parameters

menuItemRef	[in] Identifies the menu item.
itemFlags	[in] Menu item flags. Flag Value Meaning API_MenuItemDisabled Disable the menu item API_MenuItemChecked Check the menu item
menuItemText	[in] Optional Unicode menu item text to set.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - any of the parameters are nullptr
• APIERR_BADINDEX - the specified menu item does not belong to the caller add-on

Remarks

This function is used to set the current status of a menu item which belongs to the caller API tool add-on. The menu item is referenced with the resource ID and the string number. To get the current status of a menu item use the ACAPI_MenuItem_GetMenuItemFlags function. Note that the initial status of a menu item can also be set in the menu item string resources of the add-on. Refer to the STR# specification explained in the Required Resources paper in details.

Example

// -----------------------------------------------------------------------------
// Checkmark a menu item of the addon
// -----------------------------------------------------------------------------
 
void CheckACMenuItem (short itemInd, bool checked)
{
    API_MenuItemRef itemRef {};
    GSFlags itemFlags;
 
    itemRef.menuResID = 32500;
    itemRef.itemIndex = itemInd;
 
    itemFlags = 0;
    ACAPI_MenuItem_GetMenuItemFlags (&itemRef, &itemFlags);
    if (checked)
            itemFlags |= API_MenuItemChecked;
    else
            itemFlags &= ~API_MenuItemChecked;
    ACAPI_MenuItem_SetMenuItemFlags (&itemRef, &itemFlags);
}              // CheckACMenuItem

ACAPI_MenuItem_SetMenuItemText()

GSErrCode ACAPI_MenuItem_SetMenuItemText	(	const API_MenuItemRef *	menuItemRef,
		char *	itemText,
		GS::UniString *	itemUniText = nullptr )

Sets the text of the specified menu item.

Parameters

menuItemRef	[in] Identifies the menu item.
itemText	[in] Menu item text to set (if you don't pass itemUniText).
itemUniText	[in] Optional Unicode menu item text to set.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - menuItemRef or both itemText and itemUniText are nullptr
• APIERR_BADINDEX - the specified menu item does not belong to the caller add-on

Remarks

This function is used to set the text of a menu item which belongs to the caller API tool add-on. The menu item is referenced with the resource ID and the string number. To get the current text of a menu item use the ACAPI_MenuItem_GetMenuItemText function.

Example

void SetPaletteMenuText (short paletteItemInd, bool paletteIsVisible)
{
    API_MenuItemRef itemRef {};
    GS::UniString itemStr;
 
    if (paletteIsVisible)
        itemStr.Append ("Hide Palette");
    else
        itemStr.Append ("Show Palette");
 
    itemRef.menuResID = 32500;
    itemRef.itemIndex = paletteItemInd;
    ACAPI_MenuItem_SetMenuItemText (&itemRef, nullptr, &itemStr);
}

CreateMenuManager()

MenuManager ACAPI::UI::Menu::CreateMenuManager ( )

inline

A function to create menu manager instance, that lets you query and manipulate menu related data.

Returns

The menu manager instance.