Add-On Integration

Functions to integrate the Add-On seamlessly into Archicad. They provide a way for the Add-On install callbacks to various possible events, integrate into existing dialogs (such as the Save and Open dialog) ans so on. More...

Classes
struct	API_MenuParams
	Describes the menu item that was chosen. More...
struct	API_IOParams
	Describes the file to work on in your callback procedure. More...
struct	API_PropertyObjectParams
	Defines parameters for the property handler function. More...
struct	API_AttributeManagerFormat
	Represents the data of an attribute manager format. More...
struct	API_PublishFormatData
	Represents the data of a publisher format. More...
struct	API_TranslatorNameConfig
	Represents a translator by its GUID and its name. More...

Typedefs
typedef GSErrCode __ACENV_CALL	APIMenuCommandProc(const API_MenuParams *menuParams)
	User supplied callback procedure for handling menu commands.
typedef GSErrCode __ACENV_CALL	APIIOCommandProc(const API_IOParams *ioParams)
	User supplied callback procedure for handling I/O operations.
typedef GSErrCode __ACENV_CALL	APIIO3DCommandProc(const API_IOParams *ioParams, Modeler::SightPtr sight)
	User supplied callback procedure for handling I/O operations.
typedef GSErrCode __ACENV_CALL	APIPanelCreateProc(Int32 refCon, const void *tabControl, void *data, void **tabPage)
	Callback procedure for creating custom tabpages.
typedef GSErrCode __ACENV_CALL	APIPanelDestroyProc(Int32 refCon, void *tabPage)
	Callback procedure for destroying custom tabpages.
typedef GSErrCode __ACENV_CALL	APIESYMCommandProc(const API_ESYMParams *esymParams)
	User supplied callback function for handling external symbols.
typedef GSErrCode __ACENV_CALL	APIModulCommandProc(GSHandle params, GSPtr resultData, bool silentMode)
	User supplied callback procedure for handling calls from other add-ons.
typedef GSErrCode __ACENV_CALL	APIPropertyObjectCommandProc(API_PropertyObjectParams *propertyParams)
	Callback function to handle the different property assignments.
typedef GSErrCode __ACENV_CALL	APISettingsCreateProc(void *uiData)
	Callback procedure for handle settings dialog create event.
typedef GSErrCode __ACENV_CALL	APISettingsDestroyProc(void *uiData)
	Callback procedure for handle settings dialog destroy event.
typedef GSErrCode __ACENV_CALL	APIPublishFormatCommandProc(void *uiData)
	Callback procedure for handle publish format command.
typedef GSErrCode __ACENV_CALL	APIModulDataMergeHandlerProc(API_MDSetCmd mode, const GS::UniString &modulName, const API_ModulData *originalInfo, const API_ModulData *toMergeInfo, API_ModulData *destInfo)
	User supplied callback procedure for handling module data merge operations.
typedef GSErrCode __ACENV_CALL	APIModulDataSaveOldFormatHandlerProc(API_FTypeID planFileType, GS::HashTable< GS::UniString, API_ModulData * > &modulesToSave)
	User supplied callback procedure for converting modules into previous format.
typedef GSErrCode __ACENV_CALL	APIElemSetSaveOldFormatHandlerProc(API_FTypeID planFileType, const GSPtr dataPtr, GSPtr *oldDataPtr)
	User supplied callback function for handling backward conversion on user data attached to elements.
typedef GSErrCode __ACENV_CALL	APINavigatorAddOnViewPointDataMergeHandlerProc(const GS::Array< API_NavigatorAddOnViewPointData > &sourceVPDataArray)
	User supplied callback procedure for handling Navigator AddOn viewpoint merge operations.
typedef GSErrCode __ACENV_CALL	APINavigatorAddOnViewPointDataSaveOldFormatHandlerProc(API_FTypeID planFileType, const GS::Array< API_NavigatorAddOnViewPointData > &currentFormatVPDataArray, GS::Array< API_NavigatorAddOnViewPointData > &oldFormatVPDataArray)
	User supplied callback procedure for converting Navigator AddOn viewpoints into older format.
typedef GSErrCode __ACENV_CALL	APINavigatorAddOnViewPointDataConvertNewFormatHandlerProc(API_FTypeID planFileType, const GS::Array< API_NavigatorAddOnViewPointData > &oldFormatVPDataArray, GS::Array< API_NavigatorAddOnViewPointData > &currentFormatVPDataArray)
	User supplied callback procedure for converting Navigator AddOn viewpoints into current format.
typedef bool __ACENV_CALL	APIClassificationVisibilityHandlerProc(API_ClassificationVisibilityMode visibilityMode, const GS::Array< API_Guid > &classificationGuids, const API_Guid &classificationItemGuid)
	Callback function to handle the visibility of a classification.
typedef bool __ACENV_CALL	APIPropertyVisibilityHandlerProc(API_PropertyVisibilityMode visibilityMode, const GS::Array< API_Guid > &classificationGuids, const API_Guid &propertyDefinitionGuid)
	Callback function to handle the visibility of a property.
typedef GSErrCode __ACENV_CALL	APIPaletteControlCallBackProc(Int32 referenceID, API_PaletteMessageID messageID, GS::IntPtr param)
	User supplied callback function for handling special messages for modeless palettes.

Functions
GSErrCode __ACENV_CALL	ACAPI_AddOnAddOnCommunication_RegisterSupportedService (GSType cmdID, Int32 cmdVersion)
	Registers a command which can be used by other add-ons.
GSErrCode __ACENV_CALL	ACAPI_AddOnIntegration_RegisterRequiredService (const API_ModulID *modulID, GSType cmdID, Int32 cmdVersion)
	Check the availability of an other add-on's command.
GSErrCode __ACENV_CALL	ACAPI_MenuItem_RegisterMenu (short menuStrResID, short promptStrResID, APIMenuCodeID menuPosCode, GSFlags menuFlags)
	Registers the menu items of the add-on.
GSErrCode __ACENV_CALL	ACAPI_AddOnIntegration_RegisterFileType (Int32 refCon, GSType ftype, GSType fcreator, const char *extname, short iconResID, short descStrResID, short descStrResItemID, API_IOMethod methodFlags)
	Registers a file type for I/O type add-ons.
GSErrCode __ACENV_CALL	ACAPI_LibraryPart_RegisterSubtype (GSType signature, short templateFileResID, bool transparentNode, short stringResID, short smallIconResID, short largeIconResID, API_TBoxGroup toolGroupId, API_TBoxEnabled enableFlags, short defaultsResID)
	Registers a new library part subtype.
GSErrCode __ACENV_CALL	ACAPI_AddOnIntegration_RegisterSettingsPanel (Int32 refCon, const API_ElemType &tool, short iconId, short stringId, short pageId, short growType=0, bool visibleByDefault=false)
	Appends a custom panel to an element settings dialog.
GSErrCode __ACENV_CALL	ACAPI_AddOnIntegration_RegisterAttributePanel (Int32 refCon, API_AttrTypeID attr, short iconId, short stringId, short pageId, short growType=0)
	Appends a custom panel to an attribute settings dialog.
GSErrCode __ACENV_CALL	ACAPI_AddOnIntegration_RegisterInfoBoxPanel (Int32 refCon, const API_ElemType &tool, short stringId, short pageId, bool visibleByDefault=false)
	Appends a custom panel to the info box.
GSErrCode __ACENV_CALL	ACAPI_LibraryPart_RegisterESYM (GSType signature, API_LibTypeID typeID, short stringResID)
	Registers an external symbol type with Archicad.
GSErrCode __ACENV_CALL	ACAPI_Property_RegisterPropertyObjectHandler (short assignStrResID)
	Registers a property handler.
GSErrCode __ACENV_CALL	ACAPI_AddOnIntegration_RegisterBuiltInLibrary (void)
	Registers built-in library parts to be loaded.
GSErrCode __ACENV_CALL	ACAPI_AddOnIntegration_RegisterModulDataHandler (void)
	Registers the add-on to be called for merging and converting its moduldata.
GSErrCode __ACENV_CALL	ACAPI_AddOnIntegration_RegisterClassificationVisibilityHandler (void)
	Tells Archicad that your add-on wants to modify classification visibility.
GSErrCode __ACENV_CALL	ACAPI_Property_RegisterPropertyVisibilityHandler (void)
	Tells Archicad that your add-on wants to modify property visibility.
GSErrCode __ACENV_CALL	ACAPI_AddOnIntegration_RegisterNavigatorAddOnViewPointDataHandler (void)
	Registers the add-on to be called when Navigator AddOn viewpoints are merged, saved to older format, or converted from older format to current format.
GSErrCode __ACENV_CALL	ACAPI_AddOnIntegration_RegisterSettingsObserver (const API_ElemType &tool)
	Create an observer to an element settings dialog.
GSErrCode __ACENV_CALL	ACAPI_AddOnIntegration_RegisterAttributeImportFormat (const API_AttributeManagerFormat &formatData)
	Registers an attribute manager format which can be used in attribute manager import.
GSErrCode __ACENV_CALL	ACAPI_AddOnIntegration_RegisterPublishFormat (const API_PublishFormatData &formatData)
	Registers a publish format which can be used in publisher tree.
GSErrCode __ACENV_CALL	ACAPI_AddOnIntegration_InstallModulCommandHandler (GSType cmdID, Int32 cmdVersion, APIModulCommandProc *handlerProc)
	Installs a callback for handling command calls from other add-ons.
GSErrCode __ACENV_CALL	ACAPI_MenuItem_InstallMenuHandler (short menuStrResID, APIMenuCommandProc *handlerProc)
	Installs a callback procedure for handling the add-on's menu commands.
GSErrCode __ACENV_CALL	ACAPI_AddOnIntegration_InstallFileTypeHandler (GSType cmdID, APIIOCommandProc *handlerProc)
	Installs a callback procedure for handling file operations.
GSErrCode __ACENV_CALL	ACAPI_AddOnIntegration_InstallFileTypeHandler3D (GSType cmdID, APIIO3DCommandProc *handlerProc)
	Installs a callback procedure for handling file operations.
GSErrCode __ACENV_CALL	ACAPI_AddOnIntegration_InstallPanelHandler (Int32 refCon, APIPanelCreateProc *handlerCreateProc, APIPanelDestroyProc *handlerDestroyProc)
	Installs the creation and destroy handlers for the registered custom settings panel.
GSErrCode __ACENV_CALL	ACAPI_LibraryPart_InstallESYMHandler (GSType signature, APIESYMCommandProc *handlerProc)
	Installs a callback for handling external symbols.
GSErrCode __ACENV_CALL	ACAPI_Property_InstallPropertyObjectHandler (short strResID, APIPropertyObjectCommandProc *propertyCommandProc)
	Installs the property handler function for the given menu item.
GSErrCode __ACENV_CALL	ACAPI_AddOnIntegration_InstallModulDataMergeHandler (APIModulDataMergeHandlerProc *mergeHandlerProc)
	Installs a callback procedure for handling the module data merge operations.
GSErrCode __ACENV_CALL	ACAPI_AddOnIntegration_InstallModulDataSaveOldFormatHandler (APIModulDataSaveOldFormatHandlerProc *modulDataSaveOldFormatProc)
	Installs a callback procedure for converting module data into older format.
GSErrCode __ACENV_CALL	ACAPI_AddOnIntegration_InstallElemSetSaveOldFormatHandler (APIElemSetSaveOldFormatHandlerProc *elemSetSaveOldFormatProc)
	Installs a callback procedure for handling the converison of the user data, the addOn attached to an elemeset.
GSErrCode __ACENV_CALL	ACAPI_AddOnIntegration_InstallNavigatorAddOnViewPointDataMergeHandler (APINavigatorAddOnViewPointDataMergeHandlerProc *mergeHandlerProc)
	Installs a callback procedure for handling the Navigator AddOn viewpoint merge operations.
GSErrCode __ACENV_CALL	ACAPI_AddOnIntegration_InstallNavigatorAddOnViewPointDataSaveOldFormatHandler (APINavigatorAddOnViewPointDataSaveOldFormatHandlerProc *saveOldFormatProc)
	Installs a callback procedure for converting Navigator AddOn viewpoints into older format.
GSErrCode __ACENV_CALL	ACAPI_AddOnIntegration_InstallNavigatorAddOnViewPointDataConvertNewFormatHandler (APINavigatorAddOnViewPointDataConvertNewFormatHandlerProc *convertNewFormatProc)
	Installs a callback procedure for converting Navigator AddOn viewpoints into current format.
GSErrCode __ACENV_CALL	ACAPI_AddOnIntegration_InstallSettingsHandler (const API_ElemType &tool, APISettingsCreateProc *handlerCreateProc, APISettingsDestroyProc *handlerDestroyProc)
	Installs the create and destroy handlers for the registered settings observer.
GSErrCode __ACENV_CALL	ACAPI_AddOnIntegration_InstallClassificationVisibilityHandler (APIClassificationVisibilityHandlerProc *handlerProc)
	Installs the classification visibility handler function.
GSErrCode __ACENV_CALL	ACAPI_Property_InstallPropertyVisibilityHandler (APIPropertyVisibilityHandlerProc *handlerProc)
	Installs the property visibility handler function.
GSErrCode __ACENV_CALL	ACAPI_AddOnIntegration_InstallPublisherSaveMethod (const char *mimeType, SaveProc *saveProc)
	Installs the save methods for the Publisher.
GSErrCode __ACENV_CALL	ACAPI_AddOnIntegration_InstallPublisherSaveOption (const char *mimeType, SaveOptionProc *saveOptionProc)
	Installs the option methods for the Publisher.
GSErrCode __ACENV_CALL	ACAPI_AddOnIntegration_InstallPublisherTranslatorGetter (const char *mimeType, TranslatorGetterProc *translatorGetterProc)
	Installs the translator getter function for the Publisher.
GSErrCode __ACENV_CALL	ACAPI_AddOnIntegration_InstallPublisherDefaultTranslatorGetter (const char *mimeType, DefaultTranslatorGetterProc *defaultTranslatorGetterProc)
	Installs the default translator getter function for the Publisher.
GSErrCode __ACENV_CALL	ACAPI_AddOnIntegration_InstallAttrManagerImportMethod (const GS::UniString &fileExtension, ImportAttrProc *importProc)
	Installs the import method for the Attribute Manager.
void __ACENV_CALL	ACAPI_KeepInMemory (bool keepIn)
	Instructs the host application to keep the add-on in the memory after execution.
GSErrCode __ACENV_CALL	ACAPI_RegisterModelessWindow (Int32 referenceID, APIPaletteControlCallBackProc *callBackProc, GSFlags controlFlags, const API_Guid &paletteGuid=APINULLGuid)
	Registers a modeless palette in the API.
GSErrCode __ACENV_CALL	ACAPI_ActivatePropertyObjectHandler (short strResID, bool active)
	Activates or deactivates an add-on's property handler.

Detailed Description

Functions to integrate the Add-On seamlessly into Archicad. They provide a way for the Add-On install callbacks to various possible events, integrate into existing dialogs (such as the Save and Open dialog) ans so on.

Typedef Documentation

APIClassificationVisibilityHandlerProc

typedef bool __ACENV_CALL APIClassificationVisibilityHandlerProc(API_ClassificationVisibilityMode visibilityMode, const GS::Array< API_Guid > &classificationGuids, const API_Guid &classificationItemGuid)

Callback function to handle the visibility of a classification.

Parameters

visibilityMode	[in] specifies what should the callback function return. Has one of the following values: API_ClassificationVisibilityMode Meaning APIClassVis_IsEnabled The callback function should return true if the visibility handling is enabled. APIClassVis_IsClassificationVisible The callback function should return true if the given classification is visible.
classificationGuids	[in] the classification guids of the current element.
classificationItemGuid	[in] the guid of the current classification.

Returns

• true - The result if it was successfull.

APIElemSetSaveOldFormatHandlerProc

typedef GSErrCode __ACENV_CALL APIElemSetSaveOldFormatHandlerProc(API_FTypeID planFileType, const GSPtr dataPtr, GSPtr *oldDataPtr)

User supplied callback function for handling backward conversion on user data attached to elements.

Parameters

planFileType	[in] File type's ID of the save process
dataPtr	[in] Pointer to the attached user data
oldDataPtr	[out] Pointer to the backward converted user data

Returns

• NoError - The function has completed with success.

Remarks

oldDataPtr is nullptr on call, and should be allocated in the function. If it is nullptr on return, the used data will be deleted from the saved plan.

APIESYMCommandProc

typedef GSErrCode __ACENV_CALL APIESYMCommandProc(const API_ESYMParams *esymParams)

User supplied callback function for handling external symbols.

Parameters

esymParams

[in] This structure contains the various parameters identifying the external symbol (type, index) and the type of operation (new/edit).

Returns

• NoError - The function has completed with success.

Remarks

This is the function which will be called when your add-on installed it with ACAPI_LibraryPart_InstallESYMHandler.

APIIO3DCommandProc

typedef GSErrCode __ACENV_CALL APIIO3DCommandProc(const API_IOParams *ioParams, Modeler::SightPtr sight)

User supplied callback procedure for handling I/O operations.

Parameters

ioParams	[in] This structure contains the various parameters identifying the file to be opened or saved.
sight	[in] The 3D sight pointer.

Returns

• NoError - The function has completed with success.

Remarks

This is the function which will be called when your add-on installed it with ACAPI_AddOnIntegration_InstallFileTypeHandler3D.

APIIOCommandProc

typedef GSErrCode __ACENV_CALL APIIOCommandProc(const API_IOParams *ioParams)

User supplied callback procedure for handling I/O operations.

Parameters

ioParams

[in] This structure contains the various parameters identifying the file to be opened or saved.

Returns

• NoError - The function has completed with success.

Remarks

This is the function which will be called when your add-on installed it with ACAPI_AddOnIntegration_InstallFileTypeHandler. From Archicad 19 you have to enclose the element creation creating in an undoable command scope during a merge file operation. In case you pass empty string parameter to ACAPI_CallUndoableCommand, Archicad replaces it with the default "Paste" undo string. From Archicad 9 merge and open operations can be initiated also with drag drop:

• dropping a file of a registered type onto the frame window (on Windows) results an IO_OPEN method call
• dropping a file of a registered type onto the visible client area of a drawing (floorplan, section, detail) window generates an IO_MERGE operation. In this case the fromDragDrop flag of API_IOParams is set, and the dropOffset field contains the vector that points to the dropping position from the origin. The false value in the noDialog parameter means that the drag drop operation was performed with the right mouse button or with pressing a modifier key (Ctrl on Windows, Alt on the Macintosh).

APIMenuCommandProc

typedef GSErrCode __ACENV_CALL APIMenuCommandProc(const API_MenuParams *menuParams)

User supplied callback procedure for handling menu commands.

Parameters

menuParams

[in] This structure contains the various parameters identifying the menu command.

Returns

• NoError - The function has completed with success.

Remarks

This is the function which will be called when your add-on installed it with ACAPI_MenuItem_InstallMenuHandler. For tool type add-ons, this is the replacement for the original DoCommand function.

APIModulCommandProc

typedef GSErrCode __ACENV_CALL APIModulCommandProc(GSHandle params, GSPtr resultData, bool silentMode)

User supplied callback procedure for handling calls from other add-ons.

Parameters

params	[in/out] This structure contains the parameters of the command passed onto your add-on.
resultData	[out] This structure contains parameters passed back to the caller add-on.
silentMode	[in] This flag tells the add-on to work "silently", i.e. skip all dialogs and warning messages.

Returns

• NoError - The function has completed with success.

Remarks

Your add-on can provide services to other add-ons by calling ACAPI_AddOnAddOnCommunication_RegisterSupportedService in its RegisterInterface function. After that any add-on can call your add-on which knows the command's interface; and this function will be the entry point of your add-on in this case.

APIModulDataMergeHandlerProc

typedef GSErrCode __ACENV_CALL APIModulDataMergeHandlerProc(API_MDSetCmd mode, const GS::UniString &modulName, const API_ModulData *originalInfo, const API_ModulData *toMergeInfo, API_ModulData *destInfo)

User supplied callback procedure for handling module data merge operations.

Parameters

mode	[in] The operation the add-on is called for.
modulName	[in] Identifier name of the modul data (for modules stored in previous versions this parameter is always empty string).
originalInfo	[in] The original module data in the to which data has to be merged into.
toMergeInfo	[in] The incoming module data.
destInfo	[out] The result module data. Your add-on should put the result of the merge in here.

Returns

• NoError - The function has completed with success.

Remarks

This is the function to be called when two conflicting modules need to be merged by your add-on. The handler function pointer must be passed with ACAPI_AddOnIntegration_InstallModulDataMergeHandler. It is also necessary to register this functionality of the add-on with calling ACAPI_AddOnIntegration_RegisterModulDataHandler. The details of the notification process are described in the ModulData Manager section.

APIModulDataSaveOldFormatHandlerProc

typedef GSErrCode __ACENV_CALL APIModulDataSaveOldFormatHandlerProc(API_FTypeID planFileType, GS::HashTable< GS::UniString, API_ModulData * > &modulesToSave)

User supplied callback procedure for converting modules into previous format.

Parameters

planFileType	[in] The old format plan version the project is being saved. In Archicad 13 this can be only APIFType_PlanFile1200.
modulesToSave	[out] A hash table to retrieve the converted module data.

Returns

• NoError - The function has completed with success.

Remarks

In order to save the add-on's moduldata in the proper format into a previous version project file, you need to implement this callback function, and pass it to Archicad with ACAPI_AddOnIntegration_InstallModulDataSaveOldFormatHandler during the Initialize phase. It is also necessary to notify Archicad about this capability of the add-on by calling ACAPI_AddOnIntegration_RegisterModulDataHandler from the RegisterInterface function. This handler function is called whenever the user saves the project into an older format, and tha add-on has any moduldata stored currently into the project. The data should be constructed according to the required version into a dynamically allocated API_ModulData structure, and the pointer of this structure should be pushed into the modulesToSave table. Notice that more modules can be added, should be identified with different names. In Archicad versions prior to 13 were able to store only one moduldata per add-on, this moduldata should be stored with empty string identifier (""). The memory allocated for the converted moduldata by the add-on's handler function will be released by the caller application. For further details of the notification process refer to the ModulData Manager section.

APINavigatorAddOnViewPointDataConvertNewFormatHandlerProc

typedef GSErrCode __ACENV_CALL APINavigatorAddOnViewPointDataConvertNewFormatHandlerProc(API_FTypeID planFileType, const GS::Array< API_NavigatorAddOnViewPointData > &oldFormatVPDataArray, GS::Array< API_NavigatorAddOnViewPointData > &currentFormatVPDataArray)

User supplied callback procedure for converting Navigator AddOn viewpoints into current format.

Parameters

planFileType	[in] The old format plan version being opened.
oldFormatVPDataArray	[in] Navigator AddOn viewpoints in old format.
currentFormatVPDataArray	[out] Navigator AddOn viewpoints in current format. These will be visible after the plan finished opening.

Returns

• NoError - The function has completed with success.

Remarks

In order to convert older version Navigator AddOn viewpoints into current version during plan file opening, you need to implement this callback function, and install it with ACAPI_AddOnIntegration_InstallNavigatorAddOnViewPointDataConvertNewFormatHandler in the Initialize function. It is also necessary to call ACAPI_AddOnIntegration_RegisterNavigatorAddOnViewPointDataHandler from the RegisterInterface function. This handler function is called by Archicad whenever the user opens a plan file, that is in older format. Inside the function the converted viewpoints should be constructed in API_NavigatorAddOnViewPointData structures in the format required by current version of this AddOn, and these structures should be pushed into currentFormatVPDataArray. When Archicad calls this function, it passes an empty currentFormatVPDataArray. If you need to delete a Navigator AddOn viewpoint (e.g. it cannot be converted to current version) then simply do not push it into currentFormatVPDataArray. Note, that if you do not push a root or group, all its descendants will be deleted, even if some descendants were pushed into currentFormatVPDataArray. If you push a viewpoint data with an invalid guid (i.e. one that does not designate an existing root, group or leaf node), it will be skipped, and not created. Order of the items in currentFormatVPDataArray is irrelevant. The hierarchy cannot be changed during conversion. The parentGuid of the pushed structures will be ignored. The item type of the Navigator viewpoints cannot be changed during conversion. The itemType of the pushed structures will be ignored.

APINavigatorAddOnViewPointDataMergeHandlerProc

typedef GSErrCode __ACENV_CALL APINavigatorAddOnViewPointDataMergeHandlerProc(const GS::Array< API_NavigatorAddOnViewPointData > &sourceVPDataArray)

User supplied callback procedure for handling Navigator AddOn viewpoint merge operations.

Parameters

sourceVPDataArray

[in] The list of the Navigator AddOn viewpoints to be merged. These viewpoint roots, groups or leaf nodes come from the merged plan file.

Returns

• NoError - The function has completed with success.

Remarks

This function is called by Archicad when a file merge operation is performed. The handler function should merge the source objects into the project database by calling Navigator AddOn viewpoint related API functions, e.g. ACAPI_Navigator_CreateNavigatorVPItem, ACAPI_Navigator_ChangeNavigatorVPItem.

APINavigatorAddOnViewPointDataSaveOldFormatHandlerProc

typedef GSErrCode __ACENV_CALL APINavigatorAddOnViewPointDataSaveOldFormatHandlerProc(API_FTypeID planFileType, const GS::Array< API_NavigatorAddOnViewPointData > &currentFormatVPDataArray, GS::Array< API_NavigatorAddOnViewPointData > &oldFormatVPDataArray)

User supplied callback procedure for converting Navigator AddOn viewpoints into older format.

Parameters

planFileType	[in] The old format plan version, the project is being saved into.
currentFormatVPDataArray	[in] Navigator AddOn viewpoints in current format.
oldFormatVPDataArray	[out] Navigator AddOn viewpoints in old format. This will be saved into the old format plan.

Returns

• NoError - The function has completed with success.

Remarks

In order to save the Navigator AddOn viewpoints into a previous version project file, you need to implement this callback function, and install it with ACAPI_AddOnIntegration_InstallNavigatorAddOnViewPointDataSaveOldFormatHandler in the Initialize function. It is also necessary to call ACAPI_AddOnIntegration_RegisterNavigatorAddOnViewPointDataHandler from the RegisterInterface function. This handler function is called by Archicad whenever the user saves the project into an older format. Inside the function the converted viewpoints should be constructed in API_NavigatorAddOnViewPointData structures in the format required by the previous version of this AddOn, and these structures should be pushed into oldFormatVPDataArray. When Archicad calls this function, it passes an empty oldFormatVPDataArray. If you need to delete a Navigator AddOn viewpoint (e.g. it cannot be converted to previous version) then simply do not push it into oldFormatVPDataArray. Note, that if you do not push a root or group, all its descendants will be deleted, even if some descendants were pushed into oldFormatVPDataArray. If you push a viewpoint data with an invalid guid (i.e. one that does not designate an existing root, group or leaf node), it will be skipped, and not created. Order of the items in oldFormatVPDataArray is irrelevant. The hierarchy cannot be changed during conversion. The parentGuid of the pushed structures will be ignored. The item type of the Navigator viewpoints cannot be changed during conversion. The itemType of the pushed structures will be ignored.

APIPaletteControlCallBackProc

typedef GSErrCode __ACENV_CALL APIPaletteControlCallBackProc(Int32 referenceID, API_PaletteMessageID messageID, GS::IntPtr param)

User supplied callback function for handling special messages for modeless palettes.

Parameters

referenceID	[in] The unique ID that identifies the modeless palette.
messageID	[in] Event to be handled in the palette control callback procedure.
param	[out] Return parameter, used for APIPalMsg_IsPaletteVisible.

Returns

• NoError - The function has completed with success.

Remarks

You can register this function with ACAPI_RegisterModelessWindow. From now on, it will be your responsibility to adjust the behavior of your palette to the other palettes. The following types of events will come for your custom window:

Message type	Description
APIPalMsg_ClosePalette	The API asks the add-on to close its palette.
APIPalMsg_HidePalette_Begin	Your palette should be hidden for some reason, e.g. the user chose Hide All Palettes from the menu.
APIPalMsg_HidePalette_End	The palette can be shown again if needed.
APIPalMsg_DisableItems_Begin	Certain palette items should be disabled, because the user is performing an input. This is necessary because you shouldn't make any modifications to the database during input.
APIPalMsg_DisableItems_End	The reason behind APIPalMsg_DisableItems_Begin is gone; you can enable the items on the palette.
APIPalMsg_OpenPalette	Sent when the palette should be opened automatically as set in the Work Environment. Your palette should pass a GUID when created: DG::Palette (resourceId, paletteGuid) to make this work.
APIPalMsg_IsPaletteVisible	The Work Environment queries the palette for its visibility status on closing the current document/quitting the application. If you return true in param (really a bool*), then Archicad will send a APIPalMsg_OpenPalette to your add-on on next launch, so that you can re-open your add-on's palette.

APIPanelCreateProc

typedef GSErrCode __ACENV_CALL APIPanelCreateProc(Int32 refCon, const void *tabControl, void *data, void **tabPage)

Callback procedure for creating custom tabpages.

Parameters

refCon	[in] reference number passed by the panel registration function
tabControl	[in] pointer to the constructed DG::TabControl dialog item
data	[in] pointer to an interface which provides access to the user data
tabPage	[out] pointer to the tabpage object instance created in the callback function

Returns

• NoError - The function has completed with success.

Remarks

When the additional panel is being created, a callback function is called which lets the add-on initialize the tabpage item with the associated user data and an attached observer to it. Install this handler function with ACAPI_AddOnIntegration_InstallPanelHandler in order to be called to create your tabpage identified with refCon and attach the observer to it when the settings dialog is being constructed.

APIPanelDestroyProc

typedef GSErrCode __ACENV_CALL APIPanelDestroyProc(Int32 refCon, void *tabPage)

Callback procedure for destroying custom tabpages.

Parameters

refCon	[in] reference number passed by the panel registration function
tabPage	[in] pointer to the tabpage object instance

Returns

• NoError - The function has completed with success.

Remarks

When the additional panel is being destroyed, a callback function is called in order to detach the tabpage observer, destruct the tabpage item, and free the associated user data. Install this handler function with ACAPI_AddOnIntegration_InstallPanelHandler in order to be called to detach the observer and destroy your tabpage identified with refCon when the settings dialog closes.

APIPropertyObjectCommandProc

typedef GSErrCode __ACENV_CALL APIPropertyObjectCommandProc(API_PropertyObjectParams *propertyParams)

Callback function to handle the different property assignments.

Parameters

propertyParams

[in] the parameters of the property assignment.

Returns

• NoError - The function has completed with success.

APIPropertyVisibilityHandlerProc

typedef bool __ACENV_CALL APIPropertyVisibilityHandlerProc(API_PropertyVisibilityMode visibilityMode, const GS::Array< API_Guid > &classificationGuids, const API_Guid &propertyDefinitionGuid)

Callback function to handle the visibility of a property.

Parameters

visibilityMode	[in] specifies what should the callback function return. Has one of the following values: API_PropertyVisibilityMode Meaning APIPropVis_IsEnabled The callback function should return true if the visibility handling is enabled. APIPropVis_IsPropertyVisible The callback function should return true if the given property is visible.
classificationGuids	[in] the classification guids of the current element.
propertyDefinitionGuid	[in] the guid of the current property.

Returns

• bool - The result.

APIPublishFormatCommandProc

typedef GSErrCode __ACENV_CALL APIPublishFormatCommandProc(void *uiData)

Callback procedure for handle publish format command.

Parameters

uiData

[in/out] pointer to the tool UI data.

Returns

• NoError - The function has completed with success.

Remarks

When the publish called from a type, then this function will be called.

APISettingsCreateProc

typedef GSErrCode __ACENV_CALL APISettingsCreateProc(void *uiData)

Callback procedure for handle settings dialog create event.

Parameters

uiData

[in/out] pointer to the tool UI data. This UI data can be used to get the current settings and to attach an observer which monitors changes of the settings dialog.

Returns

• NoError - The function has completed with success.

Remarks

When the settings dialog is being created, the callback function is called which lets the add-on get the current settings and attach an observer to the tool UI data. Install this handler function with ACAPI_AddOnIntegration_InstallSettingsHandler.

APISettingsDestroyProc

typedef GSErrCode __ACENV_CALL APISettingsDestroyProc(void *uiData)

Callback procedure for handle settings dialog destroy event.

Parameters

uiData

[in/out] pointer to the tool UI data.

Returns

• NoError - The function has completed with success.

Remarks

When the settings dialog is being destroyed, a callback function is called in order to detach tool UI data observer. Install this handler function with ACAPI_AddOnIntegration_InstallSettingsHandler.

Function Documentation

ACAPI_ActivatePropertyObjectHandler()

GSErrCode __ACENV_CALL ACAPI_ActivatePropertyObjectHandler	(	short	strResID,
		bool	active
	)

Activates or deactivates an add-on's property handler.

Parameters

strResID	[in] tells for which property handler is this command issued
active	[in] turns the property handler on/off

Returns

• NoError - The function has completed with success.

Remarks

Only one property handler can be active in Archicad at a time. The return value of this functions depends on the user, as a dialog pops up when you issue this command. When the function returns, you should adjust your menu items accordingly. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

Example

if (ACAPI_ActivatePropertyObjectHandler (stringResID, !checkedAssignProperty) == NoError) {
 
    checkedAssignProperty = !checkedAssignProperty;
 
    API_MenuItemRef mir;
    Int32           flags;
 
    BNZeroMemory (&mir, sizeof (API_MenuItemRef));
    mir.menuResID = menuResID;
    mir.itemIndex = 1;
    ACAPI_Interface (APIIo_GetMenuItemFlagsID, &mir, &flags);
    if (checkedAssignProperty)
        flags = flags | API_MenuItemChecked;
    else
        flags = flags & !API_MenuItemChecked;
 
    ACAPI_Interface (APIIo_SetMenuItemFlagsID, &mir, &flags);
}

ACAPI_AddOnAddOnCommunication_RegisterSupportedService()

GSErrCode __ACENV_CALL ACAPI_AddOnAddOnCommunication_RegisterSupportedService	(	GSType	cmdID,
		Int32	cmdVersion
	)

Registers a command which can be used by other add-ons.

Parameters

cmdID	[in] The command identifier of the supported service.
cmdVersion	[in] The command version of the supported service.

Returns

• NoError - The function has completed with success.

Remarks

The function registers one of your add-on's command, and makes it avaliable for other add-ons. This should be called from the RegisterInterface function of the add-on.

Example

//------------------------------------------------------
// Interface definitions
//------------------------------------------------------
GSErrCode __ACENV_CALL  RegisterInterface (void)
 
{
    GSErrCode   err;
 
    //
    // Register command services
    //
    err = ACAPI_AddOnAddOnCommunication_RegisterSupportedService ('DWFO', 4L);
 
    return err;
}               // RegisterInterface

ACAPI_AddOnIntegration_InstallAttrManagerImportMethod()

GSErrCode __ACENV_CALL ACAPI_AddOnIntegration_InstallAttrManagerImportMethod	(	const GS::UniString &	fileExtension,
		ImportAttrProc *	importProc
	)

Installs the import method for the Attribute Manager.

Since

Archicad 26

Parameters

fileExtension	The unique file extension which identifies the new import format.
importProc	Callback function, called when import a file with the registered extension.

Returns

• NoError - The function has completed with success.

Remarks

This function installs the callback function for the new attribute import format. The Attribute Manager will call the registered function, during the import command. Example Refer to the Attribute Test example project of the API Development Kit.

ACAPI_AddOnIntegration_InstallClassificationVisibilityHandler()

GSErrCode __ACENV_CALL ACAPI_AddOnIntegration_InstallClassificationVisibilityHandler

(

APIClassificationVisibilityHandlerProc *

handlerProc

)

Installs the classification visibility handler function.

Parameters

handlerProc

[in] The classification visibility handler function.

Returns

• NoError - The function has completed with success.

Remarks

This function should be called from the Initialize function of the add-on, after registering the classification handler with ACAPI_AddOnIntegration_RegisterClassificationVisibilityHandler.

Example

//------------------------------------------------------
// Called after the add-on has been loaded into memory
//------------------------------------------------------
GSErrCode __ACENV_CALL  APIMenuCommandProc_Main   (const API_MenuParams *menuParams);
bool      __ACENV_CALL  ClassificationVisibilityHandler (API_ClassificationVisibilityMode visibilityMode, const GS::Array<API_Guid>& classificationGuids, const API_Guid& classificationItemGuid);
 
GSErrCode __ACENV_CALL  Initialize (void)
{
    GSErrCode err = ACAPI_MenuItem_InstallMenuHandler (32500, APIMenuCommandProc_Main);
    if (err != NoError) {
        return err;
    }
 
    err = ACAPI_AddOnIntegration_InstallClassificationVisibilityHandler (ClassificationVisibilityHandler);
    if (err != NoError) {
        return err;
    }
 
    ACAPI_KeepInMemory (true);
    return NoError;
}

ACAPI_AddOnIntegration_InstallElemSetSaveOldFormatHandler()

GSErrCode __ACENV_CALL ACAPI_AddOnIntegration_InstallElemSetSaveOldFormatHandler

(

APIElemSetSaveOldFormatHandlerProc *

elemSetSaveOldFormatProc

)

Installs a callback procedure for handling the converison of the user data, the addOn attached to an elemeset.

Parameters

elemSetSaveOldFormatProc

[in] The callback function to handle the backward conversion

Returns

• NoError - The function has completed with success.

Remarks

The installed callback is called when the plan is saved back to an earlier version of Archicad. You can handle any change in the user data's here, to make it readable for previous version.

ACAPI_AddOnIntegration_InstallFileTypeHandler()

GSErrCode __ACENV_CALL ACAPI_AddOnIntegration_InstallFileTypeHandler	(	GSType	cmdID,
		APIIOCommandProc *	handlerProc
	)

Installs a callback procedure for handling file operations.

Parameters

cmdID	[in] An identifier of the file type to install the callback procedure for. This should be the same what you used in the ACAPI_AddOnIntegration_RegisterFileType as a reference number in the RegisterInterface function.
handlerProc	[in] The callback function to handle the different file operations.

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 your registered file format in one of the Open/Save/Merge dialogs.

Example

// -----------------------------------------------------------------------------
// Called when the add-on has been loaded into memory
// -----------------------------------------------------------------------------
GSErrCode __ACENV_CALL  Initialize (void)
 
{
    GSErrCode    err = NoError;
 
    err = ACAPI_AddOnIntegration_InstallFileTypeHandler (1, APIIOCommandProc);
 
    return err;
}   // Initialize

ACAPI_AddOnIntegration_InstallFileTypeHandler3D()

GSErrCode __ACENV_CALL ACAPI_AddOnIntegration_InstallFileTypeHandler3D	(	GSType	cmdID,
		APIIO3DCommandProc *	handlerProc
	)

Installs a callback procedure for handling file operations.

Parameters

cmdID	[in] An identifier of the file type to install the callback procedure for. This should be the same what you used in the ACAPI_AddOnIntegration_RegisterFileType as a reference number in the RegisterInterface function.
handlerProc	[in] The callback function to handle the different file operations.

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 your registered file format in one of the Open/Save dialogs.

Example

// -----------------------------------------------------------------------------
// Called when the add-on has been loaded into memory
// -----------------------------------------------------------------------------
GSErrCode __ACENV_CALL  Initialize (void)
 
{
    GSErrCode    err = NoError;
 
    err = ACAPI_AddOnIntegration_InstallFileTypeHandler3D (1, APIIOCommandProc);
 
    return err;
}   // Initialize

ACAPI_AddOnIntegration_InstallModulCommandHandler()

GSErrCode __ACENV_CALL ACAPI_AddOnIntegration_InstallModulCommandHandler	(	GSType	cmdID,
		Int32	cmdVersion,
		APIModulCommandProc *	handlerProc
	)

Installs a callback for handling command calls from other add-ons.

Parameters

cmdID	[in] An identifier of the command to install the callback procedure for. This should be the same what you used in the ACAPI_AddOnAddOnCommunication_RegisterSupportedService as the command identifier in the RegisterInterface function.
cmdVersion	[in] An identifier of the command to install the callback procedure for. This should be the same what you used in the ACAPI_AddOnAddOnCommunication_RegisterSupportedService as the command version number in the RegisterInterface function.
handlerProc	[in] The callback function to handle the command calls.

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 other add-ons would like to use the supported services of your add-on.

Example

// -----------------------------------------------------------------------------
// Called when the add-on has been loaded into memory
// -----------------------------------------------------------------------------
GSErrCode __ACENV_CALL  Initialize (void)
 
{
    GSErrCode    err = NoError;
 
    err = ACAPI_AddOnIntegration_InstallModulCommandHandler ('DWFI', 1, APIModulCommandProc);
 
    return err;
}   // Initialize

ACAPI_AddOnIntegration_InstallModulDataMergeHandler()

GSErrCode __ACENV_CALL ACAPI_AddOnIntegration_InstallModulDataMergeHandler

(

APIModulDataMergeHandlerProc *

mergeHandlerProc

)

Installs a callback procedure for handling the module data merge operations.

Parameters

mergeHandlerProc

[in] The callback procedure which will handle the module data merge. Can be nullptr ; this removes the installed callback.

Returns

• NoError - The function has completed with success.

Remarks

This function should be called in the Initialize function of your add-on to pass the pointer of the APIModulDataMergeHandlerProc callback routine implemented for resolving conflicts between two instances of the same custom data section of the add-on during a merge operation.

ACAPI_AddOnIntegration_InstallModulDataSaveOldFormatHandler()

GSErrCode __ACENV_CALL ACAPI_AddOnIntegration_InstallModulDataSaveOldFormatHandler

(

APIModulDataSaveOldFormatHandlerProc *

modulDataSaveOldFormatProc

)

Installs a callback procedure for converting module data into older format.

Parameters

modulDataSaveOldFormatProc

[in] The callback procedure to convert module data. Passing nullptr in this parameter uninstalls the previously installed handler function.

Returns

• NoError - The function has completed with success.

Remarks

This function should be called in the Initialize function of your add-on to pass the pointer of the APIModulDataSaveOldFormatHandlerProc callback routine implemented for converting modules of the add-on into previous format.

ACAPI_AddOnIntegration_InstallNavigatorAddOnViewPointDataConvertNewFormatHandler()

GSErrCode __ACENV_CALL ACAPI_AddOnIntegration_InstallNavigatorAddOnViewPointDataConvertNewFormatHandler

(

APINavigatorAddOnViewPointDataConvertNewFormatHandlerProc *

convertNewFormatProc

)

Installs a callback procedure for converting Navigator AddOn viewpoints into current format.

Parameters

convertNewFormatProc

[in] The callback procedure which will handle the Navigator AddOn viewpoints' conversion into current format. If nullptr is passed, an installed callback function is removed.

Returns

• NoError - The function has completed with success.

Remarks

This function should be called in the Initialize function of your AddOn.

ACAPI_AddOnIntegration_InstallNavigatorAddOnViewPointDataMergeHandler()

GSErrCode __ACENV_CALL ACAPI_AddOnIntegration_InstallNavigatorAddOnViewPointDataMergeHandler

(

APINavigatorAddOnViewPointDataMergeHandlerProc *

mergeHandlerProc

)

Installs a callback procedure for handling the Navigator AddOn viewpoint merge operations.

Parameters

mergeHandlerProc

[in] The callback procedure which will handle the Navigator AddOn viewpoint data merge. If nullptr is passed, an installed callback function is removed.

Returns

• NoError - The function has completed with success.

Remarks

This function should be called in the Initialize function of your AddOn.

ACAPI_AddOnIntegration_InstallNavigatorAddOnViewPointDataSaveOldFormatHandler()

GSErrCode __ACENV_CALL ACAPI_AddOnIntegration_InstallNavigatorAddOnViewPointDataSaveOldFormatHandler

(

APINavigatorAddOnViewPointDataSaveOldFormatHandlerProc *

saveOldFormatProc

)

Installs a callback procedure for converting Navigator AddOn viewpoints into older format.

Parameters

saveOldFormatProc

[in] The callback procedure which will handle the Navigator AddOn viewpoints' conversion into older format. If nullptr is passed, an installed callback function is removed.

Returns

• NoError - The function has completed with success.

Remarks

This function should be called in the Initialize function of your AddOn.

ACAPI_AddOnIntegration_InstallPanelHandler()

GSErrCode __ACENV_CALL ACAPI_AddOnIntegration_InstallPanelHandler	(	Int32	refCon,
		APIPanelCreateProc *	handlerCreateProc,
		APIPanelDestroyProc *	handlerDestroyProc
	)

Installs the creation and destroy handlers for the registered custom settings panel.

Parameters

refCon	[in] Panel reference number
handlerCreateProc	[in] Callback function, called when the panel is created.
handlerDestroyProc	[in] Callback function, called when the panel is destroyed.

Returns

• APIERR_REFUSEDPAR - There is no panel registered with refcon by the add-on.
• NoError - The function has completed with success.

Remarks

This function installs the callback functions for handling create/delete events of the dialog panel registered by ACAPI_AddOnIntegration_RegisterSettingsPanel, ACAPI_AddOnIntegration_RegisterInfoBoxPanel or ACAPI_AddOnIntegration_RegisterAttributePanel. The ACAPI_AddOnIntegration_InstallPanelHandler function should be called from Initialize. The 'create' handler is called when the panel is created. The handler must create the tabpage and the observer. The 'destroy' handler is called when the panel is destroyed. The handler must destroy the tabpage and the observer. For more details refer to the general description of Custom Panels in Settings Dialogs.

Example

Refer to the Panel_Test
 
example project of the API Development Kit.

ACAPI_AddOnIntegration_InstallPublisherDefaultTranslatorGetter()

GSErrCode __ACENV_CALL ACAPI_AddOnIntegration_InstallPublisherDefaultTranslatorGetter	(	const char *	mimeType,
		DefaultTranslatorGetterProc *	defaultTranslatorGetterProc
	)

Installs the default translator getter function for the Publisher.

Since

Archicad 26

Parameters

mimeType	The unique mimeType which identifies the new publish format
defaultTranslatorGetterProc	Callback function, called from the Organizer

Returns

• NoError - The function has completed with success.

Remarks

This function installs the callback functions for the new publish formats. The publisher will call the registered function, during the setup of the formats in the Organizer. Example Refer to the Format Register Test example project of the API Development Kit.

ACAPI_AddOnIntegration_InstallPublisherSaveMethod()

GSErrCode __ACENV_CALL ACAPI_AddOnIntegration_InstallPublisherSaveMethod	(	const char *	mimeType,
		SaveProc *	saveProc
	)

Installs the save methods for the Publisher.

Parameters

mimeType	The unique mimeType which identifies the new publish format
saveProc	Callback function, called in case of publishing

Returns

• NoError - The function has completed with success.

Remarks

This function installs the callback functions for the new publish formats. The publisher will call the registered function, during the publishing command. Example Refer to the Format Register Test example project of the API Development Kit.

ACAPI_AddOnIntegration_InstallPublisherSaveOption()

GSErrCode __ACENV_CALL ACAPI_AddOnIntegration_InstallPublisherSaveOption	(	const char *	mimeType,
		SaveOptionProc *	saveOptionProc
	)

Installs the option methods for the Publisher.

Parameters

mimeType	The unique mimeType which identifies the new publish format
saveOptionProc	Callback function, called in case of publishing

Returns

• NoError - The function has completed with success.

Remarks

This function installs the callback functions for the new publish formats. The Add-on can create his own option dialog, the settings are stored in API_Userdata structures. Example Refer to the Format Register Test example project of the API Development Kit.

ACAPI_AddOnIntegration_InstallPublisherTranslatorGetter()

GSErrCode __ACENV_CALL ACAPI_AddOnIntegration_InstallPublisherTranslatorGetter	(	const char *	mimeType,
		TranslatorGetterProc *	translatorGetterProc
	)

Installs the translator getter function for the Publisher.

Since

Archicad 26

Parameters

mimeType	The unique mimeType which identifies the new publish format
translatorGetterProc	Callback function, called from the Organizer

Returns

• NoError - The function has completed with success.

Remarks

This function installs the callback functions for the new publish formats. The publisher will call the registered function, during the setup of the formats in the Organizer. Example Refer to the Format Register Test example project of the API Development Kit.

ACAPI_AddOnIntegration_InstallSettingsHandler()

GSErrCode __ACENV_CALL ACAPI_AddOnIntegration_InstallSettingsHandler	(	const API_ElemType &	tool,
		APISettingsCreateProc *	handlerCreateProc,
		APISettingsDestroyProc *	handlerDestroyProc
	)

Installs the create and destroy handlers for the registered settings observer.

Since

Archicad 26

Parameters

tool	[in] The element type that identifies the settings dialog
handlerCreateProc	[in] Callback function, called when the settings dialog is created.
handlerDestroyProc	[in] Callback function, called when the settings dialog is destroyed.

Returns

• APIERR_BADPARS - No settings observer was registered for the settings dialog specified by tool and variaton.
• NoError - The function has completed with success.

Remarks

This function installs the callback functions for handling create/destroy events of the settings dialog observer registered by ACAPI_AddOnIntegration_RegisterSettingsObserver. The ACAPI_AddOnIntegration_InstallSettingsHandler function should be called from Initialize. The 'create' handler is called when the settings dialog is created. The 'destroy' handler is called when the settings dialog is destroyed. From version 26 the tool and variation parameters were merged into a single API_ElemType parameter.

Example

Refer to the Panel_Test
 
example project of the API Development Kit.

ACAPI_AddOnIntegration_RegisterAttributeImportFormat()

GSErrCode __ACENV_CALL ACAPI_AddOnIntegration_RegisterAttributeImportFormat

(

const API_AttributeManagerFormat &

formatData

)

Registers an attribute manager format which can be used in attribute manager import.

Since

Archicad 26

Parameters

formatData

[in] Stores parameters of the new attribute manager import format.

Returns

• NoError - The function has completed with success.

Remarks

For further informations read the documentation of API_AttributeManagerFormat structure.

Example

//------------------------------------------------------
// Interface definitions
//------------------------------------------------------
GSErrCode   __ACDLL_CALL    RegisterInterface (void)
{
    API_AttributeManagerFormat formatData = {};
    formatData.fileCreator  = 'GSAC';
    formatData.fileType     = 'TEXT';
    formatData.fileExtension    = "txt";
    formatData.popupText    = "Test txt file";
 
    return ACAPI_AddOnIntegration_RegisterAttributeImportFormat (formatData);
}

ACAPI_AddOnIntegration_RegisterAttributePanel()

GSErrCode __ACENV_CALL ACAPI_AddOnIntegration_RegisterAttributePanel	(	Int32	refCon,
		API_AttrTypeID	attr,
		short	iconId,
		short	stringId,
		short	pageId,
		short	growType = 0
	)

Appends a custom panel to an attribute settings dialog.

Parameters

refCon	[in] Unique reference number chosen for this panel
attr	[in] The attribute type that identifies the settings dialog
iconId	[in] Panel icon resource ID
stringId	[in] Title text to appear in the handler area of the panel
pageId	[in] Dialog resource ID of the tabpage
growType	[in] Grow type of the tab page: can be DG_DLG_NOGROW, DG_DLG_HGROW, DG_DLG_VGROW, or DG_DLG_HGROW | DG_DLG_VGROW. This parameter is optional, the default is DG_DLG_NOGROW.

Returns

• APIERR_BADPARS - The attr parameter is invalid.
• APIERR_NOTSUPPORTED - The attribute type does not support custom panels.
• NoError - The function has completed with success.

Remarks

This function appends a new panel into an attribute settings dialog. For more details refer to the general description of Custom Panels in Settings Dialogs.

ACAPI_AddOnIntegration_RegisterBuiltInLibrary()

GSErrCode __ACENV_CALL ACAPI_AddOnIntegration_RegisterBuiltInLibrary

(

void

)

Registers built-in library parts to be loaded.

Returns

• NoError - The function has completed with success.

Remarks

This function notifies the host application that your add-on has library parts compiled into the add-on as 'FILE' resources. The application will add the add-on module to the active libraries and the library parts will be available as read only objects. You can retrieve the unique ID of a built-in library part with the ACAPI_LibraryPart_GetBuiltInLibpartUnId goodie function.

Example

The StairMaker add-on has its own subtype template library part derived from the General Stair subtype.
In order to compile the library part into the add-on module, the library part should be copied among the localized resource files of the add-on, and there must be a reference to it in the .GRC file:

ACAPI_AddOnIntegration_RegisterClassificationVisibilityHandler()

GSErrCode __ACENV_CALL ACAPI_AddOnIntegration_RegisterClassificationVisibilityHandler

(

void

)

Tells Archicad that your add-on wants to modify classification visibility.

Returns

• NoError - The function has completed with success.

Remarks

This function should be called from the RegisterInterface routine in your add-on.

Example

//------------------------------------------------------
// Interface definitions
//------------------------------------------------------
GSErrCode __ACENV_CALL  RegisterInterface (void)
{
    GSErrCode err = ACAPI_MenuItem_RegisterMenu (32500, 32600, MenuCode_UserDef, MenuFlag_Default);
    if (err != NoError) {
        return err;
    }
 
    err = ACAPI_AddOnIntegration_RegisterClassificationVisibilityHandler ();
    if (err != NoError) {
        return err;
    }
 
    return NoError;
}   // RegisterInterface

ACAPI_AddOnIntegration_RegisterFileType()

GSErrCode __ACENV_CALL ACAPI_AddOnIntegration_RegisterFileType	(	Int32	refCon,
		GSType	ftype,
		GSType	fcreator,
		const char *	extname,
		short	iconResID,
		short	descStrResID,
		short	descStrResItemID,
		API_IOMethod	methodFlags
	)

Registers a file type for I/O type add-ons.

Parameters

refCon	[in] An arbitrary number which identifies this file type within the add-on.
ftype	[in] Macintosh file type (e.g. 'TEXT').
fcreator	[in] Creator on Macintosh (e.g. 'GSAC' for Archicad).
extname	[in] The extension used on Windows (e.g. "txt").
iconResID	[in] An optional icon resource ID. This icon appears in the Open/Save dialogs on the Macintosh.
descStrResID	[in] The resource ID of the resource containing the description of the file type.
descStrResItemID	[in] The item ID within the resource of the item containing the description of the file type, or 0 when specifying MIME type as well (see Remarks).
methodFlags	[in] Flags describing the Open/Save dialogs to add this file type to (see Remarks).

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 file type from the same add-on, appearing in different menus of the server application. The supplied refCon parameter should be the same in the ACAPI_AddOnIntegration_InstallFileTypeHandler function, which you have to call from your Initialize routine. The methodFlags parameter defines which dialogs' file type popup should contain the registered file type:

Flag	File Dialog
Open2DSupported	Open as 2D
Merge2DSupported	Merge
OpenLibPartSupported	Open Library Item
SaveAs2DSupported	Save as 2D
SaveAs3DSupported	Save as 3D
SaveAsFlySupported	Create Fly-Through/Sun Study
Import2DDrawingSupported	Import as Drawing

From API v4.2 you have the possibility to register the MIME type for the file as well. MIME (Multipurpose Internet Mail Extension) types are commonly accepted identifiers for certain media types. Specifying the MIME type makes the file format identification more accurate in the File Type Manager. If you decide to use this feature, you can do this in the following way:

• in the GRC file the string resource that describes the file format must contain two items: the descriptive name of the file format (e.g. "DWF File") the assigned MIME type (e.g. "model/vnd.dwf")
• the descriptive name of the file format (e.g. "DWF File")
• the assigned MIME type (e.g. "model/vnd.dwf")
• in the descStrResItemID parameter of the ACAPI_AddOnIntegration_RegisterFileType function you must pass 0

  Example

  In the localizable GRC file:

ACAPI_AddOnIntegration_RegisterInfoBoxPanel()

GSErrCode __ACENV_CALL ACAPI_AddOnIntegration_RegisterInfoBoxPanel	(	Int32	refCon,
		const API_ElemType &	tool,
		short	stringId,
		short	pageId,
		bool	visibleByDefault = false
	)

Appends a custom panel to the info box.

Since

Archicad 26

Parameters

refCon	[in] Unique reference number chosen for this panel
tool	[in] The element type that identifies the settings dialog
stringId	[in] Title text to appear in the handler area of the panel
pageId	[in] Dialog resource ID of the tabpage
visibleByDefault	[in] Show or hide the panel by default (optional parameter, false if omitted)

Returns

• APIERR_BADPARS - The passed element type is invalid.
• APIERR_BADID - The passed tool / variation parameter pair does not identify a valid toolbox item (including invisible tools).
• NoError - The function has completed with success.

Remarks

This function appends a new panel into an element settings dialog specified by tool. In order to get panel create/destroy events you must install the panel handler callback functions with ACAPI_AddOnIntegration_InstallPanelHandler. Compared to the ACAPI_AddOnIntegration_RegisterSettingsPanel function there is no need to specify icon resource ID. For more details refer to the general description of Custom Panels in Settings Dialogs.

ACAPI_AddOnIntegration_RegisterModulDataHandler()

GSErrCode __ACENV_CALL ACAPI_AddOnIntegration_RegisterModulDataHandler

(

void

)

Registers the add-on to be called for merging and converting its moduldata.

Returns

• NoError - The function has completed with success.

Remarks

Call this function from RegisterInterface to let Archicad know that the add-on has APIModulDataMergeHandlerProc and/or APIModulDataSaveOldFormatHandlerProc callback function implemented for merging and converting its modules. In order this functions to be called on the adequate event, the add-on needs to pass the function pointers to Archicad from Initialize with ACAPI_AddOnIntegration_InstallModulDataMergeHandler and ACAPI_AddOnIntegration_InstallModulDataSaveOldFormatHandler, respectively.

ACAPI_AddOnIntegration_RegisterNavigatorAddOnViewPointDataHandler()

GSErrCode __ACENV_CALL ACAPI_AddOnIntegration_RegisterNavigatorAddOnViewPointDataHandler

(

void

)

Registers the add-on to be called when Navigator AddOn viewpoints are merged, saved to older format, or converted from older format to current format.

Returns

• NoError - The function has completed with success.

Remarks

Call this function from RegisterInterface to let Archicad know that the AddOn has APINavigatorAddOnViewPointDataMergeHandlerProc, APINavigatorAddOnViewPointDataSaveOldFormatHandlerProc or APINavigatorAddOnViewPointDataConvertNewFormatHandlerProc callback function implemented for merging and converting its Navigator AddOn viewpoint data. In order these functions to be called on the adequate event, the AddOn needs to pass the function pointers to ACAPI_AddOnIntegration_InstallNavigatorAddOnViewPointDataMergeHandler, ACAPI_AddOnIntegration_InstallNavigatorAddOnViewPointDataSaveOldFormatHandler and ACAPI_AddOnIntegration_InstallNavigatorAddOnViewPointDataConvertNewFormatHandler respectively. Call these install functions in the AddOn's Initialize function.

ACAPI_AddOnIntegration_RegisterPublishFormat()

GSErrCode __ACENV_CALL ACAPI_AddOnIntegration_RegisterPublishFormat

(

const API_PublishFormatData &

formatData

)

Registers a publish format which can be used in publisher tree.

Parameters

formatData

[in] Stores parameters of the new publish format

Returns

• NoError - The function has completed with success.

Remarks

For further informations read the documentation of API_PublishFormatData structure.

Example

//------------------------------------------------------
// Interface definitions
//------------------------------------------------------
GSErrCode   __ACDLL_CALL    RegisterInterface (void)
{
    API_PublishFormatData formatData = {};
    formatData.mimeType = "text/Testxml";
    formatData.popUpText = "TestXML";
    formatData.fileExtText2D = "testFormat";
    formatData.fileExtText3D = "testFormat3d";
    formatData.windowTypes = { APIWind_AllID };
    formatData.singleFile = false;
    formatData.iconID = DG::Icon::NoIcon;
 
    return ACAPI_AddOnIntegration_RegisterPublishFormat (formatData);
}

ACAPI_AddOnIntegration_RegisterRequiredService()

GSErrCode __ACENV_CALL ACAPI_AddOnIntegration_RegisterRequiredService	(	const API_ModulID *	modulID,
		GSType	cmdID,
		Int32	cmdVersion
	)

Check the availability of an other add-on's command.

Parameters

modulID	[in] The modul ID of the add-on containing the required service.
cmdID	[in] The command identifier of the required service.
cmdVersion	[in] The command version of the required service.

Returns

• NoError - The function has completed with success.
• APIERR_GENERAL - The command isn't supported service.

Remarks

This function checks for the availability of an other add-on's command, without which it cannot run. The other add-on should provide all the necessary information. The function should be called from the RegisterInterface function of the add-on.

Example

//------------------------------------------------------
// Interface definitions
//------------------------------------------------------
GSErrCode __ACENV_CALL  RegisterInterface (void)
 
{
    GSErrCode   err;
 
    //
    // Register command services
    //
    err = ACAPI_AddOnIntegration_RegisterRequiredService ('DWFO', 4L);
 
    return err;
}               // RegisterInterface

ACAPI_AddOnIntegration_RegisterSettingsObserver()

GSErrCode __ACENV_CALL ACAPI_AddOnIntegration_RegisterSettingsObserver

(

const API_ElemType &

tool

)

Create an observer to an element settings dialog.

Since

Archicad 26

Parameters

tool	[in] The element type that identifies the settings dialog

Returns

• APIERR_BADPARS - The passed element type is invalid.
• APIERR_BADID - The passed tool does not identify a valid toolbox item (including invisible tools).
• NoError - The function has completed with success.

Remarks

This function creates an observer for an element settings dialog specified by tool. In order to get settings dialog create or destroy events you must install the settings handler callback functions with ACAPI_AddOnIntegration_InstallSettingsHandler. This function should be called from your add-on's RegisterInterface routine. You can register more than one observers from the same add-on for different settings dialogs. From version 26 the tool and variation parameters were merged into a single API_ElemType parameter.

Example

Refer to the Panel_Test
 
example project of the API Development Kit.

ACAPI_AddOnIntegration_RegisterSettingsPanel()

GSErrCode __ACENV_CALL ACAPI_AddOnIntegration_RegisterSettingsPanel	(	Int32	refCon,
		const API_ElemType &	tool,
		short	iconId,
		short	stringId,
		short	pageId,
		short	growType = 0,
		bool	visibleByDefault = false
	)

Appends a custom panel to an element settings dialog.

Since

Archicad 26

Parameters

refCon	[in] Unique reference number chosen for this panel
tool	[in] The element type that identifies the settings dialog
iconId	[in] Panel icon resource ID
stringId	[in] Title text to appear in the handler area of the panel
pageId	[in] Dialog resource ID of the tabpage
growType	[in] Grow type of the tab page: can be DG_DLG_NOGROW, DG_DLG_HGROW, DG_DLG_VGROW, or DG_DLG_HGROW | DG_DLG_VGROW. This parameter is optional, the default is DG_DLG_NOGROW.
visibleByDefault	[in] Show or hide the panel by default (optional parameter, false if omitted)

Returns

• APIERR_BADPARS - The passed element type is invalid.
• APIERR_BADID - The passed tool / variation parameter pair does not identify a valid toolbox item (including invisible tools).
• NoError - The function has completed with success.

Remarks

This function appends a new panel into an element settings dialog specified by tool and variation. In order to get panel create/destroy events you must install the panel handler callback functions with ACAPI_AddOnIntegration_InstallPanelHandler. For more details refer to the general description of Custom Panels in Settings Dialogs. From version 26 the tool and variation parameters were merged into a single API_ElemType parameter.

Example

Resources in the GRC file:

ACAPI_KeepInMemory()

void __ACENV_CALL ACAPI_KeepInMemory

(

bool

keepIn

)

Instructs the host application to keep the add-on in the memory after execution.

Parameters

keepIn

[in] If true the add-on will stay in the memory.

Returns

Remarks

This function is used to keep the add-on in the memory. You should call this function with true each time your add-on is called to stay in memory. The values of all your global variables stay the same between the calls to your add-on. Also, when in memory, the Initialize and the FreeData functions of your add-on are not called. See more about this topic at the Control the Load/Unload Mechanism part of the Tips and Tricks.

ACAPI_LibraryPart_InstallESYMHandler()

GSErrCode __ACENV_CALL ACAPI_LibraryPart_InstallESYMHandler	(	GSType	signature,
		APIESYMCommandProc *	handlerProc
	)

Installs a callback for handling external symbols.

Parameters

signature	[in] A four-character identifier of the external symbol.
handlerProc	[in] The callback function to handle the creation and the editing of the external symbol.

Returns

• NoError - The function has completed with success.

Remarks

This function should be called in the Initialize function of your add-on.

Example

// -----------------------------------------------------------------------------
// Called when the add-on has been loaded into memory
// -----------------------------------------------------------------------------
GSErrCode __ACENV_CALL  Initialize (void)
 
{
    GSErrCode    err = NoError;
 
    err = ACAPI_LibraryPart_InstallESYMHandler ('ABCD', APIESYMCommandProc);
 
    return err;
}   // Initialize

ACAPI_LibraryPart_RegisterESYM()

GSErrCode __ACENV_CALL ACAPI_LibraryPart_RegisterESYM	(	GSType	signature,
		API_LibTypeID	typeID,
		short	stringResID
	)

Registers an external symbol type with Archicad.

Parameters

signature	[in] Unique identifier of the new symbol type (a four-character ID).
typeID	[in] Type of the new symbol (can be API_ObjectID, API_LampID, API_WindowID, or API_DoorID).
stringResID	[in] Resource containing the description of the new symbol type.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - Invalid symbol type.

Remarks

This function should be called from your add-on's RegisterInterface routine. More than one external symbol can be registered from one add-on. After registration you should also install a callback function with ACAPI_LibraryPart_InstallESYMHandler in your Initialize function, which will handle the events coming from Archicad.

Example

//------------------------------------------------------
// Interface definitions
//------------------------------------------------------
GSErrCode __ACENV_CALL  RegisterInterface (void)
{
    GSErrCode   err;
 
    // Register ESYM
    err = ACAPI_LibraryPart_RegisterESYM ('GRPH', API_LampID, 32611);
 
    return err;
}               /* RegisterInterface */

ACAPI_LibraryPart_RegisterSubtype()

GSErrCode __ACENV_CALL ACAPI_LibraryPart_RegisterSubtype	(	GSType	signature,
		short	templateFileResID,
		bool	transparentNode,
		short	stringResID,
		short	smallIconResID,
		short	largeIconResID,
		API_TBoxGroup	toolGroupId,
		API_TBoxEnabled	enableFlags,
		short	defaultsResID
	)

Registers a new library part subtype.

Parameters

signature	[in] A four-character identifier of this library part subtype
templateFileResID	[in] 'FILE' resource ID of the subtype template library part compiled into the add-on
transparentNode	[in] Objects of this subtype can be shown on higher ancestry levels as well
stringResID	[in] Resource ID of the library part subtype description string
smallIconResID	[in] Resource ID of the small-sized toolbox (toolbar) item icon
largeIconResID	[in] Resource ID of the large-sized toolbox item icon
toolGroupId	[in] Toolbox item position
enableFlags	[in] Enable or disable the subtype tool depending on the active window
defaultsResID	[in] ID of the 'ACP0' resource that contains the element default values for this subtype

Returns

• APIERR_BADPARS - templateFileResID refers to an invalid 'FILE' resource or the built-in library part cannot be accepted as subtype template.
• NoError - The function has completed with success.

Remarks

This function registers a new library part subtype. In order to have an own element subtype the add-on must contain a built-in library part in its reource module. This library part will be loaded into the active libraries, and become a new node in the ancestry tree. The new element type will be identified with the signature identifier chosen by the add-on's writer. The signature should be unique in order to avoid collisions. You may pass 0 in the signature parameter if you do not need a new element type but a single subtype node. The subtype can appear in the toolbox as an external tool, and also on the Windows toolbar. In this case you must pass two valid icon resource IDs in the smallIconResID and the largeIconResID parameters. The size of the icons should be 16x16 and 30x21 pixels respectively. You can specify the position of the subtype item inserted into the toolbox with the toolGroupId parameter as follows:

API_TBoxGroup	Meaning
TBoxGroup_Root	The subtype tool item will be appended to the group of model element tools
TBoxGroup_Objects	The subtype tool item will be added to the object tools
TBoxGroup_Openings	The subtype tool item will be added to the window/door tools

You can control the availability of the subtype tool in the toolbox by setting the enableFlags bits:

API_TBoxEnabled	The subtype tool is enabled
API_TBoxEnabled_FloorPlan	on floor plan window
API_TBoxEnabled_ModelSection	on model type section and elevation windows
API_TBoxEnabled_DrawingSection	on drawing type section and elevation windows
API_TBoxEnabled_3D	on 3D model window
API_TBoxEnabled_Detail	on detail window
API_TBoxEnabled_Layout	on layout and master layout windows
API_TBoxEnabled_Worksheet	on worksheet window
API_TBoxEnabled_ModelInteriorElevation	on model type interior elevation windows
API_TBoxEnabled_DrawingInteriorElevation	on drawing type interior elevation windows

If you want to register your subtype tool without appearing in the toolbox, pass 0 for both the smallIconResID and the largeIconResID parameters. If you register a subtype tool you should define the factory default values for this element type in an 'ACP0' resource. The element default will be initialized with these parameters when no preferences data is stored. The structure of this resource is shown at the example below. The resource ID should be passed in the defaultsResID parameter. Learn more about this topic at the general description of Library Part Subtypes.

Example

Resources in the .GRC file:

ACAPI_MenuItem_InstallMenuHandler()

GSErrCode __ACENV_CALL 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 __ACENV_CALL  Initialize (void)
 
{
    GSErrCode    err = NoError;
 
    err = ACAPI_MenuItem_InstallMenuHandler (32500, APIMenuCommandProc);
 
    return err;
}   // Initialize

ACAPI_MenuItem_RegisterMenu()

GSErrCode __ACENV_CALL 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:

ACAPI_Property_InstallPropertyObjectHandler()

GSErrCode __ACENV_CALL ACAPI_Property_InstallPropertyObjectHandler	(	short	strResID,
		APIPropertyObjectCommandProc *	propertyCommandProc
	)

Installs the property handler function for the given menu item.

Parameters

strResID	[in] The string resource ID you install the property handler for.
propertyCommandProc	[in] The property command handler function.

Returns

• NoError - The function has completed with success.

Remarks

The string resource will appear in Archicad's dialogs. This function should be called from the Initialize function of the add-on, after registering the property handler with ACAPI_Property_RegisterPropertyObjectHandler.

Example

//------------------------------------------------------
// Called after the add-on has been loaded into memory
//------------------------------------------------------
GSErrCode __ACENV_CALL  Initialize (void)
{
    ACAPI_MenuItem_InstallMenuHandler (MenuResId, Callback_Check_AVA_OR_DIN_MenuItem);
    ACAPI_Property_InstallPropertyObjectHandler (PropertyResId, Callback_Property);
 
    return NoError;
}

ACAPI_Property_InstallPropertyVisibilityHandler()

GSErrCode __ACENV_CALL ACAPI_Property_InstallPropertyVisibilityHandler

(

APIPropertyVisibilityHandlerProc *

handlerProc

)

Installs the property visibility handler function.

Parameters

handlerProc

[in] The property visibility handler function.

Returns

• NoError - The function has completed with success.

Remarks

This function should be called from the Initialize function of the add-on, after registering the property handler with ACAPI_Property_RegisterPropertyVisibilityHandler.

Example

//------------------------------------------------------
// Called after the add-on has been loaded into memory
//------------------------------------------------------
GSErrCode __ACENV_CALL  APIMenuCommandProc_Main   (const API_MenuParams *menuParams);
bool      __ACENV_CALL  PropertyVisibilityHandler (API_PropertyVisibilityMode visibilityMode, const GS::Array<API_Guid>& classificationGuids, const API_Guid& propertyDefinitionGuid);
 
GSErrCode __ACENV_CALL  Initialize (void)
{
    GSErrCode err = ACAPI_MenuItem_InstallMenuHandler (32500, APIMenuCommandProc_Main);
    if (err != NoError) {
        return err;
    }
 
    err = ACAPI_Property_InstallPropertyVisibilityHandler (PropertyVisibilityHandler);
    if (err != NoError) {
        return err;
    }
 
    ACAPI_KeepInMemory (true);
    return NoError;
}

ACAPI_Property_RegisterPropertyObjectHandler()

GSErrCode __ACENV_CALL ACAPI_Property_RegisterPropertyObjectHandler

(

short

assignStrResID

)

Registers a property handler.

Parameters

assignStrResID

[in] The string resource ID, which will be used in Archicad's dialogs.

Returns

• NoError - The function has completed with success.

Remarks

This function should be called from the RegisterInterface routine in your add-on.

Example

//------------------------------------------------------
// Interface definitions
//------------------------------------------------------
GSErrCode __ACENV_CALL  RegisterInterface (void)
{
    ACAPI_MenuItem_RegisterMenu (MenuResId, MenuTextResId, MenuCode_Calculate, MenuFlag_Default);
    ACAPI_Property_RegisterPropertyObjectHandler (PropertyResId);
 
    return NoError;
}   // RegisterInterface

ACAPI_Property_RegisterPropertyVisibilityHandler()

GSErrCode __ACENV_CALL ACAPI_Property_RegisterPropertyVisibilityHandler

(

void

)

Tells Archicad that your add-on wants to modify property visibility.

Returns

• NoError - The function has completed with success.

Remarks

This function should be called from the RegisterInterface routine in your add-on.

Example

//------------------------------------------------------
// Interface definitions
//------------------------------------------------------
GSErrCode __ACENV_CALL  RegisterInterface (void)
{
    GSErrCode err = ACAPI_MenuItem_RegisterMenu (32500, 32600, MenuCode_UserDef, MenuFlag_Default);
    if (err != NoError) {
        return err;
    }
 
    err = ACAPI_Property_RegisterPropertyVisibilityHandler ();
    if (err != NoError) {
        return err;
    }
 
    return NoError;
}   // RegisterInterface

ACAPI_RegisterModelessWindow()

GSErrCode __ACENV_CALL ACAPI_RegisterModelessWindow	(	Int32	referenceID,
		APIPaletteControlCallBackProc *	callBackProc,
		GSFlags	controlFlags,
		const API_Guid &	paletteGuid = APINULLGuid
	)

Registers a modeless palette in the API.

Parameters

referenceID	[in] Arbitrary number to uniquely identify your modeless palette. (You can use the resource ID if you wish.)
callBackProc	[in] Callback procedure for handling special API messages. It is called by the API, independently of DG.
controlFlags	[in] Define the behavior of the palette above different Archicad windows (plan, 3D, section, layout), and in case of selection.
paletteGuid	[in] A unique identifier for recording the state of the palette in the Work Environment. Optional parameter, can be omitted.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The passed referenceID has already been used.
• APIERR_MEMFULL - No free memory was available for the new entry.

Remarks

Modeless palettes now can be opened with the normal DG functions (either DGModelessInit, or DG::Palette). However, the API should know about the existence of an add-on's palette, so that it could send special messages to the palette (see APIPaletteControlCallBackProc). This function registers the add-on's modeless window with the API; call it from the Initialize function. API 11 introduced new values for the controlFlags parameter: API_PalEnabled_Worksheet, API_PalEnabled_Elevation, and API_PalEnabled_InteriorElevation.

Example

GSErrCode   __ACENV_CALL Initialize (void)
{
    GSErrCode err = ACAPI_MenuItem_InstallMenuHandler (DGTEST_MENU_STRINGSID, MenuCommandHandler);
 
    // If the palette is constructed and registered, the add-on will be not unloaded from the memory while Archicad runs.
    ACAPI_RegisterModelessWindow (OwnerDrawnListBoxPalette::ODLBPaletteRefId (),
                                  OwnerDrawnListBoxPalette::PaletteAPIControlCallBack,
                                  API_PalEnabled_FloorPlan + API_PalEnabled_Section + API_PalEnabled_Elevation +
                                  API_PalEnabled_InteriorElevation + API_PalEnabled_3D +
                                  API_PalEnabled_Detail + API_PalEnabled_Worksheet + API_PalEnabled_Layout +
                                  API_PalEnabled_DocumentFrom3D + API_PalEnabled_ModelCompare, GSGuid2APIGuid (OwnerDrawnListBoxPalette::ODLBPaletteGuid ()));
 
    if (err != NoError)
        DBPrintf ("DG_Test:: Initialize() ACAPI_MenuItem_InstallMenuHandler failed\n");
 
    return err;
}       // Initialize