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 add-on's menu items. 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 an 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 completed successfully.
APIERR_BADPARS - menuItemRef or both weText and weUniText are nullptr.

Remarks: This function is mainly used 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 an 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 completed successfully.
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 get.

Returns

NoError - The function completed successfully.
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] A menu identifier for which to install the callback procedure. You should use this in the ACAPI_MenuItem_RegisterMenu as a menu string resource number in the RegisterInterface function.
handlerProc	[in] The callback function handles the menu commands.

Returns

NoError - The function has completed successfully.

Remarks: This function should be called in your add-on's initialize function. 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 should be in the resource fork of the add-on.
promptStrResID	[in] The resource ID of the prompt string resource 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.
menuFlags	[in] Flags describing whether you want 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 successfully.

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 must 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 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 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"

}

The add-on may define its 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; instead, 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 existing menu title (e.g., Window) that 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 impact 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 completed successfully.
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 for 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 completed successfully.
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.

Classes

Functions

Detailed Description

Function Documentation

◆ ACAPI_MenuItem_AddMenuItemText()

◆ ACAPI_MenuItem_GetMenuItemFlags()

◆ ACAPI_MenuItem_GetMenuItemText()

◆ ACAPI_MenuItem_InstallMenuHandler()

◆ ACAPI_MenuItem_RegisterMenu()

◆ ACAPI_MenuItem_SetMenuItemFlags()

◆ ACAPI_MenuItem_SetMenuItemText()

◆ CreateMenuManager()